拓冰网站定制 
简介一套基于Java的开源聚合支付系统Jeepay面向需要整合微信、支付宝、云闪付等多渠道支付能力的开发者与企业。系统内置支付网关自动路由已对接微信服务商及普通商户V2/V3、支付宝服务商及普通商户RSA/RSA2、云闪付服务商并采用签名机制保障交易安全适合作为电商、SaaS平台或金融机构的支付中台。资源包共387个文件以322个Java源码为主辅以XML配置、SQL初始化脚本、YML环境配置及Shell部署脚本压缩包仅7.05MB结构紧凑便于本地搭建。管理端包含运营平台与商户系统界面简洁前后端分离权限基于Spring Security订单通知通过MQ实现高可用渠道参数配置可自动化生成。已有95人学习下载附带的开发文档和搭建说明能大幅降低二次开发门槛适合有Java基础并希望深入支付领域的开发者。1. Jeepay是什么为什么一个开源的Java支付系统值得你亲自部署一遍一个支付系统真正吃功夫的从来不是“收钱”那一下而是收完钱之后的账怎么算、渠道怎么切、订单怎么对。Jeepay就是这样一套用Java写成的开源聚合支付系统它把多商户进件、多渠道聚合、统一收银台、结算分账和对账报表全部做成了可以部署的工程代码省掉了从零攒轮子的过程。这篇按一条真实的落地路径把Jeepay从部署到二次开发的关键步骤和参数讲清楚适合学过Spring Boot的Java工程师、给多商户做增值服务的小团队以及想自建支付中台的技术负责人。2. 拆解Jeepay的技术骨架聚合支付与四方支付的核心设计思路2.1 聚合支付与四方支付先搞清楚Jeepay到底做了什么Jeepay的定位经常被人一句话说成“一个支付后台”但这个说法太容易让人低估它的设计范围。先理清几个概念所谓聚合支付指的是把微信、支付宝、云闪付这些不同渠道的收款能力封装成一套统一接口商户不需要分别对接每一个渠道的文档只要调一个接口就能发起一笔收款。而四方支付是在三方支付和银行渠道之上做聚合、路由、分账、对账的技术服务方本身不直接触碰资金也不持有支付牌照但承担了商户接入、渠道管理、订单匹配这些脏活累活。Jeepay做的正是四方支付模式的项目落地。它把“聚合支付”的通用能力拆成了运营、商户、支付核心三条链路运营侧管商户进件和费率商户侧管应用和订单查询支付核心管渠道调用和回调转译。这个分层不是拍脑袋设计的它直接对应了四方支付平台在业务上的三个角色——平台运营方、入驻商户、底层渠道。理解了这个模型后边看数据库表结构和接口设计都会顺很多。有一点容易被忽略四方支付系统里资金流和信息流是分离的。用户付钱钱直接进的是渠道侧的三方支付账户Jeepay能做的只是记录订单状态、计算分账金额、定时对账。这意味着所有金额字段都不能用浮点型所有状态变更都要留操作日志渠道回调与本地订单的金额不一致时必须按差异单处理。这些约束在后边的开发中会反复出现先把模型立住再动手写代码才不会越改越乱。2.2 六大核心模块从商户进件到资金结算的完整闭环把Jeepay代码仓库打开会发现它的后端工程是按业务域拆分的大体可以分成六个核心模块它们合起来才构成从商户进件到资金结算的完整闭环。模块核心职责关键数据商户系统商户信息、应用信息、进件审核mch_info、mch_app渠道系统渠道参数配置、渠道类型管理pay_channel、pay_channel_route支付核心下单、渠道调用、回调接收、订单状态机pay_order、pay_pending_task结算系统分账配置、结算单生成、提现管理settle_record、profit_allocation对账系统渠道账单拉取、本地流水比对、差异处理reconciliation_diff运营后台费率配置、公告、运维数据统计各类统计汇总表商户系统是入口。一个商户进来之后平台要给他创建商户号然后再创建应用每个应用对应一套独立的API密钥和回调配置。真实业务里一个商户可能有好几个应用App、小程序、H5各一个每个应用可以单独配置允许使用哪些渠道也可以设定不同的费率。这一步管不好后边对账和结算全都会乱。渠道系统是Jeepay最值得借鉴的一层设计。它把“微信下单”和“支付宝下单”这类动作抽象成了统一的渠道接口每个渠道自己实现下单、查单、回调解析、验签这几个方法。新增一个渠道时核心代码改动被限制在渠道实现类里不需要碰业务层。这其实就是策略模式在支付系统里的标准应用但很多自研支付系统做到后面会把渠道判断散落在Service层里改一个渠道要牵连好几个文件Jeepay这种收敛方式值得直接抄。支付核心是整个系统的发动机。它接收商户的下单请求根据路由规则选中一个可用渠道生成渠道侧的交易参数再返回给商户端一个收银台地址。用户支付完成之后渠道系统异步回调到Jeepay支付核心解析回调内容、验签、更新本地订单状态再通过商户通知接口把结果推给商户。这条链路上最怕的不是渠道挂掉而是回调丢或重复所以Jeepay在状态更新时做了防重和幂等后边章节细聊。结算和对账是四方支付里真正体现价值的部分。渠道侧的钱经过一段时间才能结算到平台账户平台再按分账规则把钱结算给商户。这个过程需要把渠道账单、本地订单、结算记录三份数据拉到一起比出现差异后生成差异单人工介入处理。很多小团队做支付系统收单功能上线很快但结算跑批和对账脚本能拖上一个月就是低估了这三方数据对齐的工作量。2.3 支付流程设计下单、渠道路由与回调通知的关键设计一次标准支付在Jeepay里的时序可以压缩成五个步骤商户后端调用下单接口传入商户号、应用ID、订单号、金额、回调地址。支付核心校验参数和签名生成支付订单按路由规则选中渠道。返回渠道收银台地址或支付参数商户端把用户引导到对应页面。用户在渠道侧完成支付渠道回调Jeepay的支付结果的地址。支付核心验签后更新订单状态调用商户回调接口通知商户。这五步看起来简单真正写起来每一步都有边界情况。比如第二步的路由规则不能只看渠道开通没开通还要看当前渠道是否在维护窗口、单笔限额是否满足、商户是否被限制使用该渠道。有些实现会把路由做成可配置的权重轮询比如微信和支付宝各占50%流量某个渠道连续失败就自动摘除。Jeepay里这种路由配置和渠道参数是分开存储的做二次开发时可以直接在路由表上做文章。第五步的回调通知是埋坑最多的地方。渠道侧回调同一个订单可能重复触发商户回调接口可能超时或返回异常这两件事叠加起来就会导致订单状态不一致。常见的处理方式是引入补单任务定时扫描处于“支付中”状态且超过一定时间的订单主动向渠道侧发起查单根据查单结果修正本地订单状态再触发商户通知。补单任务本身要支持手动触发因为有些渠道查单接口也有延迟人工触发是为了在联调阶段快速验证不用干等定时器跑完。在写补单逻辑时最直接的做法是给订单状态加一个版本号字段更新时用带条件的UPDATE语句比如“SET status 新状态 WHERE order_id ? AND status 旧状态”这样并发回调时只有一个请求能成功更新状态不会出现订单状态被后到的回调覆盖成旧值的情况。Jeepay这类支付系统的状态机本质是用数据库的行锁来解决回调乱序不要试图在Java代码里用同步锁来处理跨进程的问题。3. 本地部署从拉取代码到跑通一笔测试支付的完整步骤3.1 环境准备JDK、MySQL、Redis的版本选择Jeepay后端是标准的Spring Boot工程Java版本用8就够了不需要上17之类的新版本反而新版本JDK在运行时可能出现反射相关的兼容问题。构建工具用Maven 3.6以上IDE用IDEA可以直接打开根目录的pom.xml等待依赖下载完即可。先给出我实际验证过的一套组合避免在环境上反复折腾。组件版本选择说明JDK1.88u201Spring Boot 2.x对JDK8支持最稳定Maven3.6构建和打包后端工程MySQL5.7或8.08.0需注意排序规则兼容Redis3.2缓存、分布式锁、延迟队列都会用到前端可选Node.js 14只有跑运营后台和商户后台才需要MySQL的版本是最容易翻车的地方。Jeepay的初始化脚本里如果包含utf8mb4_0900_ai_ci这样的排序规则放到MySQL 5.7上执行会直接报错。要么把脚本里的字符集和排序规则统一改成utf8mb4和utf8mb4_unicode_ci要么直接用MySQL 8.0初始化然后连接配置里加上characterEncodingutf8mb4。数据库的时区也要注意连接串里建议加上serverTimezoneAsia/Shanghai避免Java服务本地时区和数据库时区不一致导致时间字段偏移。Redis的作用容易被新手低估。支付订单的短暂状态、渠道访问令牌、分布式锁、延迟队列都依赖Redis如果只把它当成缓存来用启动时不配密码可能没事但生产环境Redis宕机会直接影响支付链路。因为Jeepay回调和补单逻辑里大量依赖Redis的原子操作来防重Redis不可用时订单状态就没办法可靠更新。本地部署时Redis不用开持久化但生产环境至少开AOF并且设置appendfsync everysec。3.2 初始化数据库与启动服务三个Java进程怎么配合Jeepay的源码拉下来之后先不要急着用IDEA点启动按钮按顺序来。先把数据库初始化和配置改好再逐一把服务跑起来。以下是我常用的命令序列在项目根目录下执行。# 拉取代码 git clone https://gitee.com/jeequan/jeepay.git cd jeepay # 初始化数据库执行根目录下的init脚本 mysql -uroot -p jeepay-db/init.sql # 进入支付核心工程修改数据库和Redis配置 vim jeepay-payment-boot/src/main/resources/application.yml # 重点修改这几项 # spring.datasource.url、username、password # spring.redis.host、port、password # 打包并启动支付核心 mvn -pl jeepay-payment-boot clean package -DskipTests java -jar jeepay-payment-boot/target/jeepay-payment-boot.jar 先启动支付核心的理由很直接商户平台和运营平台在登录之后会有大量查询支付订单的操作如果支付核心没起来后端的Feign调用会报连接失败控制台刷错误日志。三个工程的依赖关系是支付核心在最底运营和商户平台在中间前端页面在最上。很多人第一次跑项目时习惯一次性把所有服务全启动结果日志混在一起看不出问题建议逐个启动等前一个的端口能访问了再起下一个。支付核心的application.yml里还有一个容易被忽略的参数is_dev开发环境下设为true会打印更多调试日志也会跳过一些签名校验方便本地联调。但要注意这个参数在生产环境一定要关掉否则回调接口会存在严重安全隐患。另外渠道的证书文件路径要确认存在有些渠道在初始化时会加载证书路径配错了启动都不会报错但真正发起支付时会直接抛异常。3.3 配置支付渠道接入一个测试支付参数的参数说明初始化脚本执行完之后运营平台和商户平台里是没有任何可用渠道的。要在测试环境跑通一笔支付需要先在运营平台里配置一个支付渠道。打开运营平台的“支付渠道”菜单选择渠道类型会看到一串待填写的参数。我把关键的几项列出来并说明它的实际作用。参数示例说明渠道类型WX_PAY / ALI_PAY微信或支付宝商户号微信侧分配的mch_id渠道侧识别平台身份的编号应用IDwx123456789不同端使用的appIdAPI密钥32位随机字符串生成签名和验签使用API证书apiclient_cert.p12微信退款和查单需要回调地址https://api.example.com/api/payment/callback接收渠道通知的地址回调地址是本地联调里第一个坎。如果用内网穿透工具把本地服务暴露出去回调地址必须填穿透工具生成的公网HTTPS地址如果是在服务器上部署填真实域名并配好HTTPS证书。很多渠道要求回调地址必须是HTTPS且非局域网IP直接用IP地址会被拒绝。首次联调时最容易遇到“支付成功但本地收不到回调”十有八九是回调地址填错。4. 二次开发与定制接口签名、分账与商户系统的对接要点4.1 接口规范统一签名算法与应用令牌的传递方式Jeepay给商户提供了统一的下单、退款、查单接口这些接口共享一套签名规则。签名的作用不是为了加密而是让服务端能够确认请求来自合法的调用方同时防止请求参数被中途篡改。接口约定一般是这样商户应用创建时生成一个API密钥调用接口时把所有参数按字典序拼接加上密钥后做MD5得到的字符串作为sign字段传过来。// 签名工具示例基于TreeMap自动按key排序 public static String generateSign(MapString, String params, String apiKey) { TreeMapString, String sorted new TreeMap(params); StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sorted.entrySet()) { String key entry.getKey(); String value entry.getValue(); // 签名参数本身不参与计算空值也要剔除 if (sign.equals(key) || value null || value.isEmpty()) { continue; } sb.append(key).append().append(value).append(); } // 拼接密钥后做MD5 sb.append(key).append(apiKey); return DigestUtils.md5Hex(sb.toString()); }这段实现里有三个细节值得注意。TreeMap保证了参数按字典序排序省去了手动排序的代码过滤空值的逻辑必须写否则渠道侧多传一个空参数就会导致签名结果不同最后拼接的密钥不带value空串因为apiKey是平台固定的不需要参与排序。登录和鉴权环节除了签名还依赖应用令牌。商户调用接口时在请求头里带上tokentoken由商户应用ID和密钥动态生成。Jeepay的服务端会维护一份token到应用信息的映射缓存到Redis里过期后要求重新获取。做二次开发时如果要新增一个商户自定义接口记得先鉴权再处理业务逻辑不要因为内部系统就跳过签名校验。4.2 扩展一个新支付渠道从渠道配置到回调适配的改动范围接入一个新的支付渠道比如某些地区的本地支付App是Jeepay二次开发里最典型的任务。改动点可以收敛到三个地方渠道配置表加一条渠道类型、实现一个渠道服务类、在路由规则里允许该渠道参与选择。核心的渠道服务类通常长这样public interface IChannelService { // 返回渠道类型标识例如 LOCAL_PAY String getChannelId(); // 构建渠道侧下单参数并返回支付链接 PayOrderModel createOrder(PayOrderReq req); // 解析渠道回调请求拿到原始参数 String parseCallback(HttpServletRequest request); // 校验渠道回调的签名 boolean verifyCallback(MapString, String params); }实现这个接口时createOrder是最复杂的一步。它需要把Jeepay的支付订单转换成渠道侧要求的参数格式包括金额、商户号、回调地址、过期时间等。这里最容易踩的坑是金额单位不一致Jeepay内部通常是分但有些渠道接口要求元或者反过来。转换错误会导致用户看到的价格和实际扣款不一致这种问题在联调阶段就很难发现需要在下单和回调两端都把金额打印出来对照。新增渠道类型后渠道侧的配置文件、数据字典、页面下拉选项这些都要跟着补。核心逻辑编译通过不代表功能完整还要回到商户平台里确认这个新渠道能在创建支付订单时被路由到。一个稳妥的做法是先走通一个新渠道的最小支付链路再去补查单、退款、对账这些周边功能不要一开始就追求能力一步到位。4.3 接入商户系统的三个关键点分账、对账与回调幂等商户系统接入Jeepay时最容易出问题的不是下单而是资金相关的三个点。分账配置的粒度要到“商户应用渠道”的层级不同渠道的手续费率不同分账比例自然也不同。Jeepay里分账配置通常是在运营平台上维护商户侧只能查询做定制时要注意权限边界不要让商户自己把分账比例改成100%。对账则是每天固定时间拉取渠道账单和本地订单流水比对。差异单产生的原因一般是这三类本地订单存在但渠道账单没有渠道账单存在但本地订单状态不是成功两边金额不一致。处理差异单的正确姿势不是直接改数据库而是先跟踪渠道侧订单状态再决定本地订单是做补单还是做退款。项目中我一般会保留所有对账差异记录至少半年方便后续排查历史问题。回调幂等前面提过一次这里再强调一遍它在对接时的具体做法。商户侧接收Jeepay回调时不能先查订单再更新要直接用订单号加状态条件做更新并且要保证回调处理逻辑本身可以重复执行。换句话说商户自己的回调接口也要做幂等设计否则Jeepay因为网络超时重发回调时商户侧就可能把同一笔订单处理两次。5. 部署避坑Jeepay环境配置与支付联调的常见问题排查5.1 部署阶段数据库初始化失败、Redis连接异常与端口占用现象一条接一条说。初始化数据库时执行到一半报错日志里出现Unknown collation: utf8mb4_0900_ai_ci。原因是MySQL 8.0默认的排序规则在5.7里不存在脚本是给8.0环境写的。解决方法是把脚本里所有utf8mb4_0900_ai_ci替换成utf8mb4_unicode_ci或者直接换MySQL 8.0初始化两种路都行但要注意替换之后的脚本要在5.7和8.0上都能跑通建议用sed批量替换后再导入。服务启动时控制台刷Unable to connect to Redis但本地Redis明明能连。这个现象多数不是Redis服务挂了而是配置文件和实际运行环境不匹配。比如配置文件里写了Redis密码但本地Redis没设置密码连接就是会被拒绝。还有种情况是Redis只绑定了127.0.0.1而Java服务跑在容器里网络隔离导致连不上。解决办法是把application.yml里的Redis配置改成实际环境的值容器部署时推荐用环境变量覆盖配置不要把密码硬编码在代码仓库里。端口占用问题在同时启动多个Jeepay工程时特别常见。支付核心、运营平台、商户平台默认端口不同但8080端口经常被本地的其他服务占掉。启动报Port 8080 was already in use时直接用lsof -i:8080查占用进程把端口改了就行。改端口时注意不仅要改application.yml里的server.port还要检查后台管理系统里有没有硬编码回链地址否则登录成功之后跳转的地址还是旧端口。5.2 联调阶段回调接收不到、验签失败与订单状态卡住本地联调最让人头疼的是回调链路。用户在沙箱环境支付成功Jeepay这边订单状态却一直是等待支付商户后台也收不到通知。先用最简单的方式验证打开支付核心的后台日志搜索订单号看有没有渠道回调的记录。如果日志里根本没有回调说明回调没有到达Jeepay如果日志里有回调但处理失败说明问题出在回调解析或验签。回调到不了绝大多数原因是回调地址配置错误。渠道侧回调时无法访问内网地址比如http://127.0.0.1或http://192.168.x.x需要配置成公网可访问的地址。本地开发时用内网穿透工具服务器部署时用真实的HTTPS域名。还有少部分是渠道侧的回调地址是支付下单时动态传的不是商户后台全局配置的这种就检查下单参数里有没有把回调地址覆盖掉。验签失败是第二高频问题。现象是回调到了但日志提示验签不通过。原因往往不是密钥错了而是签名计算时参数处理不一致。渠道回调里包含的空值字段、sign字段本身、参数名大小写任何一处不一致都会导致验签失败。解决的唯一可靠办法是打开渠道侧的回调日志和Jeepay接收到的原始参数逐个字段对比写一个独立的调试接口把接收到的参数原样打印出来眼过一遍比反复猜快得多。订单卡住长时间不更新可能不是回调问题而是补单任务没跑起来。有些版本的补单定时任务默认间隔较长比如30分钟测试时等不起。处理办法是把补单任务的时间阈值临时调短比如改成3分钟联调完再恢复。如果连补单任务都没有触发检查是不是用了分布式任务调度框架但没有配置执行器本地单机部署时这部分很容易漏配。5.3 生产阶段密钥泄露、订单并发与日志追踪的注意点生产环境遇到的坑和测试环境完全是两回事。最常见的是API密钥泄露导致被刷单。Jeepay这类系统里密钥就是商户调用接口的通行证一旦泄露别人就可以用它下单、查单、甚至发起退款。密钥管理的基本要求是不允许明文出现在数据库表里存储时加密日志打印参数时把sign和apiKey打码定期更换密钥时保证新旧密钥有一段并行期避免切换瞬间商户全部调用失败。订单并发问题在生产环境会暴露得很明显。同一个订单号被渠道侧重复回调或者商户侧因为没有做幂等把支付中的订单重复更新成已关闭状态。Jeepay里对订单状态更新做了条件限制但如果你在二次开发时加了自己的更新逻辑必须加上状态条件。数据库层面用UPDATE ... WHERE status pending返回影响行数为0就说明状态已经被其他请求修改这时候直接返回失败不要做任何覆盖操作。日志追踪是生产排查的基础设施。支付系统每天几万笔订单只靠搜订单号定位问题效率极低。最实用的做法是全链路透传一个traceId从商户调用进来时生成贯穿下单、回调、补单任务、对账记录日志框架里把traceId输出到单独一个字段方便用日志平台按traceId聚合。曾经有一次线上订单状态对不上靠这个traceId把这笔订单在三台机器上的所有日志捞出来十分钟就定位到了是回调重复导致的没有这个字段的话估计要捞一下午。6. 进阶玩法用Jeepay沉淀一套通用的支付中台能力6.1 从单体到微服务支付网关独立化的演进路径Jeepay按业务域拆分工程已经是微服务的雏形但真正要支撑多条业务线时还需要把支付能力进一步独立成平台。常见做法是把支付核心单独拆出来做成一个支付网关服务所有业务方都通过它下单、查单、接收回调业务侧不再直接感知底层渠道。这样做的好处是支付相关的路由规则、渠道切换、故障降级都收口在网关层业务系统只需要关心自己的业务订单。6.2 对账文件自动化核对差异订单的收集与重试对账任务跑批时可以把差异结果输出到一个统一的差异单表再配合可视化的后台页面人工处理。脚本触发的时机最好是渠道侧出账单之后避开白天交易高峰。以下是一段简化版的差异核对SQL逻辑-- 找出本地订单成功但渠道账单缺失的记录 SELECT o.order_id, o.amount, o.pay_time FROM pay_order o LEFT JOIN channel_bill c ON o.order_id c.order_id WHERE o.status success AND c.bill_date #{reportDate} AND c.order_id IS NULL;把这类查询固化到对账模块里配合消息通知把差异单推给财务处理比每天人工捞数高效得多。注意保留渠道账单的原始明细因为渠道侧补传数据或者人工修复时要能回溯是哪一笔账单出了问题。6.3 压测、故障演练与灰度发布的落地方法上生产之前要至少做两轮验证。第一轮是常规压测重点看下单接口的TPS和响应时间方法是用压测工具模拟100个并发用户连续下单同时观察数据库连接池和Redis的负载。第二轮是模拟渠道故障比如把某个渠道的配置改成错误参数看路由规则能否快速切换到其他渠道以及回调失败后的补单任务能否在预期时间内完成状态修正。在灰度发布策略上支付网关的切换适合用“按商户灰度”而不是按流量百分比。挑几个测试商户先切到新网关观察两三天的对账差异率确认没有问题后再逐步放量。支付系统出问题的代价比普通业务系统高回滚方案要在发布前准备好确保切换后短时间内可以切回旧链路否则一旦线上问题持续十几分钟对商户的影响就是真金白银。我吃过一次亏当时赶着上线新渠道压测只测了下单链路没测回调吞吐。结果活动当天渠道侧集中回调接收回调的线程池被打满大量订单状态更新延迟补单任务又因为重复触发造成数据库锁等待。后来在回调入口加了消息队列削峰再用版本号做状态更新的乐观锁类似的故障再没出现过。Jeepay能帮你把支付主链路搭起来但真正让它稳定扛住业务的是对账、限流、幂等这些细节的打磨。希望帮到你。本文还有配套的精品资源点击获取 Jeepay开源聚合支付系统实战：Java工程师部署与二次开发指南
简介一套基于Java的开源聚合支付系统Jeepay面向需要整合微信、支付宝、云闪付等多渠道支付能力的开发者与企业。系统内置支付网关自动路由已对接微信服务商及普通商户V2/V3、支付宝服务商及普通商户RSA/RSA2、云闪付服务商并采用签名机制保障交易安全适合作为电商、SaaS平台或金融机构的支付中台。资源包共387个文件以322个Java源码为主辅以XML配置、SQL初始化脚本、YML环境配置及Shell部署脚本压缩包仅7.05MB结构紧凑便于本地搭建。管理端包含运营平台与商户系统界面简洁前后端分离权限基于Spring Security订单通知通过MQ实现高可用渠道参数配置可自动化生成。已有95人学习下载附带的开发文档和搭建说明能大幅降低二次开发门槛适合有Java基础并希望深入支付领域的开发者。1. Jeepay是什么为什么一个开源的Java支付系统值得你亲自部署一遍一个支付系统真正吃功夫的从来不是“收钱”那一下而是收完钱之后的账怎么算、渠道怎么切、订单怎么对。Jeepay就是这样一套用Java写成的开源聚合支付系统它把多商户进件、多渠道聚合、统一收银台、结算分账和对账报表全部做成了可以部署的工程代码省掉了从零攒轮子的过程。这篇按一条真实的落地路径把Jeepay从部署到二次开发的关键步骤和参数讲清楚适合学过Spring Boot的Java工程师、给多商户做增值服务的小团队以及想自建支付中台的技术负责人。2. 拆解Jeepay的技术骨架聚合支付与四方支付的核心设计思路2.1 聚合支付与四方支付先搞清楚Jeepay到底做了什么Jeepay的定位经常被人一句话说成“一个支付后台”但这个说法太容易让人低估它的设计范围。先理清几个概念所谓聚合支付指的是把微信、支付宝、云闪付这些不同渠道的收款能力封装成一套统一接口商户不需要分别对接每一个渠道的文档只要调一个接口就能发起一笔收款。而四方支付是在三方支付和银行渠道之上做聚合、路由、分账、对账的技术服务方本身不直接触碰资金也不持有支付牌照但承担了商户接入、渠道管理、订单匹配这些脏活累活。Jeepay做的正是四方支付模式的项目落地。它把“聚合支付”的通用能力拆成了运营、商户、支付核心三条链路运营侧管商户进件和费率商户侧管应用和订单查询支付核心管渠道调用和回调转译。这个分层不是拍脑袋设计的它直接对应了四方支付平台在业务上的三个角色——平台运营方、入驻商户、底层渠道。理解了这个模型后边看数据库表结构和接口设计都会顺很多。有一点容易被忽略四方支付系统里资金流和信息流是分离的。用户付钱钱直接进的是渠道侧的三方支付账户Jeepay能做的只是记录订单状态、计算分账金额、定时对账。这意味着所有金额字段都不能用浮点型所有状态变更都要留操作日志渠道回调与本地订单的金额不一致时必须按差异单处理。这些约束在后边的开发中会反复出现先把模型立住再动手写代码才不会越改越乱。2.2 六大核心模块从商户进件到资金结算的完整闭环把Jeepay代码仓库打开会发现它的后端工程是按业务域拆分的大体可以分成六个核心模块它们合起来才构成从商户进件到资金结算的完整闭环。模块核心职责关键数据商户系统商户信息、应用信息、进件审核mch_info、mch_app渠道系统渠道参数配置、渠道类型管理pay_channel、pay_channel_route支付核心下单、渠道调用、回调接收、订单状态机pay_order、pay_pending_task结算系统分账配置、结算单生成、提现管理settle_record、profit_allocation对账系统渠道账单拉取、本地流水比对、差异处理reconciliation_diff运营后台费率配置、公告、运维数据统计各类统计汇总表商户系统是入口。一个商户进来之后平台要给他创建商户号然后再创建应用每个应用对应一套独立的API密钥和回调配置。真实业务里一个商户可能有好几个应用App、小程序、H5各一个每个应用可以单独配置允许使用哪些渠道也可以设定不同的费率。这一步管不好后边对账和结算全都会乱。渠道系统是Jeepay最值得借鉴的一层设计。它把“微信下单”和“支付宝下单”这类动作抽象成了统一的渠道接口每个渠道自己实现下单、查单、回调解析、验签这几个方法。新增一个渠道时核心代码改动被限制在渠道实现类里不需要碰业务层。这其实就是策略模式在支付系统里的标准应用但很多自研支付系统做到后面会把渠道判断散落在Service层里改一个渠道要牵连好几个文件Jeepay这种收敛方式值得直接抄。支付核心是整个系统的发动机。它接收商户的下单请求根据路由规则选中一个可用渠道生成渠道侧的交易参数再返回给商户端一个收银台地址。用户支付完成之后渠道系统异步回调到Jeepay支付核心解析回调内容、验签、更新本地订单状态再通过商户通知接口把结果推给商户。这条链路上最怕的不是渠道挂掉而是回调丢或重复所以Jeepay在状态更新时做了防重和幂等后边章节细聊。结算和对账是四方支付里真正体现价值的部分。渠道侧的钱经过一段时间才能结算到平台账户平台再按分账规则把钱结算给商户。这个过程需要把渠道账单、本地订单、结算记录三份数据拉到一起比出现差异后生成差异单人工介入处理。很多小团队做支付系统收单功能上线很快但结算跑批和对账脚本能拖上一个月就是低估了这三方数据对齐的工作量。2.3 支付流程设计下单、渠道路由与回调通知的关键设计一次标准支付在Jeepay里的时序可以压缩成五个步骤商户后端调用下单接口传入商户号、应用ID、订单号、金额、回调地址。支付核心校验参数和签名生成支付订单按路由规则选中渠道。返回渠道收银台地址或支付参数商户端把用户引导到对应页面。用户在渠道侧完成支付渠道回调Jeepay的支付结果的地址。支付核心验签后更新订单状态调用商户回调接口通知商户。这五步看起来简单真正写起来每一步都有边界情况。比如第二步的路由规则不能只看渠道开通没开通还要看当前渠道是否在维护窗口、单笔限额是否满足、商户是否被限制使用该渠道。有些实现会把路由做成可配置的权重轮询比如微信和支付宝各占50%流量某个渠道连续失败就自动摘除。Jeepay里这种路由配置和渠道参数是分开存储的做二次开发时可以直接在路由表上做文章。第五步的回调通知是埋坑最多的地方。渠道侧回调同一个订单可能重复触发商户回调接口可能超时或返回异常这两件事叠加起来就会导致订单状态不一致。常见的处理方式是引入补单任务定时扫描处于“支付中”状态且超过一定时间的订单主动向渠道侧发起查单根据查单结果修正本地订单状态再触发商户通知。补单任务本身要支持手动触发因为有些渠道查单接口也有延迟人工触发是为了在联调阶段快速验证不用干等定时器跑完。在写补单逻辑时最直接的做法是给订单状态加一个版本号字段更新时用带条件的UPDATE语句比如“SET status 新状态 WHERE order_id ? AND status 旧状态”这样并发回调时只有一个请求能成功更新状态不会出现订单状态被后到的回调覆盖成旧值的情况。Jeepay这类支付系统的状态机本质是用数据库的行锁来解决回调乱序不要试图在Java代码里用同步锁来处理跨进程的问题。3. 本地部署从拉取代码到跑通一笔测试支付的完整步骤3.1 环境准备JDK、MySQL、Redis的版本选择Jeepay后端是标准的Spring Boot工程Java版本用8就够了不需要上17之类的新版本反而新版本JDK在运行时可能出现反射相关的兼容问题。构建工具用Maven 3.6以上IDE用IDEA可以直接打开根目录的pom.xml等待依赖下载完即可。先给出我实际验证过的一套组合避免在环境上反复折腾。组件版本选择说明JDK1.88u201Spring Boot 2.x对JDK8支持最稳定Maven3.6构建和打包后端工程MySQL5.7或8.08.0需注意排序规则兼容Redis3.2缓存、分布式锁、延迟队列都会用到前端可选Node.js 14只有跑运营后台和商户后台才需要MySQL的版本是最容易翻车的地方。Jeepay的初始化脚本里如果包含utf8mb4_0900_ai_ci这样的排序规则放到MySQL 5.7上执行会直接报错。要么把脚本里的字符集和排序规则统一改成utf8mb4和utf8mb4_unicode_ci要么直接用MySQL 8.0初始化然后连接配置里加上characterEncodingutf8mb4。数据库的时区也要注意连接串里建议加上serverTimezoneAsia/Shanghai避免Java服务本地时区和数据库时区不一致导致时间字段偏移。Redis的作用容易被新手低估。支付订单的短暂状态、渠道访问令牌、分布式锁、延迟队列都依赖Redis如果只把它当成缓存来用启动时不配密码可能没事但生产环境Redis宕机会直接影响支付链路。因为Jeepay回调和补单逻辑里大量依赖Redis的原子操作来防重Redis不可用时订单状态就没办法可靠更新。本地部署时Redis不用开持久化但生产环境至少开AOF并且设置appendfsync everysec。3.2 初始化数据库与启动服务三个Java进程怎么配合Jeepay的源码拉下来之后先不要急着用IDEA点启动按钮按顺序来。先把数据库初始化和配置改好再逐一把服务跑起来。以下是我常用的命令序列在项目根目录下执行。# 拉取代码 git clone https://gitee.com/jeequan/jeepay.git cd jeepay # 初始化数据库执行根目录下的init脚本 mysql -uroot -p jeepay-db/init.sql # 进入支付核心工程修改数据库和Redis配置 vim jeepay-payment-boot/src/main/resources/application.yml # 重点修改这几项 # spring.datasource.url、username、password # spring.redis.host、port、password # 打包并启动支付核心 mvn -pl jeepay-payment-boot clean package -DskipTests java -jar jeepay-payment-boot/target/jeepay-payment-boot.jar 先启动支付核心的理由很直接商户平台和运营平台在登录之后会有大量查询支付订单的操作如果支付核心没起来后端的Feign调用会报连接失败控制台刷错误日志。三个工程的依赖关系是支付核心在最底运营和商户平台在中间前端页面在最上。很多人第一次跑项目时习惯一次性把所有服务全启动结果日志混在一起看不出问题建议逐个启动等前一个的端口能访问了再起下一个。支付核心的application.yml里还有一个容易被忽略的参数is_dev开发环境下设为true会打印更多调试日志也会跳过一些签名校验方便本地联调。但要注意这个参数在生产环境一定要关掉否则回调接口会存在严重安全隐患。另外渠道的证书文件路径要确认存在有些渠道在初始化时会加载证书路径配错了启动都不会报错但真正发起支付时会直接抛异常。3.3 配置支付渠道接入一个测试支付参数的参数说明初始化脚本执行完之后运营平台和商户平台里是没有任何可用渠道的。要在测试环境跑通一笔支付需要先在运营平台里配置一个支付渠道。打开运营平台的“支付渠道”菜单选择渠道类型会看到一串待填写的参数。我把关键的几项列出来并说明它的实际作用。参数示例说明渠道类型WX_PAY / ALI_PAY微信或支付宝商户号微信侧分配的mch_id渠道侧识别平台身份的编号应用IDwx123456789不同端使用的appIdAPI密钥32位随机字符串生成签名和验签使用API证书apiclient_cert.p12微信退款和查单需要回调地址https://api.example.com/api/payment/callback接收渠道通知的地址回调地址是本地联调里第一个坎。如果用内网穿透工具把本地服务暴露出去回调地址必须填穿透工具生成的公网HTTPS地址如果是在服务器上部署填真实域名并配好HTTPS证书。很多渠道要求回调地址必须是HTTPS且非局域网IP直接用IP地址会被拒绝。首次联调时最容易遇到“支付成功但本地收不到回调”十有八九是回调地址填错。4. 二次开发与定制接口签名、分账与商户系统的对接要点4.1 接口规范统一签名算法与应用令牌的传递方式Jeepay给商户提供了统一的下单、退款、查单接口这些接口共享一套签名规则。签名的作用不是为了加密而是让服务端能够确认请求来自合法的调用方同时防止请求参数被中途篡改。接口约定一般是这样商户应用创建时生成一个API密钥调用接口时把所有参数按字典序拼接加上密钥后做MD5得到的字符串作为sign字段传过来。// 签名工具示例基于TreeMap自动按key排序 public static String generateSign(MapString, String params, String apiKey) { TreeMapString, String sorted new TreeMap(params); StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sorted.entrySet()) { String key entry.getKey(); String value entry.getValue(); // 签名参数本身不参与计算空值也要剔除 if (sign.equals(key) || value null || value.isEmpty()) { continue; } sb.append(key).append().append(value).append(); } // 拼接密钥后做MD5 sb.append(key).append(apiKey); return DigestUtils.md5Hex(sb.toString()); }这段实现里有三个细节值得注意。TreeMap保证了参数按字典序排序省去了手动排序的代码过滤空值的逻辑必须写否则渠道侧多传一个空参数就会导致签名结果不同最后拼接的密钥不带value空串因为apiKey是平台固定的不需要参与排序。登录和鉴权环节除了签名还依赖应用令牌。商户调用接口时在请求头里带上tokentoken由商户应用ID和密钥动态生成。Jeepay的服务端会维护一份token到应用信息的映射缓存到Redis里过期后要求重新获取。做二次开发时如果要新增一个商户自定义接口记得先鉴权再处理业务逻辑不要因为内部系统就跳过签名校验。4.2 扩展一个新支付渠道从渠道配置到回调适配的改动范围接入一个新的支付渠道比如某些地区的本地支付App是Jeepay二次开发里最典型的任务。改动点可以收敛到三个地方渠道配置表加一条渠道类型、实现一个渠道服务类、在路由规则里允许该渠道参与选择。核心的渠道服务类通常长这样public interface IChannelService { // 返回渠道类型标识例如 LOCAL_PAY String getChannelId(); // 构建渠道侧下单参数并返回支付链接 PayOrderModel createOrder(PayOrderReq req); // 解析渠道回调请求拿到原始参数 String parseCallback(HttpServletRequest request); // 校验渠道回调的签名 boolean verifyCallback(MapString, String params); }实现这个接口时createOrder是最复杂的一步。它需要把Jeepay的支付订单转换成渠道侧要求的参数格式包括金额、商户号、回调地址、过期时间等。这里最容易踩的坑是金额单位不一致Jeepay内部通常是分但有些渠道接口要求元或者反过来。转换错误会导致用户看到的价格和实际扣款不一致这种问题在联调阶段就很难发现需要在下单和回调两端都把金额打印出来对照。新增渠道类型后渠道侧的配置文件、数据字典、页面下拉选项这些都要跟着补。核心逻辑编译通过不代表功能完整还要回到商户平台里确认这个新渠道能在创建支付订单时被路由到。一个稳妥的做法是先走通一个新渠道的最小支付链路再去补查单、退款、对账这些周边功能不要一开始就追求能力一步到位。4.3 接入商户系统的三个关键点分账、对账与回调幂等商户系统接入Jeepay时最容易出问题的不是下单而是资金相关的三个点。分账配置的粒度要到“商户应用渠道”的层级不同渠道的手续费率不同分账比例自然也不同。Jeepay里分账配置通常是在运营平台上维护商户侧只能查询做定制时要注意权限边界不要让商户自己把分账比例改成100%。对账则是每天固定时间拉取渠道账单和本地订单流水比对。差异单产生的原因一般是这三类本地订单存在但渠道账单没有渠道账单存在但本地订单状态不是成功两边金额不一致。处理差异单的正确姿势不是直接改数据库而是先跟踪渠道侧订单状态再决定本地订单是做补单还是做退款。项目中我一般会保留所有对账差异记录至少半年方便后续排查历史问题。回调幂等前面提过一次这里再强调一遍它在对接时的具体做法。商户侧接收Jeepay回调时不能先查订单再更新要直接用订单号加状态条件做更新并且要保证回调处理逻辑本身可以重复执行。换句话说商户自己的回调接口也要做幂等设计否则Jeepay因为网络超时重发回调时商户侧就可能把同一笔订单处理两次。5. 部署避坑Jeepay环境配置与支付联调的常见问题排查5.1 部署阶段数据库初始化失败、Redis连接异常与端口占用现象一条接一条说。初始化数据库时执行到一半报错日志里出现Unknown collation: utf8mb4_0900_ai_ci。原因是MySQL 8.0默认的排序规则在5.7里不存在脚本是给8.0环境写的。解决方法是把脚本里所有utf8mb4_0900_ai_ci替换成utf8mb4_unicode_ci或者直接换MySQL 8.0初始化两种路都行但要注意替换之后的脚本要在5.7和8.0上都能跑通建议用sed批量替换后再导入。服务启动时控制台刷Unable to connect to Redis但本地Redis明明能连。这个现象多数不是Redis服务挂了而是配置文件和实际运行环境不匹配。比如配置文件里写了Redis密码但本地Redis没设置密码连接就是会被拒绝。还有种情况是Redis只绑定了127.0.0.1而Java服务跑在容器里网络隔离导致连不上。解决办法是把application.yml里的Redis配置改成实际环境的值容器部署时推荐用环境变量覆盖配置不要把密码硬编码在代码仓库里。端口占用问题在同时启动多个Jeepay工程时特别常见。支付核心、运营平台、商户平台默认端口不同但8080端口经常被本地的其他服务占掉。启动报Port 8080 was already in use时直接用lsof -i:8080查占用进程把端口改了就行。改端口时注意不仅要改application.yml里的server.port还要检查后台管理系统里有没有硬编码回链地址否则登录成功之后跳转的地址还是旧端口。5.2 联调阶段回调接收不到、验签失败与订单状态卡住本地联调最让人头疼的是回调链路。用户在沙箱环境支付成功Jeepay这边订单状态却一直是等待支付商户后台也收不到通知。先用最简单的方式验证打开支付核心的后台日志搜索订单号看有没有渠道回调的记录。如果日志里根本没有回调说明回调没有到达Jeepay如果日志里有回调但处理失败说明问题出在回调解析或验签。回调到不了绝大多数原因是回调地址配置错误。渠道侧回调时无法访问内网地址比如http://127.0.0.1或http://192.168.x.x需要配置成公网可访问的地址。本地开发时用内网穿透工具服务器部署时用真实的HTTPS域名。还有少部分是渠道侧的回调地址是支付下单时动态传的不是商户后台全局配置的这种就检查下单参数里有没有把回调地址覆盖掉。验签失败是第二高频问题。现象是回调到了但日志提示验签不通过。原因往往不是密钥错了而是签名计算时参数处理不一致。渠道回调里包含的空值字段、sign字段本身、参数名大小写任何一处不一致都会导致验签失败。解决的唯一可靠办法是打开渠道侧的回调日志和Jeepay接收到的原始参数逐个字段对比写一个独立的调试接口把接收到的参数原样打印出来眼过一遍比反复猜快得多。订单卡住长时间不更新可能不是回调问题而是补单任务没跑起来。有些版本的补单定时任务默认间隔较长比如30分钟测试时等不起。处理办法是把补单任务的时间阈值临时调短比如改成3分钟联调完再恢复。如果连补单任务都没有触发检查是不是用了分布式任务调度框架但没有配置执行器本地单机部署时这部分很容易漏配。5.3 生产阶段密钥泄露、订单并发与日志追踪的注意点生产环境遇到的坑和测试环境完全是两回事。最常见的是API密钥泄露导致被刷单。Jeepay这类系统里密钥就是商户调用接口的通行证一旦泄露别人就可以用它下单、查单、甚至发起退款。密钥管理的基本要求是不允许明文出现在数据库表里存储时加密日志打印参数时把sign和apiKey打码定期更换密钥时保证新旧密钥有一段并行期避免切换瞬间商户全部调用失败。订单并发问题在生产环境会暴露得很明显。同一个订单号被渠道侧重复回调或者商户侧因为没有做幂等把支付中的订单重复更新成已关闭状态。Jeepay里对订单状态更新做了条件限制但如果你在二次开发时加了自己的更新逻辑必须加上状态条件。数据库层面用UPDATE ... WHERE status pending返回影响行数为0就说明状态已经被其他请求修改这时候直接返回失败不要做任何覆盖操作。日志追踪是生产排查的基础设施。支付系统每天几万笔订单只靠搜订单号定位问题效率极低。最实用的做法是全链路透传一个traceId从商户调用进来时生成贯穿下单、回调、补单任务、对账记录日志框架里把traceId输出到单独一个字段方便用日志平台按traceId聚合。曾经有一次线上订单状态对不上靠这个traceId把这笔订单在三台机器上的所有日志捞出来十分钟就定位到了是回调重复导致的没有这个字段的话估计要捞一下午。6. 进阶玩法用Jeepay沉淀一套通用的支付中台能力6.1 从单体到微服务支付网关独立化的演进路径Jeepay按业务域拆分工程已经是微服务的雏形但真正要支撑多条业务线时还需要把支付能力进一步独立成平台。常见做法是把支付核心单独拆出来做成一个支付网关服务所有业务方都通过它下单、查单、接收回调业务侧不再直接感知底层渠道。这样做的好处是支付相关的路由规则、渠道切换、故障降级都收口在网关层业务系统只需要关心自己的业务订单。6.2 对账文件自动化核对差异订单的收集与重试对账任务跑批时可以把差异结果输出到一个统一的差异单表再配合可视化的后台页面人工处理。脚本触发的时机最好是渠道侧出账单之后避开白天交易高峰。以下是一段简化版的差异核对SQL逻辑-- 找出本地订单成功但渠道账单缺失的记录 SELECT o.order_id, o.amount, o.pay_time FROM pay_order o LEFT JOIN channel_bill c ON o.order_id c.order_id WHERE o.status success AND c.bill_date #{reportDate} AND c.order_id IS NULL;把这类查询固化到对账模块里配合消息通知把差异单推给财务处理比每天人工捞数高效得多。注意保留渠道账单的原始明细因为渠道侧补传数据或者人工修复时要能回溯是哪一笔账单出了问题。6.3 压测、故障演练与灰度发布的落地方法上生产之前要至少做两轮验证。第一轮是常规压测重点看下单接口的TPS和响应时间方法是用压测工具模拟100个并发用户连续下单同时观察数据库连接池和Redis的负载。第二轮是模拟渠道故障比如把某个渠道的配置改成错误参数看路由规则能否快速切换到其他渠道以及回调失败后的补单任务能否在预期时间内完成状态修正。在灰度发布策略上支付网关的切换适合用“按商户灰度”而不是按流量百分比。挑几个测试商户先切到新网关观察两三天的对账差异率确认没有问题后再逐步放量。支付系统出问题的代价比普通业务系统高回滚方案要在发布前准备好确保切换后短时间内可以切回旧链路否则一旦线上问题持续十几分钟对商户的影响就是真金白银。我吃过一次亏当时赶着上线新渠道压测只测了下单链路没测回调吞吐。结果活动当天渠道侧集中回调接收回调的线程池被打满大量订单状态更新延迟补单任务又因为重复触发造成数据库锁等待。后来在回调入口加了消息队列削峰再用版本号做状态更新的乐观锁类似的故障再没出现过。Jeepay能帮你把支付主链路搭起来但真正让它稳定扛住业务的是对账、限流、幂等这些细节的打磨。希望帮到你。本文还有配套的精品资源点击获取