简介
本技术文档面向 DouPHP 的“银行支付插件”，聚焦传统银行支付渠道的集成方式，涵盖银联在线支付、连连支付等。文档从系统架构、数据流、处理逻辑、错误处理、性能与安全等维度进行系统化说明，并提供关键流程的时序图与流程图，帮助开发者快速理解并正确接入银行支付能力。
银行支付的特点包括：
- 需要商户证书或密钥对（如 RSA 私钥），用于签名与验签
- 报文格式严格，字段命名与顺序有明确要求
- 严格的签名验证机制，防止篡改与重放
- 典型流程包含前置检查、订单提交、银行页面跳转、异步通知、同步回调、对账文件处理等环节
项目结构
DouPHP 将不同支付渠道以插件形式组织，每个插件提供统一的 Provider 与 Service 接口，并通过 manifest 注册到支付插件组。
graph TB
subgraph "插件: 网银支付(bankpay)"
BP["BankpayProvider"]
BS["BankpayService"]
BM["manifest.php"]
SDKB["sdk/lib/*"]
end
subgraph "插件: 连连支付(lianlianpay)"
LP["LianlianpayProvider"]
LS["LianlianpayService"]
LM["manifest.php"]
SDKL["sdk/lib/*"]
end
BM --> BP
BP --> BS
BS --> SDKB
LM --> LP
LP --> LS
LS --> SDKL核心组件
- 插件提供者（Provider）：实现统一支付插件接口，暴露 pluginId、meta、start、notify、finish 等方法，负责参数透传与路由分发。
- 业务服务（Service）：封装具体银行的请求构造、签名、表单生成、回调验签、订单状态推进、邮件通知等核心逻辑。
- SDK 库：各银行提供的提交与通知校验类，负责报文组装、签名计算、证书加载与网络通信。
架构总览
下图展示了用户下单后，通过 DouPHP 支付插件调用银行网关并完成支付的核心交互流程。
sequenceDiagram
participant U as "用户"
participant F as "前端/订单页"
participant P as "支付插件(Provider)"
participant S as "支付服务(Service)"
participant G as "银行网关"
participant N as "异步通知回调"
participant R as "同步回调页面"
U->>F : 发起支付
F->>P : start(request)
P->>S : start(request)
S->>G : 构建表单并提交(含签名)
G-->>U : 展示银行收银台
U->>G : 完成支付
G-->>N : 异步通知(POST)
N->>S : notify(payload)
S->>S : 验签与解析
S-->>N : success/fail
G-->>R : 同步回调(GET/POST)
R->>S : finish(payload)
S->>S : 验签与解析
S-->>R : 返回结果页详细组件分析
网银支付（支付宝网银支付）
- 插件元信息与配置：包含商户号、安全校验码、邮箱等字段。
- 订单提交：构造标准即时到账参数，生成自动提交的 HTML 表单，跳转到银行收银台。
- 异步通知：使用 SDK 的 AlipayNotify 进行验签，校验交易状态后标记支付成功，并记录原始报文。
- 同步回调：同样进行验签，成功后发送邮件通知，并返回订单页。
classDiagram
class BankpayProvider {
+pluginId() string
+meta() array
+start(PaymentRequest) string
+notify(PaymentCallbackPayload) string
+finish(PaymentCallbackPayload) string
}
class BankpayService {
-paymentService
+start(PaymentRequest) string
+notify(PaymentCallbackPayload) string
+finish(PaymentCallbackPayload) string
-buildConfig() array
-buildParameter(PaymentRequest) array
-encodeRaw(data) string
}
BankpayProvider --> BankpayService : "委托调用"网银支付：订单提交流程
flowchart TD
Start(["开始"]) --> CheckCfg["检查配置是否完整"]
CheckCfg --> |不完整| ErrCfg["抛出配置异常"]
CheckCfg --> |完整| BuildParam["构建支付参数"]
BuildParam --> GenForm["生成自动提交表单"]
GenForm --> Redirect["浏览器自动提交至银行网关"]
Redirect --> End(["结束"])
ErrCfg --> End连连支付
- 插件元信息与配置：包含商户编号、RSA 私钥、安全检验码等。
- 订单提交：构造连连支付参数，生成表单并提交至连连网关。
- 异步通知：使用 SDK 的 LLpayNotify 进行验签，校验 result_pay 为 SUCCESS 后标记支付成功。
- 同步回调：验签通过后解析 res_data JSON，标记成功并发送邮件通知。
classDiagram
class LianlianpayProvider {
+pluginId() string
+meta() array
+start(PaymentRequest) string
+notify(PaymentCallbackPayload) string
+finish(PaymentCallbackPayload) string
}
class LianlianpayService {
-paymentService
+start(PaymentRequest) string
+notify(PaymentCallbackPayload) string
+finish(PaymentCallbackPayload) string
-buildConfig() array
-encodeRaw(data) string
}
LianlianpayProvider --> LianlianpayService : "委托调用"连连支付：回调处理流程
flowchart TD
Start(["收到回调"]) --> Verify["SDK 验签"]
Verify --> |失败| Fail["返回 fail"]
Verify --> |成功| Parse["解析响应数据"]
Parse --> CheckStatus{"result_pay == SUCCESS ?"}
CheckStatus --> |否| ReturnUser["返回用户订单页"]
CheckStatus --> |是| MarkSuccess["标记支付成功"]
MarkSuccess --> NotifyMail["发送支付成功邮件"]
NotifyMail --> End(["结束"])
Fail --> End
ReturnUser --> End依赖关系分析
- Provider 仅做路由与参数透传，实际业务逻辑集中在 Service。
- Service 依赖 PaymentService 推进订单状态机，依赖 SDK 完成签名与网络通信。
- 各插件通过 manifest 声明 provider 类名，便于框架动态加载。
graph LR
A["BankpayProvider"] --> B["BankpayService"]
B --> C["PaymentService"]
B --> D["alipay_submit.class.php"]
B --> E["alipay_notify.class.php"]
F["LianlianpayProvider"] --> G["LianlianpayService"]
G --> C
G --> H["llpay_submit.class.php"]
G --> I["llpay_notify.class.php"]性能与可靠性
- 异步优先：支付成功以异步通知为准，同步回调仅用于用户体验与二次确认。
- 幂等性：在标记支付成功前，应基于 payment_sn 进行幂等判断，避免重复入账。
- 超时与重试：对银行网关的网络请求需设置合理超时；对异步通知建议支持幂等重试。
- 日志与审计：记录请求与响应的摘要信息（脱敏），便于问题定位。
- 资源释放：确保在异常路径下关闭连接与释放资源。
故障排查指南
- 网络超时
- 现象：提交表单或回调无响应
- 排查：检查服务器出站白名单、防火墙策略、DNS 解析；调整超时时间；查看银行网关维护公告
- 证书/密钥问题
- 现象：验签失败、签名不匹配
- 排查：核对 RSA 私钥格式与权限；确认证书链有效；检查 key 与 sign_type 配置；比对银行测试/生产环境差异
- 报文格式错误
- 现象：银行返回参数缺失或非法
- 排查：核对必填字段（如 out_trade_no/no_order、金额、字符集）；确认 UTF-8 编码；检查特殊字符转义
- 回调未触发
- 现象：支付成功但订单未更新
- 排查：确认 notify_url 可被外网访问；检查 Web 服务器日志；验证验签逻辑；确认幂等与状态机推进逻辑
- 对账不一致
- 现象：本地订单与银行流水不符
- 排查：启用对账任务；核对交易号与金额；关注退款与部分退款场景；建立差异告警
结论
DouPHP 的银行支付插件通过 Provider/Service/Sdk 的分层设计，实现了与多家银行渠道的统一接入。网银支付与连连支付均遵循“提交—跳转—异步通知—同步回调”的标准流程，并在 Service 层完成验签、状态推进与通知。生产部署时，应重点关注证书管理、IP 白名单、超时与重试、幂等性与对账等关键环节，以确保资金安全与系统稳定。
附录：配置项说明
- 网银支付（bankpay）
- 商户号/合作者身份（partner）
- 安全校验码（key）
- 支付宝账户（seller_email）
- 其他由 SDK 内部使用的证书与传输协议配置
- 连连支付（lianlianpay）
- 商户编号（oid_partner）
- 商户私钥（rsa_private_key）
- 安全检验码（key）
- 网关地址、版本、字符集、传输协议等由 Service 默认配置