三家公司两套支付通道一套Spring Boot支付服务前后维护了一年半。第一家是本地生活平台App下单加小程序入口高频小额第二家是知识付费SaaS公众号H5卖课程和会员虚拟商品第三家是B2B企业商城Web端大额支付还要配合财务对账。业务形态差得远但抠出共性的那部分就是一套基于Spring Boot的支付对接框架加上微信支付和支付宝两条渠道的适配再把架构设计、合规边界和生产环境里的坑一次讲透。这篇文章不做官方文档搬运只讲我在三个真实项目里验证过的落地方案支付模块怎么抽象、微信V3接口哪些地方最坑、支付宝通知校验怎么处理、合规上哪些事不能碰。正在设计或维护支付模块的Java后端同学可以直接参考如果是想把支付从单体业务中合理抽离出来的架构负责人里面关于边界划分和资金安全的思路同样适用。1. 三个项目一个结论支付模块必须独立成服务1.1 三个业务场景差异到底在哪里先交代一下这三家公司的真实业务形态因为后面所有设计决策都围绕它们展开。第一家是本地生活类平台用户在App里下单买便利店商品或者叫跑腿服务同时在微信小程序里也有入口。这个场景的特点是订单金额小、频次高、用户量大支付渠道主要用到微信App支付、微信小程序支付以及部分Native扫码支付用户对支付失败几乎零容忍。第二家是知识付费SaaS课程、会员、专栏这类虚拟商品主要在微信公众号里打开H5页面完成支付也会用到小程序。这个场景的特点是虚拟商品不能像实物一样“等收到货再确认”支付成功后需要立刻开通权限另外一个特殊难点是虚拟商品退款政策敏感线上客诉多状态机设计必须能清楚反映资金状态和权益状态的对账关系。第三家是B2B企业商城面向企业租户销售办公类商品和服务。企业客户很多不使用个人微信/支付宝的App方式而是在PC端操作既有标准收单的需求也有企业转账后人工上传回单的线下支付场景。这家公司对“对账”的诉求最强烈财务要能把线上支付流水、线下转账回单和业务订单统一核销。另一个很容易忽略的差异是微信小程序里不能直接调起支付宝。如果产品想让用户在小程序里用支付宝付款常规做法是单独开发支付宝小程序或者走银联/聚合服务商方案而不是在小程序里嵌入支付宝SDK。第一家公司就曾在这个问题上反复评估最后明确“小程序支付能力跟随平台生态走”的底线避免在渠道选择上做无效设计。1.2 为什么不能直接在业务系统里调第三方SDK很多同学会觉得微信/支付宝都有现成SDKController里调一下不就行了如果业务只有一个、改动频率低、团队也不打算做第二套业务线那确实可以。但三家公司的情况都指向同一个结论支付模块必须独立。最直接的痛点是代码重复。同一套下单逻辑、回调处理逻辑、退款逻辑放到三个业务服务里就是三份代码后续微信升级API、换证书、调整签名算法每个服务都要跟着动一遍维护成本成倍增加。其次是渠道替换的代价。支付渠道之间的接口差异远大于表象上的JSON/XML区别今天接微信明天接支付宝如果支付逻辑和业务逻辑耦合在一起改动会牵连业务主链路。还有一层是财务视角的需求。业务方可以不管支付细节但财务必须看到每天的支付流水、退款流水、手续费对账这些数据需要在一个统一的地方沉淀。支付服务独立出来后等于给财务提供了一个单一口径的账务数据来源避免多个业务系统各报各的账。从测试角度讲独立的支付服务也更好模拟。每个渠道都有沙箱环境但沙箱和生产环境之间的参数、回调域名、证书配置都不一样独立服务可以把这些环境差异收敛在一个地方业务系统联调时只需要面向内部接口。所以第一个结论很简单明确Spring Boot项目里支付应该是一个独立的后端服务而不是业务服务里的一个包。技术上的直观表现是业务服务通过内部RPC或HTTP接口调用支付服务支付服务不反向依赖业务服务的数据库。2. 总体架构业务订单与支付流水建模2.1 支付系统里必须分清楚的三类单据这是我在三个项目里贯穿始终的核心建模思路业务订单、支付单、渠道流水三者是不同层次的东西永远不要合并到一张表。业务订单描述的是“用户买了什么”比如一个课程订单、一箱可乐、一套办公设备它关心的是商品、数量、金额、收货信息、履约状态。支付单描述的是“用户为这笔业务付了多少钱”它关心的是支付渠道、金额、币种、支付状态、回调状态、退款状态。渠道流水则是第三方支付平台返回的交易流水比如微信支付单号、支付宝交易号它是资金对账的最终凭证。一笔业务订单可以对应多笔支付单。比如用户第一次支付超时关闭重新发起了一笔新的支付此时业务订单还是那一单但支付单有两笔一笔已关闭一笔支付成功。支付单与渠道流水则应该尽量是一对一的关系一个支付单只对应一个渠道交易单号这样对账逻辑最干净。如果把这些状态全塞进业务订单表短期内看起来方便但一旦出现改价、部分退款、多期支付、异常重试的情况表结构就会变得越来越别扭。你在业务订单表里既要存“订单金额”又要存“已支付金额”还要存“退款金额”三个字段的一致性由谁保证最终还是需要支付流水表来兜底。2.2 核心表结构与状态字段支付单表的关键字段大致如下CREATE TABLE pay_order ( id BIGINT PRIMARY KEY AUTO_INCREMENT, pay_no VARCHAR(64) NOT NULL COMMENT 支付单号业务侧幂等键, biz_order_no VARCHAR(64) NOT NULL COMMENT 业务订单号, channel VARCHAR(20) NOT NULL COMMENT 渠道: WECHAT / ALIPAY, scene VARCHAR(20) NOT NULL COMMENT 场景: APP / JSAPI / H5 / NATIVE, amount BIGINT NOT NULL COMMENT 金额单位分, currency VARCHAR(8) DEFAULT CNY, channel_order_no VARCHAR(64) COMMENT 渠道交易单号, status VARCHAR(20) NOT NULL COMMENT PENDING / SUCCESS / CLOSED / REFUNDING / REFUNDED, refund_amount BIGINT DEFAULT 0, notify_status VARCHAR(20) COMMENT 回调处理状态, create_time DATETIME NOT NULL, pay_time DATETIME, close_time DATETIME, UNIQUE KEY uk_pay_no (pay_no), KEY idx_biz_order (biz_order_no), KEY idx_channel_order (channel_order_no) );状态机的设计遵循一个铁律状态只能往前走不能回退。“PENDING”只能流转到“SUCCESS”或“CLOSED”不会出现从“SUCCESS”回到“PENDING”的情况。订单关闭之后如果回调还在路上必须靠幂等判断挡住不能因为一次迟到的回调把已经关闭的订单重新激活。2.3 渠道层抽象门面加策略把支付抽象成接口是我觉得整块架构里最关键的一步。这个接口不应该只设计一个“下单”方法而要覆盖支付全生命周期预支付、查询、退款、解析回调。public interface PayChannel { PayPrepayResult prePay(PayContext context); PayQueryResult query(String channelOrderNo); PayRefundResult refund(PayContext context); PayNotifyInfo parseNotify(String body, MapString, String headers); String channelCode(); }每个渠道实现一个Spring Bean用Component(wechatPayChannel)、Component(alipayChannel)这类方式注册。上层通过一个PayChannelRouter根据channelCode()找到对应Bean既能避免用一堆if-else切换逻辑也能在后续接入新渠道时保持扩展能力。对于Spring Boot项目来说渠道适配层放在支付服务内部业务服务完全感知不到渠道差异。业务侧传一个“我要在App场景下支付一笔订单”支付服务内部自动决定调微信还是支付宝返回给前端的又是一个统一的支付参数结构比如一个约定好的payParamsJSON串前端拿这个串直接调起支付。2.4 回调与定时查单的双通道一致性支付系统最核心的风险点是回调不可靠。微信和支付宝都会做通知重试但网络抖动、服务重启、回调处理超时都可能造成业务侧收不到最终状态。所以设计上必须两条腿走路异步回调负责实时推进状态定时查单负责兜底。我在三套系统里都部署了一个定时任务每隔一分钟扫描一次超时未完成的支付单调用渠道查询接口核对真实状态。比如支付单创建超过5分钟仍处于PENDING主动调微信query接口确认是否真的没支付。如果渠道返回已付款则走与回调处理相同的状态推进逻辑如果渠道返回未付款则继续等待直到订单超时时间到达才关闭。3. 微信支付落地实操V3接口、证书与回调解密3.1 不同终端场景怎么选接口微信支付按照终端场景区分接口这点经常被刚接触的同学搞混。Native支付收银台或Web页面生成二维码扫码后支付适合线下自提或PC端场景返回的是code_url后端生成二维码图片给前端展示。App支付在App内调起微信客户端支付需要prepay_id前端用微信SDK发起。JSAPI支付小程序和公众号内支付必须传入用户的openid这是最容易被忽视的字段。H5支付在手机浏览器里发起需要通过h5_info传入场景信息且商户平台配置好H5支付域名浏览器环境做严格限制。第一家公司同时使用App支付和小程序JSAPI支付这里就有个隐蔽问题同一个用户在小程序和App里的身份标识体系不同小程序用openidApp用用户ID终端信息。支付服务在记录用户维度时最好把两种标识分开存储发起支付时再由业务层明确传入。第二家知识付费项目则踩过H5支付的坑。微信公众号网页和普通手机浏览器的判断条件不同同一套H5支付代码在微信内打开时必须走JSAPI在外部浏览器里打开才能走H5支付。判断错了直接导致支付场景不合法用户卡在支付页。3.2 两套证书体系不能混微信支付V3最大的坑是证书体系复杂而且名字非常接近商户API证书和微信支付平台证书。这两者完全不是一回事。商户API证书用于商户请求下单、退款等接口时对请求签名证书文件以apiclient_key.pem和apiclient_cert.pem形式存在对应的证书序列号要一并配置到请求头里。微信支付平台证书则用于验证微信服务器返回给我们的签名以及解密回调报文里的加密资源。平台证书在本地不能直接拿到完整集官方提供了脚本从微信平台接口下载。线上环境证书会定期轮换生产事故频发的点就是本地只保存了一份平台证书轮换后验签直接失败所有回调全部报“验签失败”。实践中我会在支付服务里维护一个“平台证书列表”定时从微信接口刷新验证签名时用报文中Wechatpay-Serial指定的证书序列号去匹配而不是默认用本地唯一证书。注意这个细节后证书轮换期间系统可以不间断运行。3.3 下单与支付参数生成以Native支付为例核心请求参数包括appid、mchid、description、out_trade_no、amount.total、notify_url。这里金额单位是分而且是int类型建议直接用Long类型在Java里传递避免类型溢出。{ appid: wx..., mchid: 1230000109, description: 商品描述, out_trade_no: PAY202501010001, notify_url: https://api.company.com/pay/wechat/notify, amount: { total: 100 } }App支付的返回会包含prepay_id前端SDK要求组装一个签名串包含appid、partnerid、prepayid、package、noncestr、timestamp最后用商户API私钥做SHA256withRSA签名。这个签名逻辑直接使用官方SDK即可不要自己手写加密手写很容易在参数拼接顺序上报错。3.4 回调验签与解密顺序微信V3的支付结果通知是POST JSON格式但回调报文并非明文而是加密后的resource字段。处理顺序一定要正确从请求头取Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial。根据Wechatpay-Serial选择对应平台证书用平台证书验签。验签通过后用APIv3密钥对resource做AES-256-GCM解密。解密成功后解析订单号、交易状态、金额。幂等校验并更新支付单状态。验签和解密的顺序不能反。如果先解密后验签一旦遇到伪造报文你的系统会去解密一堆无法解析的加密内容轻则日志变垃圾重则把异常数据写入数据库。验签失败时直接返回HTTP 401或400微信会稍后重试。解密后的关键字段包含out_trade_no、transaction_id、trade_state、amount.payer_total。除了状态还必须校验金额防止中间人篡改或者商户后台配置错误导致金额不一致。3.5 退款接口与退款回调退款也是异步操作。调用退款接口后微信会返回受理结果但退款最终是否成功依赖于退款结果回调。退款状态包括SUCCESS、CLOSED、PROCESSING、ABNORMAL需要专门维护一个退款单状态不能复用支付单状态。我在第三家B2B商城项目里遇到的典型场景是财务发起一笔退款但因为退款回调没有单独处理导致支付单显示已支付、退款单状态却一直是待退款业务和财务两边对不上。后来把退款单独立成一张表有单独的退款流水号、退款金额、退款渠道单号并且退款状态流转单独走一套状态机问题才彻底解决。4. 支付宝集成实操同一套抽象层适配支付宝4.1 支付宝的服务端模式支付宝的交互模式与微信略有差异。以App支付为例支付宝要求服务端先调用alipay.trade.app.pay接口得到一个orderStr字符串返回给前端前端拿到orderStr后由支付宝SDK调起支付。这个模式下服务端不直接返回prepay_id这种结构化参数所有签名信息都已经包括在orderStr里。H5/WAP支付则更特殊支付宝服务端返回的是一段自动提交的HTML表单或者一个跳转URL。后端如果直接返回JSON前端需要额外处理表单渲染。我在第二家公司对接H5时是把支付宝返回的form表单以字符串形式透传给前端页面前端通过document.write或innerHTML渲染后自动跳转。这个细节如果不处理H5支付总是白屏。当面付适合线下扫码场景。第三家B2B企业商城没有用到当面付但第一家公司自提场景预留了这个接口核心返回也是qr_code和微信Native的code_url同一层级的概念。4.2 密钥体系比微信简单但私钥管理更考验习惯支付宝的密钥体系是应用私钥、应用公钥、支付宝公钥三件套。商户自己生成RSA密钥对应用公钥上传到支付宝开放平台支付宝公钥从平台下载到本地。签名逻辑商户请求支付宝用应用私钥签名支付宝响应用支付宝公钥验签支付宝回调通知也用支付宝公钥验签。这里有个长期容易忽略的坑支付宝公钥和应用公钥不是一回事。有很多次排查线上验签失败最后发现是运维直接把应用公钥配置成支付宝公钥导致验签必然失败。配置时这个字段命名必须非常醒目。密钥的存储也一样严格。应用私钥绝不能出现在Git仓库、配置文件明文、日志或者数据库里。生产环境建议放到配置中心统一管理并设置权限访问控制如果再谨慎一些可以用Jasypt对配置项加密启动时用环境变量传入解密密钥。4.3 异步通知的参数形态和处理差异支付宝异步通知是application/x-www-form-urlencoded表单POST和微信的JSONAES加密完全不同。验签时把收到的所有参数排除sign和sign_type按key排序后拼接成待验签串用支付宝公钥验签。验签通过后还要做业务校验检查app_id是否匹配检查out_trade_no是否是自己平台下的单检查total_amount是否与支付单金额一致检查seller_id是否匹配自己商户号处理成功后必须返回纯文本success注意是全小写。如果返回其他内容支付宝会按照递增间隔持续重发通知最长可能持续几天会导致系统重复处理。支付宝的金额是字符串格式单位为元例如10.00微信的是整数字段单位为分。这个差异在适配层里要统一转换成以分为单位的Long类型避免业务层同时看到两套单位。我用一个MoneyConverter统一处理微信/支付宝各自实现自己的解析规则向上层永远吐“分”。4.4 支付宝渠道的主动查询兜底支付宝同样提供alipay.trade.query接口作用和微信订单查询一样。我在定时任务里对两个渠道一视同仁扫描超时未支付订单时先把支付单查出来再根据渠道路由到对应查询接口。渠道返回已支付的结果后统一走状态推进逻辑。这里有个小技巧主动查询结果里也包含金额查出已支付后要再做一次金额比对防止半路配置错误或人为篡改渠道查询报文。5. 合规与资金安全比代码更值得投入的部分5.1 支付通道的商户主体不能乱合规这件事第一优先级还不是数据隐私而是支付通道的归属和使用边界。每一条支付通道都绑定了具体的商户主体、经营场景、结算账户。如果你把通道用到申报之外的其他业务上尤其是把通道接口转借给没有独立入网资质的二级商户使用一旦资金链路出现纠纷平台方要承担的远不止接口故障风险通道被关闭甚至清退都是可能的。第三家B2B商城当时讨论过是否让平台内中小商户共用一套通道经过评估后明确否决。原因很简单共用通道并不能带来合规的结算能力平台方既不是持牌机构也没有为每个商户做完整的支付结算协议约定共用通道短期内省事长期等于给自己埋雷。正确做法是如果有多商户收单需求选择微信支付/支付宝开放的服务商或机构合作方案让每个商户具备独立身份平台自身涉及会员充值和预付款的业务也要严格遵守支付结算的相关要求资金不能随意挪作他用账要记得明明白白该做存管的就去和有资质的机构合作。5.2 敏感的卡数据不能落地虽然微信和支付宝的个人支付不需要处理银行卡号但涉及绑卡、银行卡直连、退款到银行卡等场景时必须把PCI数据安全要求提上日程卡号、有效期、CVV/CVC这类完整明文数据不能进入我们自己的数据库和日志。我在支付服务中定的规矩是任何业务代码都不得主动记录完整的银行卡号。前端如果必须收集卡信息优先采用渠道方提供的收银台SDK或收银模块让卡数据直接进入渠道网络我们的服务器只接收渠道返回的token或凭据。哪怕渠道返回报文中带了卡号在打印日志前也要做脱敏只保留前六后四。5.3 交易记录留存与日志脱敏支付系统无论如何都要保存完整的交易流水这是对账和售后纠纷处理的基础。但留存交易记录和泄漏敏感信息并不矛盾保存订单号、渠道单号、金额、时间、商品名称、状态变化就够了不需要把用户完整手机号、证件号、支付凭据明文都塞进去。日志方面我强烈建议把支付服务的日志单独分流到一个独立文件并且通过日志框架的过滤器做关键字脱敏。谁都不希望在排查问题时从日志里翻出一堆明文手机号或支付参数。在三个项目里我都配置了Logback的RegexReplacement把疑似手机号和订单号附近的敏感字段打码。还有一条经验生产环境的数据库账号、私钥证书、支付参数不要出现在开发机和测试环境的配置文件里。三套系统都遇到过开发环境误连生产支付配置的情况虽然最后没有造成实际资损但把开发环境的测试支付请求打到生产商户号上本身就是事故。5.4 退款风控与反欺诈支付服务不能无脑支持无条件退款。虚拟商品退款尤其敏感第二家知识付费平台就出现过批量薅羊毛用户购买课程完成后立刻申请退款但内容已经被完整缓存平台没有退赔能力。后来在退款流程里加了人工审核节点并针对同一用户/同一设备/IP的高频支付退款行为触发风控告警。反欺诈还要落到支付前的额度控制上。一个真实场景凌晨时段一个新注册用户连续发起几十笔小额支付金额逐步逼近限额这种特征非常可疑。支付服务可以做基础规则判定单用户单日支付笔数、单笔最大金额、单设备关联用户数超过阈值就转入人工审核链路而不是直接拒绝避免误伤正常用户。6. 生产环境避坑清单三家公司踩过的真实问题6.1 金额精度问题的唯一解全链路使用分支付金额绝不能使用double或float。99.9%的金额精度问题都来自浮点数运算比如1.58在二进制里是一串无限小数计算后变成1.5799999。我接手第一个项目时支付单金额字段还是MySQL的DECIMAL(10,2)Java实体对应BigDecimal看似严谨但渠道接口转换时因为单位不同出现过订单金额差一分钱导致对账不平的事故。后来统一规则数据库金额列全部改为BIGINT单位分Java代码全程使用Long渠道适配层负责和渠道的单位转换。支付宝返回的10.00元字符串统一用BigDecimal转成1000L分再进入业务层。前后端交互时金额永远以分为整数传递展示时再由前端转换成元。6.2 回调重复处理数据库唯一索引比锁更可靠回调重复是这个行业最普遍的问题没有之一。微信和支付宝都强调通知不保证不重复所以支付处理逻辑必须具备天然幂等性。我在支付单表上加了channel_order_no唯一索引回调处理时先按channel_order_no查询如果已存在则直接返回成功响应不再触发业务逻辑。只依赖Redis分布式锁是不够的因为锁可能在事务提交前过期释放另一个线程又进来处理一次。最终要靠数据库约束兜底UPDATE pay_order SET status SUCCESS WHERE id ? AND status PENDING如果影响行数为0说明已经处理过直接丢弃。6.3 回调处理接口不能做重活回调接口是支付网关直接调用的接口响应速度直接影响渠道侧的重试策略。第一家公司早期把回调处理做得太重解密后立刻更新库存、发消息、更新搜索索引、推送站内信整个接口耗时经常超过5秒微信回调超时后不断重试反而加重了系统负载。后来把回调接口拆成两段第一段只做验签、解密、幂等判定、更新支付单状态返回成功第二段通过Spring事件发布异步执行库存、订单状态变更、消息通知等业务逻辑。回调接口RT降到100毫秒以内重试压力立刻缓解。这里要注意异步处理需要保证“最终一致”。我的做法是落一张内部消息表异步消费成功后删除失败则继续重试确保支付成功后的权益开通不会丢。6.4 并发场景下的多次支付发起用户手误狂点提交支付按钮前端又没做禁用后端同一时刻可能收到多笔相同业务订单的支付请求。如果不去重用户会同时生成多笔待支付单一旦都支付成功资损就发生了。解决办法是在支付服务入口按biz_order_no加分布式锁锁内查询该业务订单是否已有待支付或已支付支付单有则直接返回。由于分布式锁存在过期风险核心防重还是靠数据库唯一索引或状态字段的条件更新锁只是第一道拦截。6.5 证书、密钥、回调域名这些“环境配置”要被管起来微信支付V3的证书、支付宝的应用私钥、回调域名、商户号这些配置在测试环境和生产环境完全不同。最容易出的生产事故是测试环境配置了生产回调域名或者生产环境加载了沙箱密钥导致所有请求都报非法签名。建议在Spring Boot的配置体系里拆分三套Profile支付服务的配置项全部走bootstrap-{profile}.yml加配置中心同时加上启动自检逻辑启动时如果检测到当前环境与回调域名环境不匹配直接启动失败而不是带伤运行。6.6 轮询查单不要等回调大家总觉得支付成功一定会有回调但实际上总有各种极端情况服务重启丢通知、微信间隔很久才补发、回调被防火墙拦截。定时查单就是为了兜住这些极端场景。我的经验是定时任务扫单间隔设置为60秒扫描条件是“创建超过2分钟且仍处于PENDING”查单结果如果渠道返回已支付就复用回调处理链路推进状态。定时任务本身要做好幂等和回调处理共用同一个状态推进方法不能各写一套否则两套逻辑早晚出现状态不一致。三家公司做完我最大的感受是支付系统最难的不是把接口调通而是把状态、幂等、对账、安全这些底层的秩序建立起来。MySQL里可能只多几个表代码里可能只多一个抽象接口但这些设计落地越早后续业务扩张就越少踩坑。最后再分享一个最实际的建议回调处理的代码不要用复杂设计模式能写得多平实就多平实确保一个新来的后端同事在5分钟内能看懂一次支付回调的完整处理路径这套系统才能在你手里安稳交付、长久维护。
