kami_gateway/.qoder/repowiki/zh/content/第三方支付渠道集成.md

第三方支付渠道集成

**本文档引用的文件** - [supplier_interface.go](file://internal/service/supplier/supplier_interface.go) - [apple.go](file://internal/service/supplier/third_party/apple.go) - [jd.go](file://internal/service/supplier/third_party/jd.go) - [apple_shark.go](file://internal/service/supplier/third_party/apple_shark.go) - [batch_six.go](file://internal/service/supplier/third_party/batch_six.go) - [eggplant.go](file://internal/service/supplier/third_party/eggplant.go)

目录

1. 介绍
2. 核心接口定义
3. 核心方法实现分析
4. HTTP请求与响应处理
5. 错误处理与重试机制
6. 供应商认证机制
7. API限流与数据格式
8. 新供应商集成步骤
9. 单元测试编写
10. 常见陷阱与最佳实践

介绍

本文档旨在为开发者提供一份详细的第三方支付渠道集成指南。通过分析现有支付供应商（如Apple、京东）的实现，指导开发者如何创建新的支付供应商集成。文档涵盖了从接口实现、HTTP通信、错误处理到系统注册的完整流程。

核心接口定义

所有第三方支付供应商必须实现PayInterface接口，该接口定义了支付系统所需的核心功能。

classDiagram
class PayInterface {
+Scan(context.Context, order.OrderInfo, road.RoadInfo, merchant.MerchantInfo) ScanData
+PayNotify()
+PayQuery(order.OrderInfo, road.RoadInfo) bool
+PayQueryV2(order.OrderInfo, road.RoadInfo) supply_model.MsgModel
+PayFor(payfor.PayforInfo) string
+PayForNotify() string
+PayForQuery(payfor.PayforInfo) (string, string)
+BalanceQuery(road.RoadInfo) float64
+HasDependencyHTML() bool
}
class ScanData {
+Supplier string
+PayType string
+OrderNo string
+BankNo string
+OrderPrice string
+FactPrice string
+Status string
+PayUrl string
+Msg string
+ReturnData string
+UpStreamOrderNo string
}

图示来源

• supplier_interface.go

本节来源

• supplier_interface.go

核心方法实现分析

Scan方法实现

Scan方法是支付流程的起点，负责处理扫码支付请求。通过对比Apple和京东的实现，可以发现通用的处理模式。

sequenceDiagram
participant 开发者 as 开发者
participant Scan as Scan方法
participant SendCard as SendCard方法
participant 供应商 as 第三方供应商
开发者->>Scan : 发起支付请求
Scan->>Scan : 解析订单数据
Scan->>SendCard : 调用SendCard发送请求
SendCard->>供应商 : 发送支付请求
供应商-->>SendCard : 返回响应
SendCard-->>Scan : 返回处理结果
Scan-->>开发者 : 返回支付结果

图示来源

• apple.go
• jd.go

本节来源

• apple.go
• jd.go

PayNotify方法实现

PayNotify方法处理来自第三方供应商的支付回调通知，是确保交易状态同步的关键。

sequenceDiagram
participant 供应商 as 第三方供应商
participant PayNotify as PayNotify方法
participant 订单服务 as 订单服务
participant 系统 as 支付系统
供应商->>PayNotify : 发送回调通知
PayNotify->>PayNotify : 验证订单存在性
PayNotify->>订单服务 : 获取订单信息
订单服务-->>PayNotify : 返回订单信息
PayNotify->>系统 : 更新订单状态
系统-->>PayNotify : 返回处理结果
PayNotify-->>供应商 : 返回确认响应

图示来源

• apple.go
• jd.go

本节来源

• apple.go
• jd.go

PayQuery方法实现

PayQuery方法用于查询订单状态，确保交易的最终一致性。

sequenceDiagram
participant 系统 as 支付系统
participant PayQuery as PayQuery方法
participant 供应商 as 第三方供应商
系统->>PayQuery : 发起查询请求
PayQuery->>PayQuery : 构建查询参数
PayQuery->>供应商 : 发送查询请求
供应商-->>PayQuery : 返回查询结果
PayQuery->>PayQuery : 解析响应数据
PayQuery-->>系统 : 返回查询结果

图示来源

• apple.go
• jd.go

本节来源

• apple.go
• jd.go

HTTP请求与响应处理

请求构建与发送

支付供应商通过HTTP请求与第三方系统通信，使用httplib库进行请求构建和发送。

flowchart TD
Start([开始]) --> 构建参数["构建请求参数"]
构建参数 --> 设置URL["设置请求URL"]
设置URL --> 设置超时["设置超时时间"]
设置超时 --> 设置头["设置请求头"]
设置头 --> 序列化["序列化请求体"]
序列化 --> 发送请求["发送HTTP请求"]
发送请求 --> 处理响应["处理响应数据"]
处理响应 --> 结束([结束])

图示来源

• apple.go
• jd.go

本节来源

• apple.go
• jd.go

响应解析与处理

收到响应后，系统需要解析JSON数据并根据业务逻辑进行处理。

flowchart TD
接收响应([接收HTTP响应]) --> 检查错误["检查网络错误"]
检查错误 --> 解析JSON["解析JSON响应"]
解析JSON --> 验证结构["验证响应结构"]
验证结构 --> 提取数据["提取业务数据"]
提取数据 --> 处理状态["处理状态码"]
处理状态 --> 返回结果["返回处理结果"]

本节来源

• apple.go
• jd.go

错误处理与重试机制

错误处理策略

系统采用分层的错误处理策略，确保异常情况下的稳定性。

flowchart TD
发生错误([发生错误]) --> 记录日志["记录错误日志"]
记录日志 --> 分类错误["分类错误类型"]
分类错误 --> 网络错误{"网络错误?"}
网络错误 --> |是| 重试["执行重试逻辑"]
网络错误 --> |否| 业务错误{"业务错误?"}
业务错误 --> |是| 返回用户["返回用户友好信息"]
业务错误 --> |否| 系统错误["返回系统错误"]
重试 --> 检查重试次数["检查重试次数"]
检查重试次数 --> 达到上限{"达到上限?"}
达到上限 --> |是| 返回失败["返回失败"]
达到上限 --> |否| 重新发送["重新发送请求"]

本节来源

• apple.go
• jd.go

重试机制实现

通过req.Retries(3)设置重试次数，确保网络不稳定时的请求可靠性。

本节来源

• apple.go

供应商认证机制

签名生成

供应商通过特定算法生成签名，确保请求的完整性和安全性。

flowchart TD
开始([开始]) --> 拼接参数["拼接参数字符串"]
拼接参数 --> 生成签名["生成MD5签名"]
生成签名 --> 添加签名["将签名添加到请求参数"]
添加签名 --> 发送请求["发送带签名的请求"]

本节来源

• apple.go
• jd.go

API限流与数据格式

限流处理

系统通过配置和超时设置来应对API限流。

flowchart TD
发送请求([发送请求]) --> 设置超时["设置30秒超时"]
设置超时 --> 检查响应["检查响应时间"]
检查响应 --> 超时{"超时?"}
超时 --> |是| 重试["执行重试"]
超时 --> |否| 正常处理["正常处理响应"]

本节来源

• apple.go
• jd.go

数据格式规范

所有请求和响应都遵循统一的JSON格式规范。

本节来源

• apple.go
• jd.go

新供应商集成步骤

创建供应商结构体

创建新的供应商实现结构体，继承必要的控制器。

flowchart TD
创建结构体([创建结构体]) --> 继承Controller["继承web.Controller"]
继承Controller --> 实现接口["实现PayInterface接口"]
实现接口 --> 添加字段["添加供应商特定字段"]

本节来源

• apple.go
• jd.go

实现核心方法

按照接口定义实现所有必需的方法。

本节来源

• supplier_interface.go

添加到系统

将新的供应商实现文件添加到third_party目录，并在系统中注册。

本节来源

• apple.go
• jd.go

单元测试编写

参考现有的*_test.go文件编写单元测试，确保代码质量。

本节来源

• apple_test.go
• jd_test.go

常见陷阱与最佳实践

交易幂等性保证

通过订单号和状态检查确保交易的幂等性。

flowchart TD
接收请求([接收支付请求]) --> 检查订单["检查订单是否存在"]
检查订单 --> 已存在{"订单已存在?"}
已存在 --> |是| 检查状态["检查订单状态"]
检查状态 --> 已完成{"已完成?"}
已完成 --> |是| 返回成功["返回成功"]
已完成 --> |否| 处理请求["继续处理请求"]
已存在 --> |否| 创建订单["创建新订单"]

本节来源

• apple.go
• jd.go

最佳实践总结

1. 始终记录详细的日志信息
2. 实现完整的错误处理
3. 遵循统一的代码风格
4. 充分测试边界情况
5. 确保交易的幂等性

本节来源

• apple.go
• jd.go