20 KiB
pay-bridge Approach Design
| 字段 | 内容 |
|---|---|
| 文档版本 | v1.0 |
| 创建日期 | 2026-02-27 |
| 状态 | 草稿 |
1. 整体架构分层
pay-bridge 采用四层架构，自上而下分别为：API 接入层、业务逻辑层、渠道适配层、基础设施层。
┌──────────────────────────────────────────────────────────────┐
│ 下游业务系统 │
│ (电商 / SaaS / 多商户平台) │
└────────────────────────┬─────────────────────────────────────┘
│ REST/JSON over HTTPS
┌────────────────────────▼─────────────────────────────────────┐
│ Layer 1: API 接入层 │
│ • 鉴权中间件（appId + appSecret 签名验证） │
│ • 请求路由（Gin Router） │
│ • 参数校验（binding/validator） │
│ • 限流中间件（Redis Token Bucket） │
│ • 统一响应格式封装 / 错误码映射 │
├──────────────────────────────────────────────────────────────┤
│ Layer 2: 业务逻辑层 │
│ • 交易服务（统一下单、查询、退款、关单） │
│ • 通知服务（接收上游回调、通知下游、重试调度） │
│ • 分润服务（分账计算、分润触发、退款回退） │
│ • 服务费服务（费率计算、自动扣收） │
│ • 收款匹配服务（入账通知接收、三维度匹配引擎） │
│ • 对账服务（账单拉取、逐笔比对、差异报告） │
│ • 商户进件服务（进件提交、审核状态跟踪） │
│ • 微信通知服务（模板消息推送、绑定管理） │
│ • 订单编码服务（按 app_id 隔离的序列号生成） │
├──────────────────────────────────────────────────────────────┤
│ Layer 3: 渠道适配层 │
│ • 渠道适配器接口（统一 interface 定义） │
│ • 汇元支付适配器（RSA/MD5 签名、RSA+3DES 加解密） │
│ • 渠道工厂（根据 channel_code 动态路由到对应适配器） │
│ • 渠道配置仓储（密钥、证书的加密读取） │
├──────────────────────────────────────────────────────────────┤
│ Layer 4: 基础设施层 │
│ • MySQL 8.0（交易持久化、配置存储） │
│ • Redis（幂等 Key 缓存、分布式锁、延迟队列） │
│ • 定时任务调度器（cron 对账、状态补偿） │
│ • 结构化日志（zerolog / zap） │
└──────────────────────────────────────────────────────────────┘
│ 渠道私有协议
┌────────────────────────▼─────────────────────────────────────┐
│ 上游支付渠道 │
│ 汇元支付 │ (预留微信直连) │ (预留支付宝直连) │
└──────────────────────────────────────────────────────────────┘
分层理由：
- API 接入层与业务逻辑层分离，使鉴权、限流、协议转换等横切关注点集中处理，业务层保持纯粹。
- 渠道适配层独立为一层，而非嵌入业务层，使新增渠道无需改动任何业务代码，只新增一个适配器实现。
- 基础设施层统一封装，方便后续将 Redis 替换为其他实现，或扩展消息队列。
2. 核心模块划分
| 模块 | 职责 | 关键依赖 |
|---|---|---|
| 交易核心（Trade） | 统一下单、查询、关单，维护订单状态机 | MySQL、Redis（幂等）、渠道适配层 |
| 退款（Refund） | 退款请求、退款状态跟踪、退款查询 | MySQL、渠道适配层 |
| 异步通知（Notify） | 接收上游回调验签、更新状态、通知下游、重试调度 | Redis 延迟队列、MySQL |
| 分润（ProfitSharing） | 分润配置读取、分账调用、退款回退分润 | 渠道适配层、MySQL |
| 服务费（ServiceFee） | 费率配置读取、服务费计算、分账划转 | 渠道适配层、MySQL |
| 收款匹配（PaymentMatch） | 接收固定账户入账通知、三维度匹配引擎 | MySQL、通知模块 |
| 对账（Reconciliation） | T+1 账单拉取、逐笔比对、差异入库 | 渠道适配层、MySQL |
| 商户进件（Merchant） | 进件提交、审核跟踪、状态异常检测 | 渠道适配层、MySQL |
| 微信通知（WechatNotify） | 微信绑定管理、模板消息推送 | 微信公众号 API、MySQL |
| 订单编码（Sequence） | 按 app_id 隔离的订单号生成 | MySQL（悲观锁序列）或 Redis（原子自增） |
| 渠道适配（Channel） | 统一 interface、汇元适配器实现、渠道工厂 | 无外部依赖（纯逻辑） |
| 应用鉴权（Auth） | appId + appSecret 签名校验、应用信息缓存 | MySQL、Redis |
3. 中间件选型及理由
3.1 MySQL 8.0
理由：交易数据要求强一致性和 ACID 事务，金融场景不接受数据丢失。MySQL 在团队熟悉度、生态（如 gorm）、成本（自建）方面综合最优。单表千万级订单通过分区表或归档策略应对，不需要引入分布式数据库的复杂性。
选 MySQL 而非 PostgreSQL：PRD 明确列出 MySQL 8.0，团队已有运维经验；MySQL 在国内支付系统中更为普遍，社区案例更多。
3.2 Redis
Redis 在本系统中承担三个独立职责，每个职责对应不同的数据结构：
| 职责 | 数据结构 | 说明 |
|---|---|---|
| 幂等 Key 缓存 | String（SET NX EX） | 下单去重、回调幂等，TTL 与订单超时一致 |
| 分布式锁 | String（Redlock 语义） | 防止并发退款、分润重复触发 |
| 异步通知延迟队列 | Sorted Set（score 为下次重试时间戳） | 实现指数退避重试，无需引入重量级 MQ |
为什么不引入 RabbitMQ 或 Kafka：MVP 阶段通知 QPS 较低（< 500），Redis Sorted Set 延迟队列已足够；引入独立 MQ 会增加运维复杂度和故障点。PRD 也明确将 Redis Stream 或 RabbitMQ 列为备选，Redis Sorted Set 是更轻量的起点，后续可迁移。
3.3 Gin 框架
理由：Go 生态最成熟的 HTTP 框架，性能优异（零 gc 路由），中间件生态完善，团队学习成本低。符合 PRD 的 P95 < 200ms 要求。
3.4 GORM v2
理由：提供类型安全的 ORM，减少 SQL 拼接错误；支持软删除、Hook 钩子方便审计日志；Migration 能力支持版本化数据库变更。对于金融场景中需要精确控制的批量 SQL，支持原生 SQL 直接执行。
4. 模块间交互方式
pay-bridge 采用同进程函数调用而非微服务拆分，理由是 MVP 阶段团队规模和交易量均不需要微服务的复杂性，单体部署运维更简单，且 Go 的并发模型（goroutine）天然支持高并发。
模块间交互规则：
-
同步调用链（请求主路径）：API Handler → Service → Repository → DB。Service 层不互相直接调用，通过 interface 注入解耦。
-
事件驱动（异步后处理）：支付成功后，通知服务、分润服务、服务费服务通过 Go channel 或直接异步 goroutine 触发，不阻塞主请求链路。
-
重试队列（延迟执行）：通知重试写入 Redis Sorted Set，独立的 goroutine 定时扫描到期任务并执行。
-
定时任务：对账、商户状态检测等 cron 任务由独立 goroutine 调度，与 HTTP 服务共进程但相互隔离。
HTTP Request
│
▼
API Handler
│ 同步
▼
Trade Service ──── Repository ──── MySQL
│
│ 异步（goroutine）
├──► Notify Service ──► Redis Sorted Set（延迟重试）
├──► ProfitSharing Service ──► Channel Adapter ──► 汇元分账 API
└──► ServiceFee Service ──► Channel Adapter ──► 汇元分账 API
5. 渠道适配器框架设计思路
渠道适配器是整个系统可扩展性的核心。设计原则：对外暴露统一接口，对内封装渠道差异。
5.1 统一接口抽象
定义 PaymentChannel interface，所有渠道适配器必须实现此接口：
type PaymentChannel interface {
// Code 返回渠道编码
Code() string
// CreateOrder 下单，返回支付凭证
CreateOrder(ctx context.Context, req *CreateOrderRequest) (*CreateOrderResponse, error)
// QueryOrder 查询订单状态
QueryOrder(ctx context.Context, req *QueryOrderRequest) (*QueryOrderResponse, error)
// CloseOrder 关闭订单
CloseOrder(ctx context.Context, req *CloseOrderRequest) (*CloseOrderResponse, error)
// Refund 发起退款
Refund(ctx context.Context, req *RefundRequest) (*RefundResponse, error)
// QueryRefund 查询退款状态
QueryRefund(ctx context.Context, req *QueryRefundRequest) (*QueryRefundResponse, error)
// VerifyNotify 验证上游回调签名，返回解析后的通知数据
VerifyNotify(ctx context.Context, rawBody []byte, headers map[string]string) (*NotifyData, error)
// ProfitSharing 分账（渠道不支持时返回 ErrNotSupported）
ProfitSharing(ctx context.Context, req *ProfitSharingRequest) (*ProfitSharingResponse, error)
// RollbackProfitSharing 回退分账
RollbackProfitSharing(ctx context.Context, req *RollbackSharingRequest) (*RollbackSharingResponse, error)
// DownloadBill 下载对账账单
DownloadBill(ctx context.Context, req *DownloadBillRequest) (*BillData, error)
// MerchantApply 商户进件
MerchantApply(ctx context.Context, req *MerchantApplyRequest) (*MerchantApplyResponse, error)
// QueryMerchantStatus 查询商户审核状态
QueryMerchantStatus(ctx context.Context, channelMerchantID string) (*MerchantStatusResponse, error)
}
5.2 渠道工厂与注册（Registry 模式）
采用注册表（Registry）模式，避免 switch-case 的硬编码，实现插件化设计：
var registry = map[string]ChannelFactory{}
func Register(channelCode string, factory ChannelFactory) {
registry[channelCode] = factory
}
func GetChannel(channelCode string, config *ChannelConfig) (PaymentChannel, error) {
factory, ok := registry[channelCode]
if !ok {
return nil, ErrChannelNotFound
}
return factory(config), nil
}
每个渠道适配器包在 init() 中调用 Register() 完成自注册。新增渠道只需：新建包、实现 interface、调用 Register，主程序 import _ "pay-bridge/internal/channel/newchannel" 即可接入，无需修改任何现有代码。
5.3 汇元适配器特殊处理
汇元支付（HePay）采用 RSA/MD5 双签名和 RSA+3DES 双层加密，适配器内部封装：
- 签名层：根据渠道配置决定使用 RSA 还是 MD5，对外透明。
- 加密层：请求体使用 3DES 加密，密钥使用 RSA 公钥加密后随请求发送；响应体同样解密处理。
- 重试安全：所有加解密操作幂等，同一请求多次加密结果不同但均有效。
6. 异步通知 + 重试机制方案
6.1 整体流程
上游回调 → 验签 → 更新交易状态（DB 事务）→ 写入通知任务 → 立即第一次推送
│
推送成功 → 标记完成
推送失败 → 写入 Redis Sorted Set
score = now + 重试间隔
↓
Poller goroutine 定时扫描
到期任务 → 执行推送
成功 → 删除任务
失败 → 更新 score（下次重试时间）
超过 8 次 → 标记「通知异常」
6.2 重试间隔设计
共 9 次推送机会（第 1 次立即，后续 8 次重试），重试间隔：
| 第 N 次推送 | 距上次等待时长 | 累计等待时间 |
|---|---|---|
| 1 | 立即 | 0 |
| 2 | 15s | 15s |
| 3 | 30s | 45s |
| 4 | 1m | 1m45s |
| 5 | 5m | 6m45s |
| 6 | 30m | 36m45s |
| 7 | 1h | 1h36m45s |
| 8 | 6h | 7h36m45s |
| 9（最终） | 12h | 19h36m45s |
重试策略参考微信支付官方规范，前期快速重试应对网络抖动，后期拉长间隔避免无效轰炸，最终兜底是下游主动查询。
6.3 幂等保障
通知发送前检查 notify_log 中的发送记录，避免 Poller 并发触发重复推送。同一通知任务加 Redis 分布式锁（lock key = notify_lock:{trade_no}），保证同一时刻只有一个 goroutine 执行推送。
7. 幂等方案
系统在三个层面保障幂等，形成防重复操作的纵深防御：
7.1 下单幂等（防重复创建订单）
- 第一层 - Redis SET NX：下单时以
idempotent:{app_id}:{merchant_order_no}为 key，SET NX EX（TTL = 订单超时时间 + 缓冲）。命中则直接返回已有凭证，不进入后续流程。 - 第二层 - DB 唯一索引：
trade_order表在(app_id, merchant_order_no)上建唯一索引，作为 Redis 失效或缓存穿透时的兜底防护。 - 处理逻辑：若幂等 key 已存在，直接查询并返回已有订单的支付凭证，不重新调用渠道。
7.2 回调幂等（防重复处理上游通知）
- 上游回调到达后，先以
(channel_trade_no, status)查询 DB，如已处理则直接返回成功。 - 更新
trade_order.status使用乐观锁（WHERE status = 'PAYING' AND trade_no = ?），确保状态只正向流转，并发更新时只有一个成功，其余幂等返回。
7.3 分润 / 服务费幂等（防重复分账）
profit_sharing_order和service_fee_log在trade_no上建唯一索引（同一笔交易只触发一次分账）。- 调用渠道分账 API 前，以
sharing_lock:{trade_no}加 Redis 分布式锁（TTL = 30s），防止并发触发。
8. 关键技术决策点
8.1 单体还是微服务
决策：单体。理由：团队规模小，MVP 阶段交易量 < 500 QPS，单体的运维复杂度远低于微服务；Go 的 goroutine 模型天然支持高并发，单体完全能满足性能目标。架构上通过分层和 interface 保持模块边界清晰，未来有需要时可以沿模块边界拆分为微服务。
8.2 消息队列选型
决策：Redis Sorted Set 作为延迟队列。理由：避免引入独立 MQ 组件（RabbitMQ、Kafka）增加运维负担；Redis 已是必选基础设施；Sorted Set 的 score 天然表达「下次执行时间」，实现简单可靠。当 QPS 超过 5000 或需要多消费者时再迁移到专业 MQ。
8.3 订单号策略
决策：数据库序列（行级锁 + 自增），不用 UUID，不用雪花 ID。理由：UUID 无序，频繁插入导致 B+ 树碎片化；雪花 ID 依赖机器 ID 配置，多实例部署时配置复杂；数据库序列在 MySQL 层保证 app_id 维度的唯一递增，实现最简单，天然满足 PRD 中「不同应用独立编码序列」的要求。生成格式：{prefix}{yyMMdd}{8位序号}，例如 PAY26022700000001。
8.4 密钥存储
决策：数据库加密存储，AES-256-GCM 加密。私钥、appSecret 等敏感字段以加密后的 Base64 字符串存入 MySQL，加密密钥由环境变量注入（不写入代码或配置文件）。读取时在渠道配置仓储层解密，上层服务不感知加密细节。
8.5 对账执行机制
决策：进程内 cron + 数据库任务锁。使用 robfig/cron 在进程内调度，多实例部署时通过 Redis SETNX 确保同一时刻只有一个实例执行对账，避免重复。不引入外部调度平台（如 XXL-Job），保持轻量。
8.6 数据隔离粒度
决策：以 app_id 为核心隔离维度。订单、分润配置、服务费配置、订单编码序列均以 app_id 隔离。不同 app 的数据物理上在同一张表（通过 app_id 字段区分），通过数据库索引和应用层鉴权确保 A 应用无法访问 B 应用的数据。MVP 阶段不做分库分表，当单 app 订单量超过 5000 万后再考虑分表。
8.7 固定账户收款匹配策略
决策：规则引擎（优先级匹配）而非 ML 模型。三维度匹配（备注解析 > 金额精确匹配 > 付款方名称相似度）通过确定性规则实现，可解释、可审计、易排查。备注解析采用正则提取订单号，名称比较采用精确相等（不用模糊匹配），避免误匹配导致的资金风险。匹配降级策略：备注匹配优先，失败时降级为金额匹配，多候选时用名称缩小范围，无法确定时标记待人工确认。
9. 部署架构
┌─────────────────┐
│ Nginx / LB │
└────────┬────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────────▼──────┐ ┌──────▼───────┐ ┌────▼──────────┐
│ pay-bridge │ │ pay-bridge │ │ pay-bridge │
│ instance 1 │ │ instance 2 │ │ instance 3 │
└────────┬───────┘ └──────┬───────┘ └────┬──────────┘
│ │ │
┌────────▼────────────────▼──────────────▼──────────┐
│ MySQL 8.0（主从复制） │
│ Redis（Sentinel / Cluster 模式） │
└───────────────────────────────────────────────────┘
水平扩展能力保障：
- 无本地状态：所有实例状态通过 Redis 和 MySQL 共享，任意实例可处理任意请求。
- 幂等在 Redis/DB 层：多实例并发下单、重复回调均由 Redis SET NX 和 DB 唯一索引保障。
- 分布式锁在 Redis 层：分润、服务费分账操作通过 Redis 锁防止并发执行。
- 定时任务去重：cron 任务通过 Redis SETNX 保证多实例中只有一个实例执行。
高可用方案：
- MySQL 主从复制：写操作走主库，读操作可走从库（按需）；主库故障时手动或自动切换。
- Redis Sentinel：3 节点 Sentinel 监控，主节点故障自动切换，客户端感知切换。
- Nginx 负载均衡：upstream 配置健康检查，实例故障自动摘除。
- 日志聚合：结构化 JSON 日志接入 ELK/Loki，多实例日志统一查询。