← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.8.1 支付链路入门:下单、回调验签与十一个坑

审校 2026-09-26 · 素材来源:zcode会话#5《支付项目架构与SpringCloud整合指南》(IJPay源码)
📑 本篇章节导航 (共8节,点击直达)
三条链路:下单、回调、查单模块地图与 V2/V3 并存下单:Builder 构参 → 签名 → 发送回调:四步一个都不能少十一个坑速查表查单补偿:宁可慢,不能漏重试的正确姿势与上手路径面试怎么问

五年级 Java 转支付方向,第一个要建立的认识:支付的本质是钱的状态机 + 跨系统对账。这篇用 IJPay 这个「不依赖任何框架的工具库」走一遍支付三条链路,顺便把支付小白的十一个高频坑钉死。

前置阅读:18.4 讲过验签与防重放。这篇把它们放进完整支付链路里看。

三条链路:下单、回调、查单


下单链路:创建订单 → 组装参数 → 签名 → 调统一下单接口 → 返回支付凭证
回调链路:第三方 → 你的 /notify → 验签 → 幂等更新订单 → 返回 SUCCESS
查单链路:主动查单(补偿)→ 对账 → 差异处理

IJPay 的定位要认清:它只封装三件事——接口地址枚举、签名/验签/加解密工具、HTTP 调用代理。订单、对账、幂等、分布式事务它一概不管,这些是业务层自己的真功夫。把工具库当框架用,是支付小白第一坑。

模块地图与 V2/V3 并存


IJPay-Core      公共底座:HTTP 代理、签名加解密、二维码、Model 基类
IJPay-WxPay     微信支付(V2 和 V3 两套)
IJPay-AliPay    支付宝(封装官方 SDK 的 AlipayClient)
IJPay-UnionPay  银联
IJPay-Plugin    插件(切换 HTTP 委托实现)
IJPay-Demo-*    SpringBoot / JFinal / Solon 三套 Demo

按需引 IJPay-WxPay,或者一把梭 IJPay-All。每个渠道的关键类都是四件套:WxPayApiConfig 配置、WxPayApiConfigKit 配置容器、WxPayApi 门面、WxPayKit 签名工具——各渠道命名完全对齐,学会一个等于全都会了。

微信 V2 和 V3 是并存的两套体系,配置对象里两把密钥都有字段:V2 走 XML 报文加 partnerKey(API 密钥)签名,V3 走 JSON 加 apiKey3 加平台证书的加解密。下单用哪套、回调就验哪套,两把钥匙互开不了对方的锁——混用是「验签永远失败」的头号原因。

下单:Builder 构参 → 签名 → 发送


WxPayApiConfig cfg = WxPayApiConfigKit.getWxPayApiConfig();
Map<String, String> params = UnifiedOrderModel.builder()
    .appid(cfg.getAppId())
    .mch_id(cfg.getMchId())
    .nonce_str(WxPayKit.generateStr())      // 随机串防重放
    .out_trade_no("ORDER-20260924-001")     // 商户订单号,必须全局唯一
    .total_fee("100")                       // ⚠️ 单位是分,不是元!
    .notify_url(cfg.getDomain() + "/wxPay/payNotify")
    .trade_type(TradeType.NATIVE.getTradeType())
    .build()
    .createSign(cfg.getPartnerKey(), SignType.HMACSHA256);
String xml = WxPayApi.pushOrder(false, params);   // 发送

Model.builder().build().createSign() 是 IJPay 的核心范式:Builder 构造参数 → 反射转 Map → 按字典序拼接签名。

createSign 内部值得多看三眼:BaseModel.toMap() 用反射把 Model 字段读成 Map(新增字段零改造,反射元模型的典型收益);参数按字典序排序后拼接再摘要,字典序是为了让签名和验签两边拼出同一个串;nonce_str 随机串防重放攻击,spbill_create_ip 用 IpKit.getRealIp 取真实客户端 IP。Demo 里这些参数都替你填好了——抄 Demo 起步,比对着文档拼参数稳得多。

回调:四步一个都不能少


public String payNotify(HttpServletRequest request) {
    Map<String, String> params =
        WxPayKit.xmlToMap(HttpKit.readData(request));  // ① 读原始报文
    if (WxPayKit.verifyNotify(params, cfg.getPartnerKey(),
            SignType.HMACSHA256)) {                    // ② 验签
        if (WxPayKit.codeIsOk(params.get("return_code"))
         && WxPayKit.codeIsOk(params.get("result_code"))) {  // ③ 双码都查
            orderService.markPaid(params.get("out_trade_no")); // ④ 幂等更新
            return WxPayKit.toXml(ok("SUCCESS"));      // 必须回 SUCCESS
        }
    }
    return null;  // 验签失败返回非 SUCCESS,让微信重试
}

