简介面向中国农业银行缴费中心BRIDGE新版商户直连场景的Java版DEMOV1.4专为需要接入农行在线支付能力的商户或后端开发者设计解决从接口调用、订单处理到支付回调的全流程对接问题。资源包共133个文件约6.92MB核心为57个Java源码与44个JSP页面并配套14个jar依赖、5个XML配置、2个证书文件及PDF/TXT说明文档其中Java源码承担交易逻辑JSP页面供本地联调测试jar包提供基础依赖证书用于安全通信。目前已有567人学习下载适合具备Java基础、正在对接农行缴费接口的开发者参考。通过示例代码可快速掌握下单、支付确认、退款处理及回调通知等关键业务V1.4接口文档详细说明了请求参数、响应格式与错误码配合JSP页面与本地证书可完整模拟从发起支付到接收结果的流程从而有效缩短商户系统与农行的对接周期。1. BRIDGE商户直连这套DEMO到底在解决谁的问题拿到“中国农业银行缴费中心-BRIDGE新版商户直连DEMO-JAVA版本V1.4及文档”这套东西的Java工程师多半带着两个问题BRIDGE到底怎么对接这份DEMO能不能改改就上生产。我的结论先说在前面它不能直接上生产但它是接触缴费中心“商户直连”链路时最该先看懂的一份参考实现。做缴费对接最贵的不是服务器而是“猜”。接口文档写得再细签名串顺序、回调应答格式、金额单位总有几处要拿真实报文去试。DEMO的价值就是把“猜”变成“改”换上自己的商户号、证书路径、回调地址在本地跑通一笔缴费请求后面联调和生产部署的坑才看得见摸得着。这套东西适合三类人第一次对接农行缴费中心的后端开发要在已有系统里嵌进缴费能力的架构师以及负责回调通知联调的中级Java工程师。下面按“看时序、跑DEMO、调参数、踩坑、上生产”的顺序展开新手可以一步步跟着复现熟手可以直接跳到第4章和第5章看参数与避坑。2. 拿到DEMO包先别急着跑先看懂BRIDGE的对接路径2.1 间连与直连的差别为什么农行要单独开放一套BRIDGE缴费业务里常见的接入方式是间连也就是商户把支付请求交给自己签约的收单机构或渠道方由渠道方再转发给银行。这种方式好处是商户对接简单但坏处也明显报文协议跟着渠道方走渠道方的处理逻辑像黑匣子出了问题商户只能等渠道反馈连原始报文都未必拿得到。农行缴费中心这套BRIDGE商户直连走的是另一条路。商户系统直接和缴费中心对接中间不再隔一层渠道。商户自己控制报文拼装、签名、通知应答和重试策略订单状态在哪里断的、哪笔报文验签失败全都能在自己的日志里看到。代价也很直接加密证书、签名串顺序、回调防重、对账文件解析这些事情全要商户系统自己扛。所以BRIDGE这套DEMO真正的角色是缴费中心对外开放的桥接通道的参考实现。它把“商户侧该做的事情”做成了一个能跑的Java工程而不是只丢给你一本接口文档。理解这一点再看包里那些类就不会觉得目录结构乱。2.2 DEMO包的目录结构与运行入口解压后一般是一个标准的Maven工程包名里通常带有abchina或者bridge字样。我见过的这类DEMO大体上分四块核心工具、业务服务、配置文件和文档。用tree看一下结构$ unzip BRIDGE-DEMO-JAVA-V1.4.zip $ cd bridge-demo $ tree -L 3 -I target . ├── pom.xml ├── src │ ├── main │ │ ├── java │ │ │ └── com/abchina/bridge/demo │ │ │ ├── BridgeDemoApplication.java │ │ │ ├── core │ │ │ │ ├── config/BridgeConfig.java │ │ │ │ ├── crypto/SignUtil.java │ │ │ │ └── http/HttpClientUtil.java │ │ │ └── service │ │ │ ├── PayOrderService.java │ │ │ └── NotifyReceiver.java │ │ └── resources │ │ ├── application.properties │ │ ├── merchant_private_key.pem │ │ └── platform_public_key.pem │ └── test/java/com/abchina/bridge/demo/SignTest.java └── doc ├── 接口文档V1.4.pdf └── 商户接入指南.pdf第一次接触这套代码先看三个文件就够了BridgeConfig.java是配置加载入口SignUtil.java是签名和验签实现application.properties里是所有需要替换的参数。那个BridgeDemoApplication.java是启动入口本地可以通过IDE直接跑main方法也可以打成jar包执行。这里要提醒一句目录里的merchant_private_key.pem和platform_public_key.pem在DEMO包里放的是示例密钥绝对不要直接拿它上生产。V1.4文档里会明确告知商户开发环境和生产环境的密钥获取方式通常是在商户服务平台上申请下载。2.3 一笔缴费从发起到对账的完整时序跑DEMO之前建议先把整个链路的时序画在脑子里。BRIDGE商户直连的缴费流程我一般会拆成六个步骤商户在缴费中心完成报备注册拿到商户号、应用AppId和签名密钥。用户在商户系统发起缴费商户后端生成订单号、缴费金额和缴费项目编码。商户系统把这些参数按约定拼好用商户私钥签名把报文POST到BRIDGE下单接口。BRIDGE同步返回受理结果。注意这个返回只代表银行侧“收到并受理”不等于缴费成功。银行侧完成后续处理通过异步通知把最终缴费结果推送到商户的回调地址。商户日终下载对账文件与本地订单逐笔核对。很多第一次对接的同学在第三步就把同步返回当成最终结果处理这是最容易翻车的地方。同步返回里的订单状态只代表受理状态可能是待支付、处理中这一类中间态。真正的成功或失败要以异步通知为准最终以对账文件为准。3. 本地跑通BRIDGE商户直连DEMO三步完成3.1 环境准备JDK 1.8、Maven与环境变量这套DEMO基于Java开发本地环境需要JDK和Maven。网上搜java环境变量配置详细教程能搜出一大堆这里只说和这个DEMO有关的两个关键点。第一JDK版本建议用1.8或11不要一上来就上17。原因很实际DEMO包的pom.xml里依赖的编译参数和部分库版本可能没有在更高版本JDK下验证过。我见过有人用JDK 17直接编译报了一堆“illegal reflective access”的警告虽然不一定致命但会让新手分不清是环境问题还是代码问题。第二JAVA_HOME和MAVEN_HOME要配到用户级环境变量里不要在IDE里面单独指定。因为后面打jar包、写脚本跑对账任务时命令行里还需要用到这两个变量。下面是Linux/macOS下的配置示例Windows下把export换成set即可# Linux / macOS export JAVA_HOME/usr/local/jdk1.8.0_202 export MAVEN_HOME/usr/local/apache-maven-3.6.3 export PATH$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH # 验证 java -version mvn -version配置完成后进入DEMO根目录编译打包。Maven第一次执行会下载依赖如果公司内网有Nexus私服记得在settings.xml里配置mirror否则会卡在下载阶段很久。$ cd bridge-demo $ mvn clean package -DskipTests $ java -jar target/bridge-demo-1.4.jar如果启动失败先别急着去翻代码。九成是三个原因JAVA_HOME没配对导致找不到java命令8080端口被占配置文件里的路径写错导致读取不到密钥文件。端口问题在application.properties里改server.port即可不需要动代码。3.2 配置加载与发起第一笔缴费请求跑通的第一件事是把application.properties里的参数换成本地可用的值。这个配置文件是核心字段不算多但每个都关系到链路是否能走通参数名作用示例值bridge.merchantNo商户号报备时分配M000000001bridge.appId应用标识申请密钥时关联app001bridge.privateKeyPath商户私钥文件路径classpath:merchant_private_key.pembridge.platformPublicKeyPath农行平台公钥路径classpath:platform_public_key.pembridge.gatewayUrlBRIDGE网关地址https://gateway.test.abchina.com/bridgebridge.notifyUrl接收异步通知的回调地址http://localhost:8080/notifybridge.charset报文编码UTF-8配置加载的代码在BridgeConfig.java里它的核心逻辑就是读取配置文件、校验必填项、把PEM文件加载成密钥对象。注意看代码里对路径的处理public class BridgeConfig { private String merchantNo; private String appId; private PrivateKey merchantPrivateKey; private PublicKey platformPublicKey; private String gatewayUrl; private String notifyUrl; public static BridgeConfig load(Properties props) { // 必填项校验这里不要放过空值 if (props.getProperty(bridge.merchantNo) null || props.getProperty(bridge.merchantNo).trim().isEmpty()) { throw new IllegalArgumentException(商户号不能为空检查application.properties); } BridgeConfig config new BridgeConfig(); config.merchantNo props.getProperty(bridge.merchantNo).trim(); config.gatewayUrl props.getProperty(bridge.gatewayUrl).trim(); config.notifyUrl props.getProperty(bridge.notifyUrl).trim(); // 密钥加载失败时异常要往上抛不要在catch里吞掉 config.merchantPrivateKey PemUtil.loadPrivateKey( props.getProperty(bridge.privateKeyPath)); config.platformPublicKey PemUtil.loadPublicKey( props.getProperty(bridge.platformPublicKeyPath)); return config; } }逻辑说明这个类做的事情很直白但有两个细节值得模仿。一是在加载配置时做必填校验而不是等到发请求时才报空指针这能让配置错误提前暴露。二是密钥加载失败时直接抛异常这样启动阶段就能看到问题。实际接入时如果把配置放在Nacos或Apollo里保持同样的加载模式即可。接着看发请求的部分。HttpClientUtil里一般会封装一个支持HTTPS的client核心参数是连接超时、读取超时和TLS版本。下面这个示例用的是JDK自带的java.net.http.HttpClient不引第三方依赖public class HttpClientUtil { private static final Duration CONNECT_TIMEOUT Duration.ofSeconds(10); private static final Duration READ_TIMEOUT Duration.ofSeconds(30); public static String postJson(String url, String body) throws Exception { HttpClient client HttpClient.newBuilder() .connectTimeout(CONNECT_TIMEOUT) // 连接超时单位秒 .sslContext(SSLContext.getDefault()) .build(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(url)) .timeout(READ_TIMEOUT) // 读取超时单位秒 .header(Content-Type, application/json;charsetUTF-8) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } }参数说明连接超时设在10秒比较合理因为外网链路抖动时10秒足够让TCP握手完成重试。读取超时30秒是照顾银行侧较重的报文处理但不要超过60秒否则请求堆积会把本地线程池压垮。生产环境推荐把这两个值放到配置里方便在联调期调整。发起缴费订单的代码在PayOrderService里。核心步骤是构造请求参数Map过滤空值按ASCII排序拼接签名串用SHA256withRSA签名最后把参数和签名一起POST到网关public String createPayOrder(BridgeConfig config, String orderNo, String amount, String payerName) throws Exception { // 1. 按业务字段构造参数key用接口文档里的字段名 MapString, String params new TreeMap(); params.put(merchantNo, config.getMerchantNo()); params.put(orderNo, orderNo); params.put(payAmount, amount); params.put(payerName, payerName); params.put(notifyUrl, config.getNotifyUrl()); params.put(timestamp, DateTimeUtil.now()); // 2. 在这里调用签名工具生成sign字段 String sign SignUtil.sign(config.getMerchantPrivateKey(), params); // 3. 把sign放回参数里序列化成JSON发送 params.put(sign, sign); String json JsonUtil.toJson(params); return HttpClientUtil.postJson(config.getGatewayUrl() /order/pay, json); }这段代码背后有一个容易被忽略的顺序问题拼签名时要把sign字段排除在外把其他所有字段放进TreeMap。因为TreeMap本身就按key的字典序排列省掉了手写排序。如果后续加了自定义字段一定要保持字段名和签名时的key完全一致多一个空格都会导致生产环境验签失败。3.3 异步通知的接收与应答下单接口返回后真正的结果是通过异步通知送过来的。DEMO里的NotifyReceiver是一个Spring MVC的Controller接收POST请求做验签、幂等处理、业务更新最后返回固定应答串。RestController public class NotifyReceiver { PostMapping(/notify) public String receive(RequestBody String rawBody, RequestHeader(X-Sign) String signHeader) { // 1. 拿到平台公钥验签验签失败直接返回FAIL if (!SignUtil.verify(platformPublicKey, rawBody, signHeader)) { return FAIL; } // 2. 解析报文查本地订单比对金额 MapString, String params JsonUtil.parse(rawBody); String orderNo params.get(orderNo); String payAmount params.get(payAmount); // 3. 这里做幂等同一笔订单重复通知时直接返回SUCCESS if (orderService.isProcessed(orderNo, params.get(notifyId))) { return SUCCESS; } // 4. 更新订单状态落库 orderService.updateOrder(orderNo, params.get(payStatus), payAmount); // 5. 应答银行侧收到SUCCESS后停止重发 return SUCCESS; } }应答字符串是异步通知里最关键的一环。银行侧没收到约定的成功应答会按重试策略继续推送常见的是1分钟、5分钟、30分钟间隔递增。所以这里的逻辑很明确业务处理成功才返回SUCCESS处理失败或验签失败就返回FAIL让它继续重发。本地联调时想让农行测试环境的异步通知打到本地常见做法是用内网穿透工具把本机8080端口暴露成公网地址再把bridge.notifyUrl配置成那个公网地址。这一步不复杂但要在配置文件中把notifyUrl改成“公网地址/notify”否则会出现“下单成功但一直收不到通知”的现象。4. 签名、加密与时间戳V1.4里三个必调参数4.1 签名串的拼接规则与SHA256withRSA实现农行BRIDGE这类银行开放接口签名算法基本都走RSA体系。V1.4的DEMO里用的是SHA256withRSA这一点可以从SignUtil.java里一眼确认。真正需要花心思的不是算法本身而是“签名字符串怎么拼”。最常见的规则是把所有参与签名的参数按key的ASCII字典序升序排列每个参数写成keyvalue再用连接最后把拼接结果交给签名算法。下面这段就是签名工具的核心public class SignUtil { private static final String ALGORITHM SHA256withRSA; private static final String CHARSET UTF-8; public static String sign(PrivateKey privateKey, MapString, String params) throws Exception { // 1. 拼接待签名串只拼非空值排除sign本身 String content buildSignContent(params); // 2. 调用JCE签名注意指定UTF-8 Signature signature Signature.getInstance(ALGORITHM); signature.initSign(privateKey); signature.update(content.getBytes(CHARSET)); // 3. Base64输出签名串 return Base64.getEncoder().encodeToString(signature.sign()); } public static boolean verify(PublicKey publicKey, String content, String sign) throws Exception { Signature signature Signature.getInstance(ALGORITHM); signature.initVerify(publicKey); signature.update(content.getBytes(CHARSET)); return signature.verify(Base64.getDecoder().decode(sign)); } private static String buildSignContent(MapString, String params) { // TreeMap自动按字典序排序过滤空值和sign字段 MapString, String sorted new TreeMap(); for (Map.EntryString, String entry : params.entrySet()) { String key entry.getKey(); String value entry.getValue(); if (sign.equals(key) || value null || value.isEmpty()) { continue; // 空值不参与签名 } sorted.put(key, value); } StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sorted.entrySet()) { if (sb.length() 0) { sb.append(); } sb.append(entry.getKey()).append().append(entry.getValue()); } return sb.toString(); } }逻辑说明buildSignContent里有两个硬性规则必须保住。第一个是TreeMap的排序这决定了拼接顺序任何一处手写排序都要避免因为字符串比较和字节排序可能不一致。第二个是“空值不参与签名”这不只是减少麻烦而是银行侧的验签程序就是这么实现的你多拼一个空字段两边原文就永远对不上。这里很容易踩的一个细节请求参数在发出去的时候要把sign放回参数Map里一起序列化但拼签名原文时又要把它排除。有的人图省事把整个Map直接循环一遍签出来的串在本地自测永远是对的因为本地没有平台验签等到联调时才暴露。租下来一条经验DEMO里的SignTest这个测试类就是专门用来验证签名工具和文档示例是否一致的跑这个测试应当成为改代码后的第一件事。4.2 平台公钥、商户私钥、时间戳三个必须核对的参数对完签名逻辑真正决定“联调能不能一次过”的是三个参数平台公钥、商户私钥、时间戳。这三个参数在DEMO里都有默认值但各有各的坑。第一个是商户私钥。银行侧签发的私钥通常是PKCS8格式而很多程序员以前用的开源工具默认生成PKCS1格式。两种格式的PEM文件头不同加载方式也不同。如果加载时发现“只差一行头文件”的报错多半是私钥格式没对齐。第二个是平台公钥。平台公钥是用来验异步通知签名的它和商户私钥是一对一对的不假但平台公钥的版本更新会变。很多生产事故都出在“联调用的是老版本平台公钥上线前平台侧的密钥轮换没同步”导致上线当天所有异步通知验签失败。第三个是时间戳。这个参数很容易被忽略但它承担的是防重放攻击的作用。银行侧拿到请求后会检查timestamp与网关服务器当前时间的偏差超过窗口就拒绝。联调时如果商户服务器时间没同步或者时区不对会间歇性出现“上一笔能通、下一笔就报时间过期”的玄学问题。参数配置位置出错表现建议商户私钥bridge.privateKeyPath本地签名成功平台验签失败确认PEM是PKCS8格式换行符完整平台公钥bridge.platformPublicKeyPath异步通知验签失败上线前向银行侧确认公钥版本做环境隔离时间戳业务请求参数间歇性“订单已过期”服务器用NTP同步统一UTC8不要用本地时间这个表格值得打印出来贴在工位边上。我见过太多联调周被这三个参数折磨的团队最后发现不是代码写错是密钥文件从测试环境拷到生产环境时被Windows记事本改坏了换行符。4.3 调试时最该开的三类日志调试银行对接日志的详细程度直接决定排查效率。我一般会要求项目里至少开三类日志请求响应报文日志、HTTP调用耗时日志、验签结果日志。报文日志要打原始请求和响应但不要盲打。卡号和证件号这类敏感字段要先做脱敏再输出简单的方式是统一走一个LogUtil.mask()方法。耗时日志主要记录每次POST网关的耗时银行侧接口在联调期经常有偶发慢请求没有耗时记录很难确认是网络抖动还是银行侧处理慢。验签结果日志要把验签时的原文和签名串也打出来方便和银行侧核对。logging: level: com.abchina.bridge.demo.core: DEBUG com.abchina.bridge.demo.service: INFO org.apache.http.wire: ERROR这个配置的意思是核心工具包打DEBUG方便看签名原文业务服务打INFO避免日志刷屏HTTP client的wire日志必须关掉或打到ERROR因为wire日志会打印超文本传输协议的原始字节流里面可能带着完整报文既大又敏感。生产环境连DEBUG都不要开只在联调阶段短暂开启。5. BRIDGE商户直连接入避坑盘点5.1 本地跑通、上线验签失败私钥格式与换行符现象本地联调一切正常代码原封不动部署到生产第一次请求就返回验签失败。原因八成是私钥文件在传输或部署过程中被改动过。最常见的是从Windows传输到Linux服务器后PEM文件末尾的换行符从\r\n变成了\n或者文件被文本编辑器打开保存过一次行尾被重写。这类问题用编辑器看文件时一点异常都看不出来但程序加载出来之后密钥字节就变了。解决部署后第一时间用命令行做一次密钥指纹校验对比本地和服务器上的私钥SHA256值如果不同就重新上传并且上传用二进制模式。我的习惯是把密钥文件放进配置管理系统时固定用base64转储应用启动时解码加载能彻底避开换行符问题。5.2 异步通知收不到回调地址和应答体不对现象下单接口调用成功日志里能看到响应报文但商户系统一直收不到异步通知。检查回调地址配置看起来也没问题。原因两种情况最常见。一种是回调地址配在了内网地址或公网不可达的域名上银行侧的服务器根本访问不到。另一种是回调接口返回的应答体不对银行侧只认文档里约定的成功应答串返回了普通JSON或HTTP 200但内容是{code:0}会被当成失败继续重发。解决联调阶段先用curl从外网访问一下notifyUrl确认能通。再检查Controller返回值必须原样返回文档约定的字符串注意大小写和空格。这类问题的排查思路很简单但每次接入都会有人踩因为它藏在“明明下单成功了”的错觉背后。5.3 中文乱码UTF-8与GBK的混用现象缴费项目名称、缴费人姓名在收到异步通知后显示乱码或者下单请求里传中文导致签名失败。原因本地开发环境默认UTF-8但生产服务器的操作系统可能使用了GBK或其他默认字符集。DEMO里明确配置了bridge.charsetUTF-8但Controller接收请求时如果Spring Boot没有显式设置字符集容器的默认编码可能跟随系统。解决在application.properties里补上server.servlet.encoding.charsetUTF-8和server.servlet.encoding.enabledtrue。更保险的做法是在HttpClientUtil里显式指定UTF-8同时确保代码里所有字符串转字节的操作都带Charset参数不要用getBytes()无参版本。乱码在联调阶段不一定会暴露因为有些开发环境碰巧都是UTF-8生产环境一换就现原形。5.4 重复通知导致重复下单幂等表必须建现象本地单测时手动重发了两次通知发现数据库里生成了两笔相同的订单。原因银行侧的重试机制会带来重复通知网络抖动也可能让同一通知被发送多次。异步通知接口如果只判断“订单存在就不处理”那么正在处理中或已完成的订单仍可能被重复更新。解决建一张通知幂等表唯一键用“商户号订单号通知编号”处理前先插入记录插入冲突就直接返回SUCCESS。注意不要把唯一键只建成“订单号”因为同一订单的重试通知需要被识别为重复但真正的不同通知编号要能被记录。这个表还能顺便记录通知到达时间排查问题时有据可查。5.5 对账文件里的金额和时区现象日终对账时发现银行侧文件和本地订单的金额对不上有的差几分钱有的差一整天。原因金额单位不一致。接口报文里的金额可能以分为单位传整数对账文件里的金额却可能带小数或反过来。另一个坑是文件里给的交易日期可能用UTC8以外的时间格式解析成Java的LocalDateTime时没有指定时区导致跨天订单被算到前一天。解决对接第一件事就把文档里的金额单位拿出来核对明确“元”还是“分”写一个转换工具类统一口径。时间字段解析时用带时区的OffsetDateTime或者显式指定ZoneId.of(Asia/Shanghai)。这类问题排查起来非常耗时因为它不会报错只会让数字悄悄不对。6. 从DEMO到生产上线前这样验证有机会把DEMO真正推到生产的人一定会在上线前那一周重新审视整个对接质量。我的做法是列一个十项左右的验证清单一项一项过不凭感觉。验证项方法通过标准密钥文件完整性本地和服务器算SHA256对比完全一致签名工具与文档一致跑DEMO里的SignTest所有断言通过网关地址环境正确查看配置文件并ping通测试/生产各自独立时间戳窗口手动修改服务器时间偏移5分钟请求被拒绝或通过符合预期通知幂等脚本连续重放同一通知10次只落库一次结果回调应答模拟验签失败返回FAIL平台侧能收到并停止重发乱码回归用带中文的缴费项目跑通一笔全程无乱码对账文件解析用真实测试环境文件跑一遍金额平、时间对上线前替换配置的四项要单独拎出来核对商户私钥、平台公钥、网关地址、回调域名。这四项里任何一项用了测试环境的值生产都会在第一批请求时报错。我习惯在启动时打印一份“配置指纹”就是商户号、密钥文件SHA256、网关地址的缩写登录生产服务器看一眼就知道环境对不对。对账文件的定时拉取是另一个容易后补的功能。不要把它放在异步通知里顺带做通知只是单笔结果对账文件才是日终闭环。常见做法是单独跑一个定时任务凌晨拉取前一天文件做逐笔核对差异结果写到告警表。定时任务框架可以用Spring自带的任务也可以用成熟的调度框架但核心是把“对账”和“通知”这两条责任链分开谁出了问题都能独立定位。最后说个我自己的教训。有一年上线前我检查了代码、换了密钥、配了新网关唯独没有确认平台公钥的版本。联调阶段一直是老版本上线当天银行侧把平台公钥切到了新版本结果所有异步通知验签失败整个缴费入口瘫痪了一个上午。从那以后每次环境切换我第一件事就是打印公钥的指纹对比看过才继续。这套BRIDGE DEMO本身写得很完整但DEMO帮你省掉的只是“拼报文”的重复劳动密钥、环境、时间戳这些活还是得自己一步步验证到位。希望帮到你。本文还有配套的精品资源点击获取