简介这是一套全开源的Java聚合支付系统Jeepay面向中高级Java开发者、支付平台架构师及金融科技领域技术团队解决多渠道支付接入、自动路由、安全签名与高并发交易处理等核心问题。资源包共387个文件含322个Java业务与配置类、28个XML配置与Mapper定义、7个YML环境配置、7个TXT说明文档及2个SQL建表脚本覆盖后端服务、管理平台、SDK集成与部署全流程压缩包仅7.05MB轻量易上手。已有91人学习下载适合用于二次开发、支付中台搭建或分布式金融系统教学实践。读者可直接获取完整可运行源码、Spring Security权限控制实现、基于MQ的可靠订单通知机制、自动生成的渠道参数配置界面以及微信/支付宝/云闪付V2/V3/RSA2等多协议适配代码前后端分离架构便于快速对接前端或嵌入现有系统。1. 项目定位先搞清楚 jeepay 到底解决什么问题很多 Java 开发在简历上写“精通支付系统”但真被问到“支付网关怎么设计”“怎么对接多渠道”“回调怎么保证幂等”就懵了。原因很简单平时接触的多是公司内部已经封装好的支付组件底层怎么工作根本看不到。jeepay 这个全开源 Java 支付系统恰恰是把支付平台从零到一的全过程摊开给你看。它不是一个只能演示的 toy project而是一套可以直接部署的聚合支付系统。所谓聚合支付就是在商户和微信、支付宝、云闪付等实际支付渠道之间加了一层统一接入层。商户不需要关心每个渠道的下单接口怎么调、回调怎么验签、退款怎么发起只需要对接 jeepay 提供的统一接口就行。对于很多做电商、SaaS 平台、线下收银系统的团队来说这套东西省掉的不是一星半点的工作量。再解释下标题里“四方支付系统”这个概念。传统支付链条里支付机构直接服务商户比如商户直接去微信支付开放平台申请商户号这是三方模式商户、支付机构、用户。而四方模式多加了一个“服务商”角色——服务商帮助商户完成入驻、提供技术方案、管理交易支付机构只跟服务商结算。jeepay 在设计上就是一套“平台方 商户方 渠道方”的多角色系统商户端、服务商/代理端、平台运营端都有独立界面天然适配这种多层级的业务结构。所以你在做二次开发时不用担心角色模型不够用它已经替你考虑好了。我自己是把它当作“支付系统设计的最佳参考教材”来用的。如果你想快速搭一套聚合支付平台它是可落地的方案如果你想深入理解支付系统中订单状态机、渠道适配、回调通知、对账任务这些设计它更是难得的学习素材。两种目的都合适这也是我把它推荐给身边同事朋友的原因。2. 系统架构拆解jeepay 内部是怎么组织的2.1 四个子系统的职责边界我第一次打开 jeepay 的代码仓库时第一反应是“项目还挺多”。它不是一个单体应用而是拆成了几个独立工程每个工程职责很清晰。jeepay-core公共核心模块包含通用的实体类、工具类、异常定义、基础配置。其他所有工程都依赖它相当于地基。jeepay-payment支付核心服务负责接收商户的下单请求、调用各渠道 API、处理回调、生成支付结果通知。这个模块是整个系统的引擎也是渠道对接的大本营。jeepay-merchant商户后台服务给商户提供查看账单、配置支付参数、发起退款、查看对账单等能力。jeepay-manager平台运营后台服务给平台管理者用的管理商户入驻、审核渠道配置、查看系统运营数据、调整费率计费等。从这个拆分能看出一个核心设计思想接口层、商户端、运营端是隔离的各自独立部署互相不拖累。如果你有线上流量支付核心服务 jeepay-payment 可以单独横向扩容而运营后台压力小不需要跟着一起加机器。这也符合支付系统高可用优先的惯例。前端部分是 Vue 项目跟后端服务一一对应。你能看到 merchant 前端工程、manager 前端工程支付核心本身不需要前端页面它是纯接口服务。整体技术栈是基础的 Spring Boot MyBatis-Plus Redis MySQL Vue没有引入特别冷门的东西二次开发门槛不高这也是我敢把它拿来当生产系统参考的重要原因。2.2 核心数据模型与订单状态机支付系统里最不能搞错的就是数据模型尤其订单表的状态流转。jeepay 在这块做得相当规范核心表包括商户信息表、应用信息表、支付订单表、退款订单表、渠道参数配置表、商户参数配置表、转账订单表、分账关系表等。以支付订单表为例它的状态设计是init初始状态订单刚创建还没发起支付paying已发起支付等待用户付款success支付成功failed支付失败closed订单超时关闭或主动撤销我在实际二次开发时感受最深的是订单状态变更基本都集中在支付回调处理逻辑中而且变更前会做幂等校验。这个细节特别重要因为渠道回调可能重复推送同一笔订单如果处理两次会导致严重的资损问题。jeepay 的处理方式是回调来了先查订单状态如果已经是 success 就直接返回成功响应不重复处理。这套逻辑我在自己负责的项目里直接照搬了。退款单的状态设计类似有 init、success、fail 等状态。而且退款单和原支付单是分表存储的关联查询通过支付订单号建立映射。这种设计在处理部分退款场景下特别顺手每笔退款独立记录对账时直接按退款单维度核对就行。另外 jeepay 的数据库脚本里可以清楚看到它把商户号、应用号、渠道配置等分成独立表这意味着你可以为同一个商户的应用灵活配置不同渠道。比如商户 A 的 App 应用用微信和支付宝而 PC 网站应用只需要支付宝这种按应用维度管理渠道的做法很灵活也是多商户支付平台常见的建模思路。2.3 一次支付请求的完整生命周期说了这么多架构层面的东西可能还是有点抽象我带着你走一遍一次支付请求的完整流程你会更直观地理解 jeepay 在做什么。第一步商户系统调用 jeepay-payment 的下单接口传入商户号、应用ID、订单号、金额、支付方式等信息。jeepay 会先生成一条支付订单状态为 init同时把订单号、商户号这些信息写入 Redis 做缓存。第二步支付网关根据支付方式和商户的渠道配置找到可用的渠道实现。比如商户选择了微信扫码系统就会匹配微信官方渠道调用渠道真实的下单接口拿到支付链接或二维码内容。第三步把渠道返回的支付参数比如 code_url 这种二维码内容返回给商户系统商户系统展示二维码给用户。第四步用户扫码付款后微信服务器回调 jeepay 配置的 notify 地址。jeepay 收到回调后先做验签然后查订单、校验金额把订单状态从 init 更新为 success再向商户系统发送异步通知。第五步商户系统收到通知后需要返回确认响应jeepay 收到后停止重试。这个流程其实和所有支付网关一样单从实现上讲并不神秘。但 jeepay 把每个环节都落到了具体代码上包括验签、幂等、状态回写、通知重试机制、掉单补偿定时任务。你想学支付系统照着这个流程把代码读一遍比看十篇理论文章都管用。3. 技术选型与本地部署一步步把它跑起来3.1 技术栈和版本选择背后的理由jeepay 使用的是 Spring Boot 技术栈后端接口用的 Java前端用的 Vue。具体来说后端Spring Boot、Spring Security、MyBatis-Plus、MySQL、Redis前端Vue、ElementUI、Axios定时任务 XXL-Job封装在项目里用于处理掉单补偿、对账等构建工具Maven这套选型在业界属于“稳如老狗”级别尤其是 MyBatis-Plus国内很多业务系统都在用上手成本低。Redis 用于缓存订单信息、防重复提交、存储临时令牌等。XXL-Job 则承担了支付系统必需的定时补偿任务比如查询超时未支付订单、向商户补发通知等。用 Redis 缓存支付订单时jeepay 会设置过期时间目的就是配合定时任务做掉单处理。因为渠道回调可能出现延迟或者商户根本没有回调这时需要通过主动查询渠道订单状态来判断订单最终结果。这个设计对实际生产系统来说必不可少支付系统不能只依赖回调一条路径。3.2 下载代码和准备环境我建议你在开始前先准备好这些基础环境JDK 8 或 11不同版本分支可能要求不同用主分支默认支持的就行Maven 3.6MySQL 5.7Redis 5.0Node.js 10用于启动前端项目代码可以从 Gitee 或 GitHub 上搜索 jeepay 仓库拉取关键字用“jeepay”就能找到。拉下来之后你会看到仓库里除了后端 java 工程还有 docs 文档目录和前端工程目录。先别着急启动先看文档目录下的 SQL 脚本和部署说明这一步能帮你省掉很多不必要的坑。3.3 数据库初始化最容易出错的一步数据库这步很多新手会直接执行 SQL 脚本但忽略字符集导致中文乱码或者建库时没有设置 utf8mb4 导致一些特殊字符存不进去。我的建议是手动创建一个数据库命令大致如下CREATE DATABASE jeepay DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;然后执行项目里提供的 SQL 脚本。jeepay 的脚本一般会创建一个完整的初始库里面包含了所有表结构和基础数据包括管理员账号、运营角色、菜单权限等。这一步执行完数据库层面就准备好了。我踩过的一个坑是脚本里初始化的管理员密码是加密后的密文直接用明文去登录后台肯定失败。文档里有说明初始账号密码但实际部署时建议你登录后立即修改避免系统裸奔。这类开源项目默认密码基本是公开的秘密生产环境再不换就太心大了。3.4 项目启动顺序与配置修改jeepay 项目建议按照这个顺序启动确保 MySQL 和 Redis 已启动先启动 jeepay-manager运营后台服务因为支付服务和商户服务启动时可能会读取数据库中的配置再启动 jeepay-payment支付核心服务最后启动 jeepay-merchant商户后台服务每个工程的 application.yml 都需要改三个地方MySQL 连接地址、数据库账号密码、Redis 连接地址。注意要把配置改成你自己的环境别用默认的 localhost:3306 跑生产这种错误虽然低级但真有人犯过。后端工程启动成功后再启动前端工程。前端用了 npm执行 npm install 安装依赖然后 npm run serve 启动访问对应端口就能看到运营后台和商户后台的登录页了。我用本地环境跑通全过程大概用了一个下午其中一半时间花在等 npm install 和 Maven 下载依赖上真正遇到的实际问题并不多。4. 二次开发实战如何接入一个新的支付渠道4.1 渠道抽象层从抽象理解接入jeepay 之所以方便扩展是因为把渠道接入抽象成了一组接口。不管你接的是微信、支付宝、云闪付还是某个银行支付通道在 jeepay 里做的事情都是一样的实现统一的渠道服务接口处理下单、查单、退款、回调验签等方法。具体来说jeepay-payment 模块里各支付渠道的实现类按照支付方式组织比如微信相关的类处理微信支付的 JSAPI、扫码、小程序等场景支付宝相关的类处理支付宝的网页支付、手机网站支付等。每个渠道实现类需要实现同一个接口接口里定义了统一的调用方法。这种设计有一个明显的好处核心流程代码不用为每个渠道单独写一遍渠道差异被隔离在了具体实现类中。你在新增渠道时最需要注意的是渠道参数的定义。每个渠道有不同的配置项比如 AppID、商户号、API 密钥、证书路径、回调地址等。这些参数不能在代码里写死要通过渠道参数的配置接口维护到数据库运行时动态读取。这样做的好处是上线后如果需要调整渠道配置不用重新部署代码在运营后台改配置就行。4.2 实操视角从零对接一个支付通道假如现在要对接一个全新的支付通道比如某银行的聚合支付接口。我会按这几个步骤来第一步在渠道枚举中增加新的渠道类型。jeepay 中渠道类型一般是一个枚举类每个渠道一个标识符加了枚举之后系统才能识别这个新渠道。第二步定义渠道参数实体和对应的参数配置界面。在运营后台维护该渠道需要的配置项比如网关地址、商户号、密钥等。第三步实现支付渠道接口。核心方法包括统一下单方法负责调用新通道的接口生成支付信息查单方法负责主动向新通道查询订单支付状态退款方法负责发起退款回调处理器负责接收并验证新通道的支付结果通知。方法内部就是调用新通道的 HTTP 接口、进行参数签名、解析返回结果。第四步联调验证。用测试商户号跑真实下单流程模拟支付成功和支付失败两种场景确认回调能正确更新订单状态。这套流程其实和接微信/支付宝的官方通道是完全一致的。我在开发中发现的技巧是先把日志打详细尤其是 HTTP 请求和响应报文联调阶段能省掉大量来回沟通的时间。渠道返回的错误码五花八门没有详细日志你根本猜不到哪里参数不对或者哪次签名算错了。另外回调地址必须配置成外网能访问的公网地址。本地联调时可以用内网穿透工具把本地服务映射到公网这样才能收到支付通道的回调请求。我第一次联调时就是忽略了这个一直收不到回调还怀疑代码写错了排查了半天才发现是回调地址不通。4.3 二次开发代码落地要点在真正动手改代码前有三个地方我建议你先花时间读一遍第一统一下单入口的 Controller。你会看到它最终调用的是一套统一的业务方法而不是每个渠道各写一遍理解这个入口就能理解整个系统横向扩展的思路。第二回调处理逻辑。重点看它是怎么从 HTTP 请求中解析参数、验签、查找订单、更新状态的这段代码是整个支付系统的核心也是最容易出事故的地方。第三接口签名校验逻辑。jeepay 对商户请求有签名校验保证请求参数在传输过程中没有被篡改。你扩展新接口时这套签名机制可以复用不用自己再拍脑袋设计一套。有一点要特别注意千万不要把渠道 API 密钥、证书路径这些敏感配置硬编码在代码里。jeepay 的做法是把它存储在数据库配置表里通过注解和类型转换直接注入到渠道实现类中使用起来非常方便。这是很多新手容易犯的错误总觉得“写死在代码里省事”但后期维护和权限控制都会成为灾难。5. 常见问题排查与避坑记录5.1 掉单问题回调没收到怎么办我遇到过的最典型的问题就是支付成功了但商户系统没收到通知订单一直处于“支付中”。出现这种情况第一反应不应该是怀疑代码而是先确认支付通道是否真的把回调推送过来了。我之前联调的时候就遇到过原因是回调地址配置成了 HTTP而支付通道要求 HTTPS或者地址根本不通。排除这个之后再看 jeepay 自身的补偿机制。jeepay 里有一个定时任务会定时查询那些超时未支付但渠道侧查询已经成功的订单然后把它们的状态刷新为成功并重新补发通知。这条链路确保了即使回调丢失订单最终也能被修正。实际应用中还遇到过一个情况商户系统的通知地址响应太慢导致 jeepay 一直重试订单状态重复通知多次。解决方法是商户系统对通知做幂等处理收到重复通知直接返回成功。我经常提醒同事支付通知的幂等处理不是“尽量做”而是“必须做”这是支付系统的基本素养。5.2 数据库和缓存常见问题jeepay 在启动时报数据库连接失败这是新手最常遇到的。原因基本是三类数据库没启动、账号密码错误、配置文件的 IP 端口不对。还有一个不那么明显的原因MySQL 版本问题导致驱动不兼容。建议直接用项目文档要求的版本不要用太老旧或太新的版本否则可能会遇到奇怪的兼容性问题。Redis 连接不上是第二个高频问题。我的排查套路是先用命令行手动连一下 Redis确认网络通不通、密码对不对然后再看配置。有时候本地启动了 Redis但 Redis 配置了密码而代码里没写或者反过来都会导致连接失败。排查时要先确认 Redis 本身的可用性再查代码配置别一上来就怀疑代码写错了。5.3 商户后台和运营后台的权限问题运营后台和商户后台用的是不同的权限体系登录后看不到某些菜单是正常的不要怀疑是不是 bug。因为 jeepay 自带了基于角色的访问控制管理员分配了哪些菜单权限账号就能看到哪些菜单。新创建的商户账号默认可能只有部分功能权限需要在运营后台给商户配置权限和费率。这是我见过的新用户问得最多的“问题”其实不是 bug是权限没配全。我用 jeepay 做二次开发时最喜欢它的一个点就是这套权限模型很清晰。商户、服务商、运营方三者的权限边界是分开的不会出现商户跑到运营后台改配置的越权情况。如果你做的是多租户系统这套权限设计非常值得参考。5.4 资金安全相关的几个提醒支付系统最忌讳的就是资金差账差一分钱都可能是严重的生产事故。jeepay 在每次渠道回调时都会比对应付金额和实付金额不一致时拒绝更新为付款成功这个细节很多人会忽略。另外我强烈建议你在改动订单状态前先用分布式锁做并发保护。jeepay 在回调处理逻辑中已经做了这层防护但如果你自己新增了处理逻辑不要破坏这个保护。我在一个项目里看到有人改代码时在回调里直接根据订单号 update 状态没有做任何锁控制高并发下同一笔订单可能被两个请求同时处理后果相当危险。支付系统不是 CRUD每一行代码都应该有对极端情况的考虑。还有一个容易被忽略的点退款和订单撤销是两回事不是在支付订单上加个状态就行。jeepay 把退款单、撤销订单作为独立流程处理退款成功后原订单变成已退款状态但订单的主状态仍然是 payment success只是多了一个关联的退款单。如果你在设计系统时把退款做成直接改订单状态后续统计和计费全部乱套。这一点我在读 jeepay 源码时体会特别深它对资金类操作和业务操作做了区分资金操作必须留痕业务操作可以灵活。6. 读源码的方法论从 jeepay 能学到什么6.1 阅读路径建议别从 Controller 开始闷头读很多初学者拿到源码后习惯从 Controller 开始一个类一个类地往下看。但支付系统的业务逻辑非常依赖状态流转和异步消息仅仅看 Controller 你很难理解全貌。我建议先读表结构理解订单、退款单、渠道参数这些核心表之间的关系再去看一次完整支付链路的代码实现。具体来说你可以先看统一的支付下单方法找到它创建订单、调用渠道、处理结果的部分。然后跟着渠道实现类走到真实的 HTTP 调用看请求参数怎么组装、签名怎么算、响应怎么解析。这样从入口到出口走完一条链路比漫无目的地逐类阅读效率高得多。之后再回调通知的处理逻辑。把“下单链路”和“回调链路”这两条主线吃透jeepay 的大部分心脏代码你已经掌握了。剩下的退款流程、对账流程、分账流程都是类似套路会一通百通。6.2 值得精读的几个核心设计jeepay 里有几个设计我认为是比业务本身更有价值的一个是统一返回结构。jeepay 的接口返回永远是一个统一的 JSON 结构包含 code、msg、data 三个字段。这种设计看似简单但在服务端开发中如果每个接口返回结构不统一前端对接和网关层处理都非常痛苦。另一个是参数校验。支付接口的入参非常关键因为金额、订单号这些参数一旦出错会直接影响资金准确性。jeepay 对参数校验比较严格并且会用统一异常处理把校验失败信息返回给调用方。这种“入口收拢”的思想你在自己写业务接口时完全可以借鉴。还有一个是日志规范。jeepay 在关键节点上会打印日志包含订单号、渠道、金额等关键信息。排查线上问题时这些日志就是救命稻草。我见过很多系统的日志只看得到“调用成功”“操作失败”这种废话出了问题根本没法排查。看 jeepay 的源码你会发现它在什么位置打日志、打印哪些信息都是有讲究的。6.3 我可以把 jeepay 直接拿去做生产吗这是很多人关心的问题。我的看法是可以但前提是你具备足够的能力去承担后续的维护和定制成本。jeepay 作为一个开源项目核心功能已经相当完善基础的扫码、JSAPI、APP 支付、转账、分账、退款、对账都有覆盖。如果你的业务场景不复杂团队也没时间从零研发一套支付网关用它做基础平台再配合少量二次开发是可行的。但需要注意三点第一一定要先充分测试。支付系统的容错性要求极高你必须在沙箱环境下跑通所有场景甚至在测试环境人为模拟渠道超时、响应内容畸形这些极端情况确认系统不会崩溃或者资金出差错。第二合规资质要考虑周全。聚合支付涉及资金流转运营方是否需要支付业务许可证取决于业务落地的具体模式和所在地区的规定。这是业务层面的事不是技术代码能解决的我在部署前会先和管理层、法务对齐不会贸然上线。第三安全加固不能省。默认的管理员密码要改接口要加风控敏感配置要进行加密管理数据库不能裸奔在公网。开源项目默认配置是为了让你快速跑通不是为了让你直接上生产这两者之间还有一段路要走。6.4 学习价值远远大于部署本身就算你没有生产需求纯粹为了学习jeepay 也是很好的教材。因为它不像那些“为了演示而演示”的项目它是真实业务系统的浓缩版里面充满了对极端情况的考虑。多商户、多渠道、多支付方式、分账、对账、掉单补偿……这些设计在架构类书籍里是理论在 jeepay 里是看得见摸得着的代码。我建议你拿到项目后先部署跑起来再用测试账号走一遍支付流程然后开始改代码。从改一个支付渠道的配置开始到新增一个渠道实现再到调整回调通知逻辑一步步加深理解。支付系统是少有的“业务复杂度和技术复杂度都很高”的领域啃下一个 jeepay你的系统设计能力和对事务、状态机、幂等、并发控制的理解会有明显提升。最后再分享一个我自己的实操习惯每次拿到一个新的开源项目我都会先建立一套自己的“源码笔记”把核心流程画成模块关系图把关键类和方法的作用记下来。这次看 jeepay 也是这样从订单表到支付流程再到渠道扩展点笔记帮助我快速定位代码。如果你也想深入搞懂这个项目建议你也试试这个方法效果会比单纯看代码好得多。本文还有配套的精品资源点击获取