不验签等于任何人都能伪造「支付成功」。幂等必须做:微信会重试最多 8 次、间隔递增,先查订单状态、已处理直接返回 SUCCESS。

两个实操细节:HttpKit.readData(request) 读的是原始报文,别换成 @RequestBody 让框架先反序列化再自己拼回去验签——属性顺序、转义一变,签名就对不上;幂等的前置动作是先查订单状态再决定处理,分布式锁只防同一时刻的并发,防不了隔了一分钟的重试,状态检查才是每次请求都要过的关卡。验签直接用 WxPayKit.verifyNotify,别自己手拼摘要——字典序、空值剔除这些规则工具库已经固化,手拼十有八九漏一条。

十一个坑速查表

1. 金额单位:微信是分(整数),支付宝是元(字符串 "1.00"),混用必出事

2. 金额别用 double/float:BigDecimal 或按分用 long,浮点误差就是资损

3. 回调必须验签:底线中的底线

4. 回调必须幂等:重试是常态不是异常

5. return_code vs result_code:前者是「通信成功」,后者才是「业务成功」,两个都查

6. out_trade_no 唯一性:重复下单直接被拒

7. 签名类型一致:下单用 HMACSHA256,回调验签也得是它,否则永远失败

8. 证书安全:.p12/apiclient_key.pem 是钱袋子,不进 git、不进日志,走密钥管理

9. 超时与重试:网络抖动会「下单成功但你没收到响应」——用户其实付了。必须有主动查单补偿

10. 退款更要小心:退款回调才是终态,可能部分成功,退款要双向证书

11. 时区:统一 Asia/Shanghai,跨时区部署有坑

十一个坑里三个直接对应资损(金额单位、浮点误差、重复扣款),属于必须写进代码评审 checklist 的红线;其余八个对应漏单和排障成本。新人接手支付模块,先把这张表过一遍再动键盘。

查单补偿:宁可慢,不能漏

支付系统第一原则不是快,是不漏单、不重付。查单补偿是底线:


// 定时任务:扫「待支付超过 5 分钟」的订单,逐个主动查渠道
pendingOrders.forEach(o -> {
    Map<String, String> r = WxPayKit.xmlToMap(
        WxPayApi.orderQuery(buildQueryMap(o)));
    if (isPaid(r)) orderService.markPaid(o.getOutTradeNo());
});

对账是查单补偿的下一站,也是支付系统最后的兜底:每日下载渠道账单(DOWNLOAD_BILL)和自家订单流水逐笔比对,差异入差异表。「渠道成功、我方失败」是最危险的差异——钱到了但订单状态没跟上,要立刻补单;「我方成功、渠道失败」次之,要触发退款核查。查单补偿只覆盖「通知丢了」,对账覆盖「一切说不清的」——两者的关系是点检和大盘对总账。对账原始文件还要按日期归档留存,审计和纠纷处理都指着它,监管核查时也是第一手证据。

重试的正确姿势与上手路径

工具库自带 RetryUtils.retryOnException,配 ResultCheck 回调判断这次到底成没成。但重试只敢包查询类接口:下单接口要重试必须先查单或换新订单号,否则网络抖一下就是两笔扣款——重试的安全性比可用性优先级高。

上手三步:先跑 IJPay-Demo-SpringBoot 过一遍微信沙箱,盯着日志看请求参数和回调报文长什么样,这是建立直觉最快的方式;再通读三个文件——WxPayApiConfigKit(多商户容器)、BaseModel(签名机制)、WxPayController.payNotify(回调),这三个看懂,IJPay 就懂了八成;最后业务层自搭订单状态机、幂等表、本地消息表、对账表——工具库不提供的,恰恰是支付系统的真功夫。

面试怎么问

「支付回调怎么保证安全?」——答:三道防线——验签(防伪造)、幂等(防重试重复处理,状态机条件更新)、主动查单补偿(防通知丢失)。再补一句 return_code 和 result_code 的区别,就是有实操味道的答案。

追问「查单补偿的频率怎么设计」——答分层:待支付五分钟内的不查(回调大概率还在路上),超时的每分钟一批,超过二十四小时的降频并告警;补偿任务自己也要限流,别把兜底机制变成对渠道接口的压测。

一句话总结:工具库只管签名和 HTTP,验签、幂等、补偿三大件才是支付系统的真功夫。