简介在Java服务端开发中支付系统设计一直是高并发与资金安全的核心挑战。聚合支付作为连接商户与持牌机构的中间层通过统一API封装微信、支付宝等渠道差异成为众多业务系统快速接入支付能力的关键方案。理解支付网关的路由机制、异步回调的幂等保障以及掉单对账的兜底策略是构建可靠交易链路的基础。Jeepay作为一套完整开源的四方支付平台基于Spring Boot和MyBatis-Plus实现了商户入驻、渠道参数管理、订单状态机、定时对账等生产级模块。其清晰的模块划分与扩展点设计为Java开发者提供了从支付中台搭建到渠道接入的完整参考。本文从聚合支付概念出发结合Jeepay源码解析支付核心链路并分享本地部署与二次开发实战经验帮助读者系统掌握支付系统的工程化落地路径。 做Java开发这些年接支付大概是最绕不开的需求之一。不管你做的是电商小程序、外卖平台还是SaaS系统早晚都会碰到同一件事怎么让用户把钱付进来。自己接支付宝、微信支付一家一家谈资质、签协议、排队审核再来回联调周期拉得极长用现成的聚合支付SaaS省事是真省事可每笔手续费、结算周期、交易数据全部握在别人手里平台方说接口调整你就得跟着改。后来我开始认真关注开源的Java支付系统Jeepay就是这么进入我视野的。它是一套完整的全开源聚合支付平台或者说四方支付系统的Java实现从商户入驻、接口签名到支付渠道路由、异步回调、定时对账整条链路全部开放源码适合想做支付中台、聚合支付服务商或者就是单纯想搞懂交易系统怎么运作的开发者。这篇文章我会先澄清几个行业概念再拆解Jeepay的代码结构和核心链路然后给出一套能在本地把支付流程完整跑通的实操路径最后聊一聊二次开发时最容易踩的坑。全程以我自己的实操经历为主尽量说人话。1. 先把行业术语捋清楚聚合支付、四方支付到底是什么1.1 商户接支付的现实困境很多人第一次接触支付系统第一反应是不就是调个微信支付API吗。真做起来才发现这里面的门道远比想象中多。先说直连第三方支付。以微信支付为例你需要先申请商户号审核营业执照、法人信息、经营场景个人开发者基本很难拿下来。支付宝稍微灵活一点但也需要完整的认证流程。就算你顺利拿到了商户号接下来的联调也够喝一壶微信支付的API风格和支付宝完全不同微信老版本接口还是XML报文加MD5签名新版本V3走JSON加AES敏感信息加密支付宝是RSA2签名加表单提交。如果你还想接云闪付、银联扫码又是完全独立的一套协议和加密规范。维护N套渠道对接代码每套渠道升级API你都要跟着升级这就是现实。比起技术问题更深层的痛点是生态问题。很多做平台型业务的团队需要的不是单纯收款而是让多个商户入驻进来每个商户独立配置密钥、独立查看账单、独立提现或分账。这种业务模型实际上是一个小型支付服务商但直连持牌机构对于普通团队来说门槛很高。于是市场上出现了聚合支付服务商他们本身不一定持有支付牌照但是对接了多家持牌第三方的通道给商户提供一个统一API和一个统一管理后台商户面对的是同一个界面不用关心底层到底走了微信还是支付宝还是银行卡。1.2 Jeepay在产业链中扮演的角色产业里习惯把聚合支付服务商叫做四方支付。四方是相对于发卡行、清算组织、第三方支付机构这些传统角色而言的本质是在持牌机构之上再做一层技术聚合与商户服务。正因为它不直接碰资金定位更像一个技术服务平台所以在守住合规红线的同时普通公司也具备参与的可能。Jeepay就是这类四方支付/聚合支付平台的开源实现。它的定位很清楚让开发者拿到源码之后能够快速搭建一套具备聚合支付能力的业务系统。商户在后台完成入驻、创建支付应用、拿到AppId和密钥支付网关统一接收下单请求根据支付方式路由到对应的渠道通道渠道异步回调进来后系统完成验签和订单状态更新再向商户系统发起回调。我在实际使用中明显感受到这套系统不是那种只能看看的玩具Demo。它考虑了非常多的生产级场景多租户商户体系、应用隔离、支付路由、异步通知重试机制、账号安全和操作日志甚至连运营商平台、商户平台、支付网关三个独立Web应用怎么拆分都安排得明明白白。1.3 为什么四方支付这个词容易让人误解这里必须多说一句因为四方支付在很多人印象里多少带点灰色。实际上正规的第四方支付/聚合支付服务商绝对不允许碰资金。什么叫不碰资金就是商户的钱始终通过持牌支付机构或者银行渠道结算平台本身只做订单信息流和商户管理不形成资金池不做二清。为什么我要强调这一点因为选型的时候你怎么理解这层业务边界直接决定了系统的架构方式。在Jeepay这类合规模型里支付网关永远只是把交易请求转发给持牌渠道订单状态跟着渠道回调走商户结算也是由底层持牌机构来完成平台去做的只是对账。理解了这个边界后面看代码的时候你就知道哪些模块是核心哪些模块绝对不能碰钱。2. Jeepay系统是怎么组织代码的三大端与核心模块2.1 从仓库拿到源码后的第一眼印象不管你是下载zip包解压还是用git clone拉代码打开工程之后第一感觉就是这不是一个单体大泥球而是一个按业务域拆分的多模块项目。整个仓库大致可以分成五块运营平台manager、商户平台merchant、支付网关payment、定时任务job和公共核心模块core另外还有前端工程和数据库脚本。这里我比较建议大家不要看到多个应用就紧张。它们的代码都在同一个仓库里没有做成分布式微服务模块之间通过共享数据库和接口调用协作部署上完全可以用一台2核4G的小服务器跑起来。这种设计对绝大多数想做聚合支付业务的技术团队来说是一个非常务实的架构有清晰的业务边界又不会像微服务那样引入过多治理成本。Jeepay的后端技术栈是很典型的Java服务端组合Spring Boot做应用框架MyBatis-Plus做ORMMySQL做业务存储Redis做缓存和部分幂等控制。前端用的是Vue加Element UI运营平台和商户平台各有一套独立的前端工程。整体看下来这套技术栈对一个Java团队来说几乎没有学习成本招人也好招维护起来不愁。2.2 三个Web应用的职责边界运营平台、商户平台、支付网关这三个Web应用是理解整套系统的主线。我先用一句大白话总结它们的关系运营平台是招商和配置中心商户平台是给商户用的前台支付网关是真正处理交易流量的核心。运营平台给平台运营方用的。在这里创建商户、审核商户资料、给商户配置支付渠道参数。比如你的平台对接了微信支付的某个服务商通道那渠道参数就是在这个后台维护的。运营平台还要负责查看整盘交易数据、处理异常订单、配置系统参数。它是整套系统的管理中枢权限层级最高。商户平台的权限范围就收敛到具体商户。商户账号登录进去之后可以看到自己的支付应用列表创建支付应用获取AppId和AppSecret配置交易回调地址查看交易明细和账单。商户平台还有一个很重要的作用让商户可以自助完成大部分前后端联调前的准备工作不需要每次找平台方开工单。支付网关是每一笔交易真正经过的地方。商户通过服务端请求支付网关的下单接口支付网关解析签名、做参数校验、路由到对应的支付渠道然后同步返回收银参数或二维码信息。渠道的异步回调也由支付网关接收它先做回调验签再更新订单状态最后把支付结果通知给商户自己的系统。可以看出支付网关这套服务承载了最重的技术逻辑也是我们做二次开发时最需要重点研究的模块。2.3 数据库里最核心的几张表数据库设计是理解业务逻辑的关键入口。我把Jeepay的表结构大致梳理了一下重点看这几类核心表就能把业务串起来。商户信息表是业务的源头保存商户号对外业务标识、商户名称、状态、管理员账号等基础信息。商户应用表是紧跟在商户后面的概念一个商户可以创建多个应用每个应用对应一组AppId和AppSecret下单时靠appId区分是哪一套业务在发起交易。应用和回调地址绑定这样不同业务线的回调通知可以投递到不同的地址。支付订单表是整个库里的核心事实表每一笔交易都有一条订单记录关键是状态字段初始化、支付中、成功、失败、关闭这几种状态之间的流转严格跟支付链路的各个阶段对应。支付渠道定义表和渠道参数表则解决交易走哪个通道、参数怎么配的问题前者定义支付方式的代码比如微信Native、支付宝Wap后者加密保存真实渠道侧的商户号和密钥。从这几张核心表能看出一个很有意思的架构特征Jeepay通过商户-应用-渠道参数三层配置实现了多商户和多渠道的灵活组合。一个商户想接微信又接支付宝只需要创建应用并且在应用下挂不同的渠道参数支付方式的选择完全由商户调用方传过来的参数决定这种设计让系统的扩展性大大提升。3. 本地搭一套可运行环境把第一笔支付真实跑通3.1 准备清单与几个容易踩环境的坑跑通Jeepay的方式我建议直接按照先后端后前端先数据库后应用的顺序来。首先把依赖环境准备好JDK 8或11、Maven 3.6以上、MySQL 5.7或8.0、Redis 5.0以上。如果你还想把商户平台和运营平台的前端页面跑起来就需要Node.js环境前端工程基于Vue 2Node 14到16之间比较稳妥太新版本可能会在构建依赖时出兼容问题。这里有几个坑我在第一次部署时都踩过提前写出来能帮大家节省时间。第一个是MySQL的时区问题如果使用MySQL 8连接串里一定要加上serverTimezoneAsia/Shanghai否则驱动会报时区错误同时加上allowPublicKeyRetrievaltrue避免新版驱动默认禁止公钥检索导致连接失败。第二个是Redis如果你本机Redis设置了密码数据库配置里连着改了Redis密码和数据库编号两个配置项很容易漏。第三个是端口冲突三个后端应用默认占用了不同端口但如果你本机有别的服务占用需要进application.yml里改尤其要识别清楚哪个配置对应哪个子工程。3.2 初始化数据库与修改配置代码准备好之后先在MySQL里创建一个空数据库比如jeepay_demo字符集用utf8mb4。然后找到工程里带的SQL脚本把脚本导入到这个库里。脚本一次性把核心表、基础数据、演示商户和演示应用全部初始化好这个设计非常贴心意味着导入完成之后你已经有了一套带演示账号的可运行数据。接下来修改配置。需要改的东西集中在各应用下的application.yml也可能是application-prod.yml等等核心内容有两块数据源配置和Redis配置。把URL、用户名、密码改成你本机的真实环境然后把Redis连接信息同步调整。MySQL驱动的大部分配置已经在默认配置里写好了一般不用动。需要提醒的是源码里的配置文件并不是只有一处。我第一次跑就是只改了主配置文件忽略了另一个模块下的配置结果支付网关连不上数据库。建议全局搜索一下jdbc:mysql关键字把出现的地方挨个核对一遍再启动。3.3 编译、启动然后用演示商户完成首笔支付配置完成后回到工程根目录执行Maven打包。命令不复杂mvn clean install -DskipTests。整个编译过程会下载大量依赖国内网络环境建议先配置阿里云Maven镜像不然下载到一半卡住非常崩溃。打包成功后三个应用的jar包分别在各自模块的target目录下。启动顺序其实没有严格要求因为它们共享同一个数据库。不过从逻辑上讲我习惯先启动运营平台和商户平台最后启动支付网关。三个应用都起来之后浏览器分别访问对应的管理端口用初始化脚本里的演示管理员账号登录运营平台再用演示商户账号登录商户平台。在商户平台里找到我的应用里面已经有一个初始化好的演示应用可以看到AppIdAppSecret需要重置或者查看。接下来就是重头戏构造一笔真实的下单请求。你可以用POST工具或者直接写一小段Java代码调用支付网关的下单接口核心参数包括商户号、应用ID、支付方式代码、商户订单号、金额、回调地址。签名规则在官方文档里有标准说明核心思路是把业务参数按规范组织后用AppSecret做摘要生成签名网关收到请求后会用同一个密钥重新计算签名比对。请求成功之后接口会返回一个二维码内容或者跳转链接。在支付渠道侧我们当然没有真实的商户号所以实际支付这一步是走不通的但系统的订单状态流转可以完整演示下单后查询订单是支付中渠道回调没有进来的话定时任务会一直保持订单状态。如果你想看到完整的成功闭环可以用沙箱环境配合测试账号或者自己在回调逻辑里做模拟。这些都不影响我们理解系统全貌。4. 支付链路的本质从下单到回调的完整闭环4.1 一次下单请求网关在背后做了什么把流程跑通之后很有必要再深入看一下下单接口内部到底做了什么。我打了一个断点跟着调用链走了一遍发现整个过程可以抽象成四个步骤。第一步是参数合法性校验和签名校验。网关接口对外有统一的请求结构首先看商户号是否存在、应用是否属于该商户、支付方式是否有效、金额是否在允许范围、签名是否正确。这一步存在的意义是挡掉绝大部分伪造请求签名校验不过直接丢弃。第二步是生成平台侧订单。商户传过来的订单号是商户业务系统的单号不允许重复网关会生成一个平台内部订单号把商户号、应用ID、渠道代码、金额、状态等信息落库状态初始化为支付中。第三步是路由到具体渠道。这就是之前提到的聚合能力核心系统按照请求里的wayCode找到对应的支付渠道处理器然后调用该处理器去创建渠道侧订单。每个渠道处理器封装了对底层接口的调用逻辑比如微信的Native支付如何生成code_url支付宝的电脑网站支付如何生成Form表单这些差异被完全隔离在渠道处理器内部对上层是透明的。第四步是统一响应。不管底层是哪个渠道返回给商户的都是统一的JSON结构里面可能包含二维码链接、支付跳转地址或必要的支付参数。对商户系统来说它只需要解析这个统一结构然后引导用户去支付就行根本不需要关心底层渠道是谁。4.2 为什么异步通知要设计重试和幂等缺一不可用户完成支付之后渠道会给支付网关发异步通知。这里有一个非常关键的设计原则异步通知是不可靠的它可能延迟、可能丢失、也可能重复。微信和支付宝官方对异步通知都有一套重试机制如果接收方没有正确返回成功确认渠道会在接下来的一段时间内按不同间隔多次重发。所以网关接收渠道回调后第一件事永远是验签确认这条通知确实来自真实渠道防止伪造回调改订单状态。验签通过后系统更新本地订单状态再组装一个面向商户系统的回调通知往商户配置的回调地址投递。商户收到这个回调后必须返回一个特定字符串通常是success否则网关会按照自己的重试策略再次推送。这里容易犯的一个经典错误是把幂等实现做漏。正常的支付流程中微信可能回调两次我们的系统也可能因为网络抖动重发回调如果回调处理逻辑不幂等就会导致订单状态被反复更新、甚至触发重复发货。我在自己改造的时候对订单状态更新使用条件更新SQL只有订单当前处于支付中状态时才允许更新为成功从数据库层面就锁死了状态唯一流转这个思路推荐大家参考。4.3 掉单不可避免主动查单和对账才是兜底方案回调机制再完善也会有极端情况用户确实付款了但渠道的回调网络异常一直没发到我们服务器订单就一直卡在支付中。这就是掉单。掉单靠等待是永远等不回来的必须靠两个机制来兜底。第一个是主动查单。支付状态下系统定时任务会扫描那些超过一定时间仍然处于支付中的订单主动调用渠道的查单接口把渠道侧的支付结果同步回来。如果查到已经支付成功就主动把订单状态更新并触发后续的商户回调。这个做法在Jeepay里是由jeepay-job这个定时任务模块承担的。第二个是对账。即便主动查单也解决不了所有问题比如退款状态不一致、渠道侧有记录而平台侧没有所以每天定期拉取渠道的对账文件逐笔和平台订单做比对把不一致的数据找出来人工处理。这一层是支付系统的最后防线可能几天不触发一次但一旦真出了问题它就是挽回损失的唯一手段。5. 二次开发时最需要注意的几个地方5.1 挂接新支付渠道的扩展点我在本地把流程跑通之后做的第一件深度改造是给系统挂一个新的支付渠道。这里有个体验特别好的地方Jeepay对渠道接入的抽象做得很清晰扩展一个新的渠道不需要修改支付网关的主流程。大致路径是在支付渠道定义表里新增一条渠道记录配置好渠道代码和支付方式然后根据渠道处理器的抽象基类写一个子类实现统一下单、订单查询、关单、回调解析这几个方法最后把渠道参数加密存进渠道参数表。做完以上几步新的支付渠道就能在运营平台后台被配置到具体应用上下单时通过对应的wayCode就能路由过来。我在开发时还做了一件事在实现类里加了渠道侧与平台侧的订单号映射表。渠道返回的channelOrderNo要能在平台侧随时查到再配合定时任务做差异对账两个系统之间的状态完全对得起来。从这件事上我也体会到扩展一个渠道代码本身只占一小部分真正花时间的是渠道的文档理解、沙箱联调、异常场景梳理。5.2 金额精度、状态并发两个最隐蔽的Bug温床支付系统里有两个问题几乎每个入门者都会栽跟头一个是金额用浮点类型另一个是订单状态更新没有并发控制。金额问题听起来很基础但在实际项目中依然屡见不鲜。以分为单位用Long类型保存金额是支付系统的标准做法数据库里的金额字段也建议直接用BIGINT或DECIMAL(20,2)。千万不要在代码里用double做金额计算精度丢失一旦发生哪怕只是几分钱也对账和审计都解释不清楚。我自己在扩展还款类业务时就差点踩进去后续统一把所有金额都改成以分为单位的长整型传输从源头消除问题。状态并发问题更隐蔽。想象这样一个场景用户支付成功渠道回调正在更新订单状态此时另一个主动查单的定时任务也查到了成功结果两个线程同时更新同一条订单记录如果代码是先查询再更新就可能出现状态反复横跳。解决办法是放弃SELECT后UPDATE的写法直接执行条件更新UPDATE 订单表 SET 状态成功 WHERE 订单号? AND 状态支付中更新影响行数为0就说明已经被其他流程更新过了直接返回。这种乐观方式在支付系统里非常实用。5.3 上线前必须做的安全加固清单开源系统可以直接部署但安全加固这类事情代码不会替你做完上线前必须自己过一遍。我把自己在Jeepay二次开发后做的一轮安全审计清单分享一下。首先HTTPS是必备前提不管是支付网关对外接口还是商户平台、运营平台的访问入口全部走HTTPS密钥在明文HTTP下传输等于裸奔。第二回调地址要做白名单和校验商户配置的回调地址不能随意跳转到第三方域这里除了验签还可以限制只允许绑定过的域名端口。第三渠道参数存储必须加密数据库里如果被人拖走了明文密钥直接导致商户资金风险所以至少要使用AES加密存储密钥单独放在环境变量里。第四运营平台和商户平台的登录需要开启验证码和登录失败次数限制防止暴力破解。第五所有接口都做操作日志和审计支付系统出事之后能不能快速定位问题全靠日志全不全。除了这些技术手段还有一点容易忽略依赖安全。Jeepay依赖了一堆第三方库开源系统自己不会主动提醒你哪些组件有漏洞建议引入一个依赖漏洞检查工具定期扫一遍该升级的升级该修复的修复。6. 我在实操中的经验与建议翻来覆去说完了Jeepay的架构、部署、链路和二次开发最后分享几点个人体会。第一如果纯粹为了学习千万不要只停留在能启动这个层面。我强烈建议你按照我上文的方式自己模拟一条渠道回调把订单从支付中变成成功亲眼看看商户回调触发了什么、订单状态在哪里被更新、定时任务如果重复查单会怎么样。这一套流程走下来你对支付系统的核心难点在可靠性这句话的理解会深入很多。第二每次在群里看到有人问有没有成熟的Java聚合支付框架我都会推荐去看Jeepay的源码不是因为它的代码完美无瑕而是因为它把很多真实生产场景的细节都放出来了签名、验签、回调重试、幂等更新、渠道隔离、定时对账。这些知识点散落在八股文里但只有真正在代码里看过了面试或者设计系统时才会形成肌肉记忆。像支付回调为什么要幂等掉单如何处理状态机怎么设计这些经典问题都能在这个项目里找到参考答案。第三如果用这个项目为基础做商业项目一定注意几个前提要厘清自己所在区域的支付业务合规要求确认对接的是持牌机构还是银行通道系统本身只做信息流转绝不能碰资金归集要做好长期维护的心理准备开源系统不等于免维护自己定制化程度越高升级上游版本的成本就越大渠道参数、商户密钥这些敏感信息必须放在足够可靠的安全体系里管理。对我来说Jeepay不仅仅是一套能跑起来的支付系统更像是一座关于聚合支付系统到底应该怎么做的活教材。你可以在上面做二次开发、做渠道扩展、做架构改造甚至可以拿它作为设计自己支付中台的起点。如果你正好也在做类似的方向建议先把这篇文章收藏起来然后动手clone一份源码跑起来再回来对照着看你会发现很多文字描述的东西在代码里都变得异常清晰。本文还有配套的精品资源点击获取 Jeepay开源聚合支付系统：从支付架构到二次开发实战详解
简介在Java服务端开发中支付系统设计一直是高并发与资金安全的核心挑战。聚合支付作为连接商户与持牌机构的中间层通过统一API封装微信、支付宝等渠道差异成为众多业务系统快速接入支付能力的关键方案。理解支付网关的路由机制、异步回调的幂等保障以及掉单对账的兜底策略是构建可靠交易链路的基础。Jeepay作为一套完整开源的四方支付平台基于Spring Boot和MyBatis-Plus实现了商户入驻、渠道参数管理、订单状态机、定时对账等生产级模块。其清晰的模块划分与扩展点设计为Java开发者提供了从支付中台搭建到渠道接入的完整参考。本文从聚合支付概念出发结合Jeepay源码解析支付核心链路并分享本地部署与二次开发实战经验帮助读者系统掌握支付系统的工程化落地路径。 做Java开发这些年接支付大概是最绕不开的需求之一。不管你做的是电商小程序、外卖平台还是SaaS系统早晚都会碰到同一件事怎么让用户把钱付进来。自己接支付宝、微信支付一家一家谈资质、签协议、排队审核再来回联调周期拉得极长用现成的聚合支付SaaS省事是真省事可每笔手续费、结算周期、交易数据全部握在别人手里平台方说接口调整你就得跟着改。后来我开始认真关注开源的Java支付系统Jeepay就是这么进入我视野的。它是一套完整的全开源聚合支付平台或者说四方支付系统的Java实现从商户入驻、接口签名到支付渠道路由、异步回调、定时对账整条链路全部开放源码适合想做支付中台、聚合支付服务商或者就是单纯想搞懂交易系统怎么运作的开发者。这篇文章我会先澄清几个行业概念再拆解Jeepay的代码结构和核心链路然后给出一套能在本地把支付流程完整跑通的实操路径最后聊一聊二次开发时最容易踩的坑。全程以我自己的实操经历为主尽量说人话。1. 先把行业术语捋清楚聚合支付、四方支付到底是什么1.1 商户接支付的现实困境很多人第一次接触支付系统第一反应是不就是调个微信支付API吗。真做起来才发现这里面的门道远比想象中多。先说直连第三方支付。以微信支付为例你需要先申请商户号审核营业执照、法人信息、经营场景个人开发者基本很难拿下来。支付宝稍微灵活一点但也需要完整的认证流程。就算你顺利拿到了商户号接下来的联调也够喝一壶微信支付的API风格和支付宝完全不同微信老版本接口还是XML报文加MD5签名新版本V3走JSON加AES敏感信息加密支付宝是RSA2签名加表单提交。如果你还想接云闪付、银联扫码又是完全独立的一套协议和加密规范。维护N套渠道对接代码每套渠道升级API你都要跟着升级这就是现实。比起技术问题更深层的痛点是生态问题。很多做平台型业务的团队需要的不是单纯收款而是让多个商户入驻进来每个商户独立配置密钥、独立查看账单、独立提现或分账。这种业务模型实际上是一个小型支付服务商但直连持牌机构对于普通团队来说门槛很高。于是市场上出现了聚合支付服务商他们本身不一定持有支付牌照但是对接了多家持牌第三方的通道给商户提供一个统一API和一个统一管理后台商户面对的是同一个界面不用关心底层到底走了微信还是支付宝还是银行卡。1.2 Jeepay在产业链中扮演的角色产业里习惯把聚合支付服务商叫做四方支付。四方是相对于发卡行、清算组织、第三方支付机构这些传统角色而言的本质是在持牌机构之上再做一层技术聚合与商户服务。正因为它不直接碰资金定位更像一个技术服务平台所以在守住合规红线的同时普通公司也具备参与的可能。Jeepay就是这类四方支付/聚合支付平台的开源实现。它的定位很清楚让开发者拿到源码之后能够快速搭建一套具备聚合支付能力的业务系统。商户在后台完成入驻、创建支付应用、拿到AppId和密钥支付网关统一接收下单请求根据支付方式路由到对应的渠道通道渠道异步回调进来后系统完成验签和订单状态更新再向商户系统发起回调。我在实际使用中明显感受到这套系统不是那种只能看看的玩具Demo。它考虑了非常多的生产级场景多租户商户体系、应用隔离、支付路由、异步通知重试机制、账号安全和操作日志甚至连运营商平台、商户平台、支付网关三个独立Web应用怎么拆分都安排得明明白白。1.3 为什么四方支付这个词容易让人误解这里必须多说一句因为四方支付在很多人印象里多少带点灰色。实际上正规的第四方支付/聚合支付服务商绝对不允许碰资金。什么叫不碰资金就是商户的钱始终通过持牌支付机构或者银行渠道结算平台本身只做订单信息流和商户管理不形成资金池不做二清。为什么我要强调这一点因为选型的时候你怎么理解这层业务边界直接决定了系统的架构方式。在Jeepay这类合规模型里支付网关永远只是把交易请求转发给持牌渠道订单状态跟着渠道回调走商户结算也是由底层持牌机构来完成平台去做的只是对账。理解了这个边界后面看代码的时候你就知道哪些模块是核心哪些模块绝对不能碰钱。2. Jeepay系统是怎么组织代码的三大端与核心模块2.1 从仓库拿到源码后的第一眼印象不管你是下载zip包解压还是用git clone拉代码打开工程之后第一感觉就是这不是一个单体大泥球而是一个按业务域拆分的多模块项目。整个仓库大致可以分成五块运营平台manager、商户平台merchant、支付网关payment、定时任务job和公共核心模块core另外还有前端工程和数据库脚本。这里我比较建议大家不要看到多个应用就紧张。它们的代码都在同一个仓库里没有做成分布式微服务模块之间通过共享数据库和接口调用协作部署上完全可以用一台2核4G的小服务器跑起来。这种设计对绝大多数想做聚合支付业务的技术团队来说是一个非常务实的架构有清晰的业务边界又不会像微服务那样引入过多治理成本。Jeepay的后端技术栈是很典型的Java服务端组合Spring Boot做应用框架MyBatis-Plus做ORMMySQL做业务存储Redis做缓存和部分幂等控制。前端用的是Vue加Element UI运营平台和商户平台各有一套独立的前端工程。整体看下来这套技术栈对一个Java团队来说几乎没有学习成本招人也好招维护起来不愁。2.2 三个Web应用的职责边界运营平台、商户平台、支付网关这三个Web应用是理解整套系统的主线。我先用一句大白话总结它们的关系运营平台是招商和配置中心商户平台是给商户用的前台支付网关是真正处理交易流量的核心。运营平台给平台运营方用的。在这里创建商户、审核商户资料、给商户配置支付渠道参数。比如你的平台对接了微信支付的某个服务商通道那渠道参数就是在这个后台维护的。运营平台还要负责查看整盘交易数据、处理异常订单、配置系统参数。它是整套系统的管理中枢权限层级最高。商户平台的权限范围就收敛到具体商户。商户账号登录进去之后可以看到自己的支付应用列表创建支付应用获取AppId和AppSecret配置交易回调地址查看交易明细和账单。商户平台还有一个很重要的作用让商户可以自助完成大部分前后端联调前的准备工作不需要每次找平台方开工单。支付网关是每一笔交易真正经过的地方。商户通过服务端请求支付网关的下单接口支付网关解析签名、做参数校验、路由到对应的支付渠道然后同步返回收银参数或二维码信息。渠道的异步回调也由支付网关接收它先做回调验签再更新订单状态最后把支付结果通知给商户自己的系统。可以看出支付网关这套服务承载了最重的技术逻辑也是我们做二次开发时最需要重点研究的模块。2.3 数据库里最核心的几张表数据库设计是理解业务逻辑的关键入口。我把Jeepay的表结构大致梳理了一下重点看这几类核心表就能把业务串起来。商户信息表是业务的源头保存商户号对外业务标识、商户名称、状态、管理员账号等基础信息。商户应用表是紧跟在商户后面的概念一个商户可以创建多个应用每个应用对应一组AppId和AppSecret下单时靠appId区分是哪一套业务在发起交易。应用和回调地址绑定这样不同业务线的回调通知可以投递到不同的地址。支付订单表是整个库里的核心事实表每一笔交易都有一条订单记录关键是状态字段初始化、支付中、成功、失败、关闭这几种状态之间的流转严格跟支付链路的各个阶段对应。支付渠道定义表和渠道参数表则解决交易走哪个通道、参数怎么配的问题前者定义支付方式的代码比如微信Native、支付宝Wap后者加密保存真实渠道侧的商户号和密钥。从这几张核心表能看出一个很有意思的架构特征Jeepay通过商户-应用-渠道参数三层配置实现了多商户和多渠道的灵活组合。一个商户想接微信又接支付宝只需要创建应用并且在应用下挂不同的渠道参数支付方式的选择完全由商户调用方传过来的参数决定这种设计让系统的扩展性大大提升。3. 本地搭一套可运行环境把第一笔支付真实跑通3.1 准备清单与几个容易踩环境的坑跑通Jeepay的方式我建议直接按照先后端后前端先数据库后应用的顺序来。首先把依赖环境准备好JDK 8或11、Maven 3.6以上、MySQL 5.7或8.0、Redis 5.0以上。如果你还想把商户平台和运营平台的前端页面跑起来就需要Node.js环境前端工程基于Vue 2Node 14到16之间比较稳妥太新版本可能会在构建依赖时出兼容问题。这里有几个坑我在第一次部署时都踩过提前写出来能帮大家节省时间。第一个是MySQL的时区问题如果使用MySQL 8连接串里一定要加上serverTimezoneAsia/Shanghai否则驱动会报时区错误同时加上allowPublicKeyRetrievaltrue避免新版驱动默认禁止公钥检索导致连接失败。第二个是Redis如果你本机Redis设置了密码数据库配置里连着改了Redis密码和数据库编号两个配置项很容易漏。第三个是端口冲突三个后端应用默认占用了不同端口但如果你本机有别的服务占用需要进application.yml里改尤其要识别清楚哪个配置对应哪个子工程。3.2 初始化数据库与修改配置代码准备好之后先在MySQL里创建一个空数据库比如jeepay_demo字符集用utf8mb4。然后找到工程里带的SQL脚本把脚本导入到这个库里。脚本一次性把核心表、基础数据、演示商户和演示应用全部初始化好这个设计非常贴心意味着导入完成之后你已经有了一套带演示账号的可运行数据。接下来修改配置。需要改的东西集中在各应用下的application.yml也可能是application-prod.yml等等核心内容有两块数据源配置和Redis配置。把URL、用户名、密码改成你本机的真实环境然后把Redis连接信息同步调整。MySQL驱动的大部分配置已经在默认配置里写好了一般不用动。需要提醒的是源码里的配置文件并不是只有一处。我第一次跑就是只改了主配置文件忽略了另一个模块下的配置结果支付网关连不上数据库。建议全局搜索一下jdbc:mysql关键字把出现的地方挨个核对一遍再启动。3.3 编译、启动然后用演示商户完成首笔支付配置完成后回到工程根目录执行Maven打包。命令不复杂mvn clean install -DskipTests。整个编译过程会下载大量依赖国内网络环境建议先配置阿里云Maven镜像不然下载到一半卡住非常崩溃。打包成功后三个应用的jar包分别在各自模块的target目录下。启动顺序其实没有严格要求因为它们共享同一个数据库。不过从逻辑上讲我习惯先启动运营平台和商户平台最后启动支付网关。三个应用都起来之后浏览器分别访问对应的管理端口用初始化脚本里的演示管理员账号登录运营平台再用演示商户账号登录商户平台。在商户平台里找到我的应用里面已经有一个初始化好的演示应用可以看到AppIdAppSecret需要重置或者查看。接下来就是重头戏构造一笔真实的下单请求。你可以用POST工具或者直接写一小段Java代码调用支付网关的下单接口核心参数包括商户号、应用ID、支付方式代码、商户订单号、金额、回调地址。签名规则在官方文档里有标准说明核心思路是把业务参数按规范组织后用AppSecret做摘要生成签名网关收到请求后会用同一个密钥重新计算签名比对。请求成功之后接口会返回一个二维码内容或者跳转链接。在支付渠道侧我们当然没有真实的商户号所以实际支付这一步是走不通的但系统的订单状态流转可以完整演示下单后查询订单是支付中渠道回调没有进来的话定时任务会一直保持订单状态。如果你想看到完整的成功闭环可以用沙箱环境配合测试账号或者自己在回调逻辑里做模拟。这些都不影响我们理解系统全貌。4. 支付链路的本质从下单到回调的完整闭环4.1 一次下单请求网关在背后做了什么把流程跑通之后很有必要再深入看一下下单接口内部到底做了什么。我打了一个断点跟着调用链走了一遍发现整个过程可以抽象成四个步骤。第一步是参数合法性校验和签名校验。网关接口对外有统一的请求结构首先看商户号是否存在、应用是否属于该商户、支付方式是否有效、金额是否在允许范围、签名是否正确。这一步存在的意义是挡掉绝大部分伪造请求签名校验不过直接丢弃。第二步是生成平台侧订单。商户传过来的订单号是商户业务系统的单号不允许重复网关会生成一个平台内部订单号把商户号、应用ID、渠道代码、金额、状态等信息落库状态初始化为支付中。第三步是路由到具体渠道。这就是之前提到的聚合能力核心系统按照请求里的wayCode找到对应的支付渠道处理器然后调用该处理器去创建渠道侧订单。每个渠道处理器封装了对底层接口的调用逻辑比如微信的Native支付如何生成code_url支付宝的电脑网站支付如何生成Form表单这些差异被完全隔离在渠道处理器内部对上层是透明的。第四步是统一响应。不管底层是哪个渠道返回给商户的都是统一的JSON结构里面可能包含二维码链接、支付跳转地址或必要的支付参数。对商户系统来说它只需要解析这个统一结构然后引导用户去支付就行根本不需要关心底层渠道是谁。4.2 为什么异步通知要设计重试和幂等缺一不可用户完成支付之后渠道会给支付网关发异步通知。这里有一个非常关键的设计原则异步通知是不可靠的它可能延迟、可能丢失、也可能重复。微信和支付宝官方对异步通知都有一套重试机制如果接收方没有正确返回成功确认渠道会在接下来的一段时间内按不同间隔多次重发。所以网关接收渠道回调后第一件事永远是验签确认这条通知确实来自真实渠道防止伪造回调改订单状态。验签通过后系统更新本地订单状态再组装一个面向商户系统的回调通知往商户配置的回调地址投递。商户收到这个回调后必须返回一个特定字符串通常是success否则网关会按照自己的重试策略再次推送。这里容易犯的一个经典错误是把幂等实现做漏。正常的支付流程中微信可能回调两次我们的系统也可能因为网络抖动重发回调如果回调处理逻辑不幂等就会导致订单状态被反复更新、甚至触发重复发货。我在自己改造的时候对订单状态更新使用条件更新SQL只有订单当前处于支付中状态时才允许更新为成功从数据库层面就锁死了状态唯一流转这个思路推荐大家参考。4.3 掉单不可避免主动查单和对账才是兜底方案回调机制再完善也会有极端情况用户确实付款了但渠道的回调网络异常一直没发到我们服务器订单就一直卡在支付中。这就是掉单。掉单靠等待是永远等不回来的必须靠两个机制来兜底。第一个是主动查单。支付状态下系统定时任务会扫描那些超过一定时间仍然处于支付中的订单主动调用渠道的查单接口把渠道侧的支付结果同步回来。如果查到已经支付成功就主动把订单状态更新并触发后续的商户回调。这个做法在Jeepay里是由jeepay-job这个定时任务模块承担的。第二个是对账。即便主动查单也解决不了所有问题比如退款状态不一致、渠道侧有记录而平台侧没有所以每天定期拉取渠道的对账文件逐笔和平台订单做比对把不一致的数据找出来人工处理。这一层是支付系统的最后防线可能几天不触发一次但一旦真出了问题它就是挽回损失的唯一手段。5. 二次开发时最需要注意的几个地方5.1 挂接新支付渠道的扩展点我在本地把流程跑通之后做的第一件深度改造是给系统挂一个新的支付渠道。这里有个体验特别好的地方Jeepay对渠道接入的抽象做得很清晰扩展一个新的渠道不需要修改支付网关的主流程。大致路径是在支付渠道定义表里新增一条渠道记录配置好渠道代码和支付方式然后根据渠道处理器的抽象基类写一个子类实现统一下单、订单查询、关单、回调解析这几个方法最后把渠道参数加密存进渠道参数表。做完以上几步新的支付渠道就能在运营平台后台被配置到具体应用上下单时通过对应的wayCode就能路由过来。我在开发时还做了一件事在实现类里加了渠道侧与平台侧的订单号映射表。渠道返回的channelOrderNo要能在平台侧随时查到再配合定时任务做差异对账两个系统之间的状态完全对得起来。从这件事上我也体会到扩展一个渠道代码本身只占一小部分真正花时间的是渠道的文档理解、沙箱联调、异常场景梳理。5.2 金额精度、状态并发两个最隐蔽的Bug温床支付系统里有两个问题几乎每个入门者都会栽跟头一个是金额用浮点类型另一个是订单状态更新没有并发控制。金额问题听起来很基础但在实际项目中依然屡见不鲜。以分为单位用Long类型保存金额是支付系统的标准做法数据库里的金额字段也建议直接用BIGINT或DECIMAL(20,2)。千万不要在代码里用double做金额计算精度丢失一旦发生哪怕只是几分钱也对账和审计都解释不清楚。我自己在扩展还款类业务时就差点踩进去后续统一把所有金额都改成以分为单位的长整型传输从源头消除问题。状态并发问题更隐蔽。想象这样一个场景用户支付成功渠道回调正在更新订单状态此时另一个主动查单的定时任务也查到了成功结果两个线程同时更新同一条订单记录如果代码是先查询再更新就可能出现状态反复横跳。解决办法是放弃SELECT后UPDATE的写法直接执行条件更新UPDATE 订单表 SET 状态成功 WHERE 订单号? AND 状态支付中更新影响行数为0就说明已经被其他流程更新过了直接返回。这种乐观方式在支付系统里非常实用。5.3 上线前必须做的安全加固清单开源系统可以直接部署但安全加固这类事情代码不会替你做完上线前必须自己过一遍。我把自己在Jeepay二次开发后做的一轮安全审计清单分享一下。首先HTTPS是必备前提不管是支付网关对外接口还是商户平台、运营平台的访问入口全部走HTTPS密钥在明文HTTP下传输等于裸奔。第二回调地址要做白名单和校验商户配置的回调地址不能随意跳转到第三方域这里除了验签还可以限制只允许绑定过的域名端口。第三渠道参数存储必须加密数据库里如果被人拖走了明文密钥直接导致商户资金风险所以至少要使用AES加密存储密钥单独放在环境变量里。第四运营平台和商户平台的登录需要开启验证码和登录失败次数限制防止暴力破解。第五所有接口都做操作日志和审计支付系统出事之后能不能快速定位问题全靠日志全不全。除了这些技术手段还有一点容易忽略依赖安全。Jeepay依赖了一堆第三方库开源系统自己不会主动提醒你哪些组件有漏洞建议引入一个依赖漏洞检查工具定期扫一遍该升级的升级该修复的修复。6. 我在实操中的经验与建议翻来覆去说完了Jeepay的架构、部署、链路和二次开发最后分享几点个人体会。第一如果纯粹为了学习千万不要只停留在能启动这个层面。我强烈建议你按照我上文的方式自己模拟一条渠道回调把订单从支付中变成成功亲眼看看商户回调触发了什么、订单状态在哪里被更新、定时任务如果重复查单会怎么样。这一套流程走下来你对支付系统的核心难点在可靠性这句话的理解会深入很多。第二每次在群里看到有人问有没有成熟的Java聚合支付框架我都会推荐去看Jeepay的源码不是因为它的代码完美无瑕而是因为它把很多真实生产场景的细节都放出来了签名、验签、回调重试、幂等更新、渠道隔离、定时对账。这些知识点散落在八股文里但只有真正在代码里看过了面试或者设计系统时才会形成肌肉记忆。像支付回调为什么要幂等掉单如何处理状态机怎么设计这些经典问题都能在这个项目里找到参考答案。第三如果用这个项目为基础做商业项目一定注意几个前提要厘清自己所在区域的支付业务合规要求确认对接的是持牌机构还是银行通道系统本身只做信息流转绝不能碰资金归集要做好长期维护的心理准备开源系统不等于免维护自己定制化程度越高升级上游版本的成本就越大渠道参数、商户密钥这些敏感信息必须放在足够可靠的安全体系里管理。对我来说Jeepay不仅仅是一套能跑起来的支付系统更像是一座关于聚合支付系统到底应该怎么做的活教材。你可以在上面做二次开发、做渠道扩展、做架构改造甚至可以拿它作为设计自己支付中台的起点。如果你正好也在做类似的方向建议先把这篇文章收藏起来然后动手clone一份源码跑起来再回来对照着看你会发现很多文字描述的东西在代码里都变得异常清晰。本文还有配套的精品资源点击获取