1. 支付子模块在微服务架构中的定位与拆分逻辑1.1 为什么支付要单独拆成一个子模块做过几个交易类系统之后我越来越觉得支付这个环节天生就该独立。原因不复杂它有三个非常鲜明的特征——资金强一致、外部依赖多、安全等级高。把这三点中的任何一点放到主业务工程里都会让整个项目变得又重又脆。先说资金强一致。订单可以最终一致库存可以异步扣减但支付状态一旦落库就必须和渠道回执、账户流水严格对齐。这种强一致诉求意味着支付模块的代码里会大量出现幂等校验、状态机流转、对账补偿这些逻辑它们和商品、营销、用户这些业务逻辑混在一起维护成本会指数级上升。再说外部依赖。支付要对接的渠道五花八门每个渠道的签名算法、回调格式、超时策略都不一样。如果把这些适配代码塞进主工程一次渠道升级就可能引发整个应用重新发布风险完全不可控。拆成独立子模块之后渠道适配层可以单独迭代主业务几乎无感。最后是安全等级。支付涉及密钥、证书、回调验签这些敏感资产不应该散落在业务代码里。独立模块可以单独做密钥管理、单独做访问控制、单独做审计日志边界清晰出问题也容易定位。所以在这个项目里我把支付拆成了一个独立的 SpringCloud 子模块对外只暴露少量接口对内封装全部渠道细节。这个决策不是拍脑袋而是踩过坑之后的必然选择。1.2 子模块的职责边界怎么划拆分最怕的就是边界模糊。我见过不少项目支付模块里塞了订单查询、塞了用户余额、塞了优惠券核销最后又变成一个单体。所以在动手之前我先把职责边界写清楚属于支付模块的支付单创建、渠道路由、签名与验签、支付状态机、回调处理、主动查询、退款发起、对账文件解析。不属于支付模块的订单金额计算、优惠分摊、库存锁定、用户身份鉴权、消息推送。这条边界的关键在于支付模块只认支付单不认业务订单。业务系统传进来的是一个已经算好金额、带好业务标识的支付请求支付模块负责把它变成一笔可支付的交易并跟踪它的最终状态。至于这笔钱对应哪个订单、哪个用户支付模块只做记录不做业务判断。这样划分之后支付模块的输入输出非常稳定上游业务怎么变它都不用跟着改。这也是微服务拆分里最朴素的一条经验按变化频率拆而不是按功能列表拆。1.3 技术选型与版本搭配的考量这个项目用的是 SpringCloud 体系具体版本搭配我选的是 SpringBoot 2.7.x SpringCloud 2021.x SpringCloud Alibaba 2021.x。为什么不用更新的版本因为支付模块对稳定性要求极高新版本里一些响应式改造、配置中心协议变更在支付这种同步强一致的场景里反而会引入不确定性。注册中心用 Nacos配置中心也用 Nacos这样一套组件解决两个问题运维成本低。网关用 SpringCloud Gateway支付回调走独立路由避免和普通业务流量混在一起。服务间调用用 OpenFeign但支付模块对外提供的接口我额外做了一层 HTTP 直连的兼容因为渠道回调有时候不走服务发现直接打 IP 更稳。数据库层面支付单主库用 MySQL配合本地消息表做最终一致。缓存用 Redis主要存幂等键和渠道配置。消息队列用 RocketMQ处理支付成功后的异步通知。这套组合不是最时髦的但在我实际跑过的几个项目里它是最不容易出幺蛾子的。提示支付模块的技术选型稳定性的优先级永远高于先进性。一个新组件省下来的开发时间可能还不够你排查一次线上资金差异。2. 工程结构搭建与核心依赖配置2.1 模块目录结构设计一个清晰的目录结构能让后来接手的人少骂你几句。我在这个支付子模块里用的是经典的分层结构但做了一点微调把渠道适配单独抽了一层payment-service ├── payment-api // 对外暴露的接口定义与DTO ├── payment-domain // 领域模型、状态机、核心业务逻辑 ├── payment-infrastructure // 数据库、缓存、MQ、渠道SDK适配 ├── payment-application // 应用服务编排领域逻辑 └── payment-bootstrap // 启动模块配置与入口这么拆的好处是payment-api可以被上游业务直接依赖拿到的是干净的接口和 DTO不会把领域内部的实体泄露出去。payment-infrastructure里放各个渠道的适配器每个渠道一个 package新增渠道不影响其他代码。我特别想强调的是payment-domain这一层。支付状态机、幂等规则、金额校验这些最核心的逻辑都放在这里它不依赖任何框架纯 POJO单元测试跑起来飞快。这一点在支付场景里太重要了因为状态流转的边界条件特别多没有快速单测根本不敢改。2.2 核心依赖与版本管理依赖管理我用的是父 POM 统一管控版本子模块只声明 groupId 和 artifactId。支付模块额外引入的依赖主要有这几类!-- 服务注册与配置 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId /dependency !-- 服务调用 -- dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-openfeign/artifactId /dependency !-- 数据访问 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId /dependency !-- 消息队列 -- dependency groupIdorg.apache.rocketmq/groupId artifactIdrocketmq-spring-boot-starter/artifactId /dependency这里有个细节值得说支付模块不要引入 SpringCloud LoadBalancer 的默认轮询策略。因为支付请求往往带有渠道偏好需要按渠道做灰度或者按权重路由所以我在 Feign 配置里自定义了负载均衡规则后面会细讲。另外渠道 SDK 我强烈建议用「适配器模式」包一层不要让渠道的 jar 直接渗透到业务代码里。我见过一个项目渠道 SDK 升级后方法签名变了结果整个支付模块编译不过就是因为没有做隔离。2.3 配置文件的分环境管理支付模块的配置分三块数据库、渠道密钥、业务开关。我的做法是数据库连接、Nacos 地址这些基础配置放在bootstrap.yml通过 Nacos 的 namespace 区分环境。渠道密钥、证书路径这些敏感配置放在 Nacos 的加密配置里本地不落盘。业务开关比如某个渠道是否启用、单笔限额放在数据库配置表支持运行时动态调整。spring: application: name: payment-service cloud: nacos: discovery: server-addr: ${NACOS_ADDR} namespace: ${NACOS_NAMESPACE} config: server-addr: ${NACOS_ADDR} namespace: ${NACOS_NAMESPACE} file-extension: yaml注意渠道密钥千万不要写在代码仓库里哪怕是用占位符。我踩过的坑是有人把测试密钥提交上去结果被扫描工具抓到虽然只是测试环境但整改流程走了一周。3. 支付核心链路的设计与实现3.1 支付单模型与状态机设计支付单是整个模块的核心实体。我设计的字段大致分四组标识组支付单号、业务单号、渠道单号、金额组应付金额、实付金额、币种、状态组支付状态、退款状态、时间组创建、支付、完成、关闭时间。状态机我用的是枚举加流转表的方式而不是引入重型工作流引擎。原因很简单支付状态就那么几个用引擎反而增加理解成本。核心状态流转是这样的当前状态允许的下一状态触发条件INITPAYING调用渠道下单成功PAYINGSUCCESS收到渠道成功回执PAYINGFAILED渠道返回失败或超时关闭PAYINGCLOSED超过支付有效期SUCCESSREFUNDING发起退款REFUNDINGREFUNDED退款成功REFUNDINGREFUND_FAILED退款失败状态流转必须走统一的方法不允许任何地方直接 set 状态。我在PaymentOrder实体里写了一个transferTo方法内部校验当前状态是否允许流转不允许就抛异常。这样即使后来有人写错代码也会在测试阶段就暴露出来。public void transferTo(PaymentStatus target) { if (!this.status.canTransferTo(target)) { throw new IllegalStateException( 非法状态流转: this.status - target); } this.status target; this.updateTime LocalDateTime.now(); }3.2 渠道路由与适配器模式落地渠道路由解决的是「这笔支付走哪个渠道」的问题。我的路由策略分三层第一层按业务方指定的渠道走第二层按金额和渠道限额过滤第三层按渠道健康度和权重做负载。适配器接口定义得很简单public interface PaymentChannelAdapter { ChannelType getChannelType(); PrepayResult prepay(PrepayCommand command); CallbackResult parseCallback(String rawBody, MapString, String headers); QueryResult query(String channelOrderNo); RefundResult refund(RefundCommand command); }每个渠道实现这个接口注册到 Spring 容器里路由时根据ChannelType取对应的 Bean。新增渠道只需要加一个实现类不改任何现有代码这就是开闭原则在支付场景里的实际价值。这里有个实操心得回调解析一定要做原始报文留存。我遇到过渠道回调格式悄悄变更的情况如果没有存原始报文根本没法复现问题。所以我在parseCallback之前先把 rawBody 和 headers 落库再做解析。3.3 幂等与防重设计支付场景里幂等是生命线。我的幂等设计分两个层面第一层是请求幂等。上游业务调用支付创建接口时必须带一个业务方生成的请求号。我用 Redis 做分布式锁key 是payment:req:{requestNo}value 是支付单号过期时间设 24 小时。同一个请求号重复进来直接返回已有的支付单号不重复创建。第二层是回调幂等。渠道回调可能重复推送我用渠道单号加支付单号做唯一索引插入回调记录表时如果冲突就说明已处理过直接返回成功。这里要注意回调幂等表要单独建不要和支付单表混在一起因为回调记录需要保留多次推送的痕迹方便排查。// 回调幂等处理 try { callbackLogMapper.insert(callbackLog); } catch (DuplicateKeyException e) { log.warn(重复回调直接返回成功: {}, callbackLog.getChannelOrderNo()); return CallbackResult.success(); }提示幂等键的过期时间要大于渠道的最长重试周期。我一般设 24 小时因为大部分渠道的重试窗口不超过 12 小时。4. 服务间通信与分布式事务处理4.1 OpenFeign 调用与超时配置支付模块和上游业务、下游账务之间都有调用。上游调支付创建支付调账务记账。Feign 的默认超时是 1 秒在支付场景里太短了因为渠道下单有时候要 3 到 5 秒。我的配置是连接超时 2 秒读取超时 8 秒并且针对不同下游做差异化配置。feign: client: config: default: connectTimeout: 2000 readTimeout: 8000 account-service: connectTimeout: 1000 readTimeout: 3000为什么要差异化因为账务服务的接口是纯本地操作快而渠道下单涉及外部网络慢。统一配置要么拖慢快的要么拖垮慢的。另外Feign 调用一定要配重试但支付创建接口不能重试。因为创建支付单不是幂等操作虽然有请求号兜底但重试会增加渠道压力。我的做法是查询类接口开重试写类接口关闭重试靠上游的请求号幂等来保证。4.2 本地消息表实现最终一致支付成功后要通知业务方这个通知不能丢。我用的是本地消息表方案支付状态更新和消息记录插入在同一个本地事务里然后由定时任务扫描消息表投递到 RocketMQ投递成功再更新消息状态。这个方案的好处是不依赖 MQ 的事务消息实现简单可控性强。缺点是有一点点延迟但支付通知本来就不要求毫秒级。Transactional public void handlePaymentSuccess(String paymentNo) { PaymentOrder order orderMapper.selectByNo(paymentNo); order.transferTo(PaymentStatus.SUCCESS); orderMapper.updateById(order); LocalMessage message LocalMessage.build( PAYMENT_SUCCESS, order.getBizOrderNo(), order); messageMapper.insert(message); }定时任务每 5 秒扫一次待投递消息投递成功后把状态改成已投递。如果投递失败记录重试次数超过阈值告警。这里的关键是消息表和支付单在同一个库才能保证本地事务。4.3 分布式事务的取舍有人会问为什么不用 Seata 这种分布式事务框架我的回答是支付场景里强一致的边界应该尽量收窄到单库。支付单和消息表在同一个库用本地事务就够了。跨库的强一致比如支付和账务我用的是 TCC 的简化版——支付先记「待记账」账务记账成功后回调支付确认失败则走补偿。这样做的原因是Seata 的 AT 模式在支付这种高并发场景下全局锁的争用会很严重。而支付的核心诉求是「不丢、不重、可对账」不是「实时强一致」。只要最终能对上账中间状态短暂不一致是可以接受的。注意任何分布式事务方案都要配一个对账兜底。我见过太多项目事务框架用得很溜但一对账就发现差异最后还是靠人工补单。5. 支付回调与对账的实战细节5.1 回调接口的安全设计回调接口是支付模块最容易被攻击的入口。我的安全设计有四道防线第一道是来源 IP 白名单。渠道回调的 IP 段是固定的网关层直接过滤非白名单 IP 直接拒绝。第二道是签名验签。每个渠道的签名算法不同但核心都是「参数排序 密钥 摘要」。验签失败直接返回失败不进入业务逻辑。第三道是金额校验。回调里的金额必须和支付单金额一致不一致就告警并挂起绝不自动处理。第四道是状态校验。只有 PAYING 状态的支付单才处理回调已经是 SUCCESS 的直接返回成功幂等其他状态记录异常。public CallbackResult handleCallback(String channel, String rawBody) { // 1. 验签 if (!channelAdapter.verifySign(rawBody)) { return CallbackResult.fail(签名校验失败); } // 2. 解析 CallbackResult result channelAdapter.parseCallback(rawBody, headers); // 3. 金额校验 PaymentOrder order orderMapper.selectByNo(result.getPaymentNo()); if (!order.getAmount().equals(result.getAmount())) { alarmService.send(金额不一致, order, result); return CallbackResult.fail(金额不一致); } // 4. 状态处理 return paymentService.handleCallback(order, result); }5.2 主动查询与补偿机制回调不是 100% 可靠的渠道可能推送失败网络可能抖动。所以必须有主动查询兜底。我的做法是支付单创建后如果 30 秒内没收到回调就触发一次主动查询之后每隔 1 分钟查一次最多查 5 次5 次还没结果就标记为「待人工处理」。主动查询的结果处理和回调走同一套逻辑只是入口不同。这样能保证状态流转的一致性。补偿机制还包括超时关闭。支付单创建后设一个有效期比如 15 分钟超过就自动关闭。关闭前再查一次渠道确认没支付成功才关。这个「关闭前查询」很关键我踩过的坑是用户在第 14 分 59 秒支付成功但回调延迟结果支付单被关了钱却扣了最后只能走退款。5.3 对账文件的解析与差异处理对账是支付的最后一道防线。每天凌晨拉取渠道的对账文件和本地支付单逐笔比对。差异分三类差异类型表现处理方式本地有渠道无本地成功渠道无记录挂起人工核查渠道有本地无渠道成功本地无记录补单触发业务通知金额不一致两边都有但金额不同挂起人工核查对账文件的解析要注意编码和分隔符不同渠道差异很大。我一般先做一次「预解析」把文件转成标准格式再做比对。比对结果落库生成对账报表差异项自动告警。提示对账任务一定要做幂等同一天的对账文件重复拉取不能重复处理。我用「渠道 对账日期」做唯一键。6. 常见问题排查与避坑经验6.1 支付状态不一致的排查思路状态不一致是最常见也最头疼的问题。我的排查顺序是先看支付单当前状态和更新时间再看回调记录表再看渠道查询结果最后看本地消息表。这四张表串起来基本能还原整个时间线。有一次线上出现「用户已付款但订单未更新」排查发现是回调处理成功但消息投递失败定时任务又因为线程池满了没跑。后来我把消息投递的线程池独立出来不和业务线程共用问题就没了。6.2 渠道超时与重试的坑渠道超时后不能简单重试因为可能已经下单成功。我的做法是超时后先查询查询到已下单就复用查询不到再重试。重试次数不超过 2 次且每次重试前都要查询。还有一个坑是渠道的幂等窗口。有些渠道只保证 5 分钟内的幂等超过 5 分钟用同一个请求号会创建新单。所以请求号的设计要带时间戳避免跨窗口复用。6.3 高频问题速查表问题现象可能原因排查动作回调验签失败密钥不匹配、参数被篡改核对密钥、打印原始报文支付单重复创建请求号未生效、锁失效检查 Redis 锁、查请求号记录状态卡在 PAYING回调丢失、查询未触发查回调记录、手动触发查询对账差异多时区问题、金额精度核对时区配置、检查 BigDecimal消息重复投递消息表状态未更新查消息表、检查定时任务6.4 几个我踩过的坑第一个坑是金额用 double。早期图省事用了 double结果对账时出现 0.01 的差异。后来全部改成 BigDecimal并且统一用「分」做单位彻底解决。第二个坑是回调接口没做限流。有一次渠道异常短时间内推了大量重复回调把数据库连接池打满了。后来在网关层加了限流单渠道回调 QPS 限制在合理范围。第三个坑是日志打印了完整报文。支付报文里有敏感信息日志里不能全打。我的做法是脱敏后再打只保留关键字段。第四个坑是时区。渠道用 UTC本地用东八区对账时日期对不上。后来统一在入库时转成东八区展示时再按需转换。7. 性能优化与上线前的检查清单7.1 数据库层面的优化支付单表的数据量增长很快我做了几件事一是按支付单号做分库分表用 ShardingSphere 按支付单号取模二是冷热分离三个月前的数据归档到历史表三是索引优化业务单号、渠道单号、创建时间都建了索引。查询接口全部走覆盖索引避免回表。支付单详情这种低频查询才走主键查全字段。7.2 缓存的使用边界缓存只用在两个地方幂等键和渠道配置。支付单本身不缓存因为状态变化频繁缓存一致性成本太高。渠道配置变化少缓存 10 分钟用 Nacos 的配置监听做刷新。注意支付单绝对不要用缓存做状态判断一定要查库。缓存和库不一致导致的资金问题排查起来极其痛苦。7.3 上线检查清单上线前我一般会过一遍这个清单渠道密钥是否配置正确测试环境是否验证通过回调白名单 IP 是否更新数据库索引是否建全定时任务是否配置线程池是否独立对账任务是否配置告警是否接通限流规则是否生效日志脱敏是否生效回滚方案是否准备好这个清单看起来简单但每次上线前过一遍能避免 80% 的低级事故。我在实际项目里支付模块的上线从来不敢省这一步。最后分享一个小技巧支付模块的日志一定要打「支付单号」这个贯穿全链路的标识从创建到回调到对账所有日志都带上它。排查问题时一个 grep 就能拉出完整链路比翻好几个服务的日志高效得多。这个习惯我保持了几年每次线上出问题都能省下大量时间。