五年级 Java 转支付方向,第一个要建立的认识:支付的本质是钱的状态机 + 跨系统对账。这篇用 IJPay 这个「不依赖任何框架的工具库」走一遍支付三条链路,顺便把支付小白的十一个高频坑钉死。
前置阅读:18.4 讲过验签与防重放。这篇把它们放进完整支付链路里看。
下单链路:创建订单 → 组装参数 → 签名 → 调统一下单接口 → 返回支付凭证
回调链路:第三方 → 你的 /notify → 验签 → 幂等更新订单 → 返回 SUCCESS
查单链路:主动查单(补偿)→ 对账 → 差异处理
IJPay 的定位要认清:它只封装三件事——接口地址枚举、签名/验签/加解密工具、HTTP 调用代理。订单、对账、幂等、分布式事务它一概不管,这些是业务层自己的真功夫。把工具库当框架用,是支付小白第一坑。
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 加平台证书的加解密。下单用哪套、回调就验哪套,两把钥匙互开不了对方的锁——混用是「验签永远失败」的头号原因。
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,验签、幂等、补偿三大件才是支付系统的真功夫。