简介chinapay-java-new 是一套面向 Java Web 开发者的银联 ChinaPay 支付接口对接示例工程适合正在接入或调试银联支付功能的初中级开发者参考。压缩包共 72 个文件约 5.05MB以 17 个 java 源码与 17 个 class 编译文件为核心配合 15 个 jar 依赖包、10 个 jsp 页面以及 properties、xml 等配置文件构成一个可直接导入 Eclipse 的完整 Web 项目。目录中 src 存放业务源码WebContent 下含 index.jsp 与 WEB-INF 配置res、test、build 等模块分别对应资源、测试与构建产物结构清晰便于按模块查阅。目前已有 431 人学习下载。读者可从中获取支付请求组装、签名验签、回调处理等关键环节的实现思路并借助现成的工程骨架快速搭建本地调试环境减少从零摸索接口文档的时间成本。1. chinapay-java-new从支付通道对接到生产级容错这套方案到底解决什么问题如果你正在做国内支付通道的 Java 接入大概率绕不开 chinapay-java-new 这个方向。它不是一个泛泛的工具类集合而是围绕 ChinaPay银联电子支付通道把「签名、验签、报文组装、异步通知、对账、退款、查询」这一整条链路用 Java 重新梳理成可维护、可测试、可上生产的工程结构。很多团队第一次接支付时代码能跑通就上线结果一到生产环境就翻车异步通知重复回调导致重复发货、验签失败排查三天、退款状态和本地订单状态对不上。这套方案要解决的就是这些真实痛点适合正在做支付模块的 Java 工程师、需要对接银联通道的后端团队以及想把支付代码从「能跑」提升到「敢跑」的开发者。2. 支付通道对接的底层逻辑为什么不能只写一个 HTTP 请求2.1 ChinaPay 的报文结构和签名机制ChinaPay 的接口本质上是一套基于 HTTP 的报文交换协议但它的报文不是简单的 JSON而是「键值对 签名」的组合。常见做法是把业务参数按特定顺序拼接成待签名字符串再用商户私钥做签名最后把签名和业务参数一起发给支付网关。这里最容易出问题的地方是签名顺序和编码。// 构造待签名字符串按参数名 ASCII 升序排列排除空值和 sign 字段 public String buildSignSource(MapString, String params) { ListString keys new ArrayList(params.keySet()); Collections.sort(keys); // ASCII 升序这是 ChinaPay 的硬性要求 StringBuilder sb new StringBuilder(); for (String key : keys) { String value params.get(key); if (value null || value.isEmpty() || sign.equals(key)) { continue; // 空值和签名字段不参与签名 } sb.append(key).append().append(value).append(); } // 去掉末尾的 if (sb.length() 0) { sb.deleteCharAt(sb.length() - 1); } return sb.toString(); }这段代码的逻辑说明ChinaPay 要求参数按 ASCII 码升序排列空值不参与签名签名字段本身也不参与。参数说明params是业务参数 Mapsign字段在签名时排除验签时同样排除。很多开发者在这里踩坑是因为用了TreeMap但没处理空值或者用了HashMap导致顺序不稳定。我一般会显式用List排序避免依赖 Map 的实现细节。2.2 签名算法选型和密钥管理ChinaPay 常见支持 RSA 和 SHA1WithRSA部分场景也支持 MD5。选型上如果通道支持 RSA优先用 RSA因为密钥不用在网络上传输安全性更高。密钥管理是另一个血泪经验重灾区私钥不能硬编码在代码里也不能提交到 Git。常见做法是放在配置中心或环境变量启动时加载到内存并且做一次格式校验。// 从 PKCS8 格式的私钥字符串加载 PrivateKey public PrivateKey loadPrivateKey(String privateKeyStr) throws Exception { // 去掉 PEM 头尾和换行符 String cleaned privateKeyStr .replace(-----BEGIN PRIVATE KEY-----, ) .replace(-----END PRIVATE KEY-----, ) .replaceAll(\\s, ); byte[] keyBytes Base64.getDecoder().decode(cleaned); PKCS8EncodedKeySpec spec new PKCS8EncodedKeySpec(keyBytes); KeyFactory kf KeyFactory.getInstance(RSA); return kf.generatePrivate(spec); }逻辑说明PKCS8 是 Java 默认支持的私钥格式如果拿到的是 PKCS1 格式需要先转换。参数说明privateKeyStr是配置中心下发的私钥字符串cleaned去掉了 PEM 头和空白字符。注意不要用getBytes()不指定字符集否则在不同环境下可能因为默认字符集不同导致 Base64 解码失败。2.3 异步通知的幂等处理异步通知是支付对接里最容易出生产事故的地方。ChinaPay 会多次回调同一个通知直到你返回成功标识。如果你的接口没有幂等处理就会重复发货、重复加积分。常见做法是用「商户订单号 通知类型」做唯一键在数据库里建唯一索引插入成功才处理业务插入冲突就直接返回成功。// 幂等处理基于数据库唯一索引 public boolean handleNotify(String orderNo, String notifyType) { try { // 尝试插入通知记录唯一索引冲突会抛异常 notifyRecordMapper.insert(new NotifyRecord(orderNo, notifyType, new Date())); return true; // 插入成功说明是第一次通知 } catch (DuplicateKeyException e) { // 唯一索引冲突说明已经处理过直接返回成功 return false; } }逻辑说明利用数据库唯一索引的原子性来保证幂等比先查后插更可靠。参数说明orderNo是商户订单号notifyType是通知类型支付、退款等。注意插入记录和业务处理要在同一个事务里或者先插入记录再处理业务处理失败要删除记录或标记状态否则会出现「记录存在但业务没处理」的黑匣子情况。3. 用 Java 把支付链路跑通从配置到对账的最小闭环3.1 环境配置和依赖引入先把工程骨架搭起来。如果你用 Maven核心依赖其实不多HTTP 客户端、JSON 解析、签名工具。我一般用 OkHttp 做 HTTP 请求Jackson 做 JSON 处理签名用 JDK 自带的java.security就够了不需要额外引 BouncyCastle除非通道要求国密。!-- pom.xml 核心依赖 -- dependencies dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.17.0/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.32/version scopeprovided/scope /dependency /dependencies逻辑说明OkHttp 负责和支付网关通信Jackson 负责报文序列化Lombok 减少样板代码。参数说明版本号按你项目实际情况调整但建议 OkHttp 不低于 4.xJackson 不低于 2.15。注意如果项目里已经有 HTTP 客户端不要为了接支付再引一个统一用现有的减少依赖冲突。3.2 支付请求的组装和发送支付请求的组装分三步业务参数准备、签名、发送。业务参数里最关键的几个是商户号、订单号、金额、币种、通知地址。金额单位通常是分不是元这个坑每年都有人踩。public String createPayment(PaymentRequest request) throws Exception { MapString, String params new TreeMap(); params.put(merId, merchantConfig.getMerId()); params.put(orderNo, request.getOrderNo()); params.put(amount, String.valueOf(request.getAmountInCents())); // 单位分 params.put(currency, 156); // 156 代表人民币 params.put(notifyUrl, merchantConfig.getNotifyUrl()); params.put(returnUrl, merchantConfig.getReturnUrl()); params.put(transType, 01); // 01 代表消费 // 生成待签名字符串并签名 String signSource buildSignSource(params); String sign rsaSign(signSource, privateKey); params.put(sign, sign); // 发送请求 String response httpClient.post(gatewayUrl, params); return response; }逻辑说明用TreeMap保证参数顺序金额转成分为单位币种用 ISO 数字代码。参数说明merId是商户号orderNo是商户订单号amount是金额分currency是币种代码notifyUrl是异步通知地址transType是交易类型。注意notifyUrl必须是公网可访问的地址不能带内网 IP 或 localhost否则支付网关回调不到。3.3 异步通知的接收和验签异步通知的接收接口要做三件事验签、幂等、返回成功标识。验签是第一步验签不过直接返回失败不要处理业务。PostMapping(/notify) public String handleNotify(RequestParam MapString, String params) { // 1. 验签 String sign params.get(sign); MapString, String signParams new HashMap(params); signParams.remove(sign); String signSource buildSignSource(signParams); boolean valid rsaVerify(signSource, sign, platformPublicKey); if (!valid) { log.warn(验签失败参数{}, params); return fail; } // 2. 幂等处理 String orderNo params.get(orderNo); String notifyType params.get(transType); if (!handleNotify(orderNo, notifyType)) { return success; // 已处理过直接返回成功 } // 3. 业务处理 try { paymentService.processNotify(params); return success; } catch (Exception e) { log.error(业务处理失败orderNo{}, orderNo, e); return fail; // 返回失败让支付网关重试 } }逻辑说明验签用平台公钥幂等用数据库唯一索引业务处理失败要返回失败让网关重试。参数说明params是支付网关回调的参数platformPublicKey是平台公钥orderNo是商户订单号。注意返回的字符串必须是通道要求的格式通常是success或ok不要返回 JSON否则通道会认为你处理失败。3.4 对账文件的下载和解析对账是支付系统的后悔药。每天定时下载对账文件和本地订单做比对发现差异及时处理。ChinaPay 的对账文件通常是 CSV 或定长格式解析时要注意编码和字段分隔符。public void reconcile(LocalDate date) throws Exception { // 下载对账文件 String fileName CHINAPAY_ date.format(DateTimeFormatter.BASIC_ISO_DATE) .csv; File file downloadReconcileFile(fileName); // 解析对账文件 ListReconcileRecord records new ArrayList(); try (BufferedReader reader new BufferedReader( new InputStreamReader(new FileInputStream(file), StandardCharsets.UTF_8))) { String line; boolean isHeader true; while ((line reader.readLine()) ! null) { if (isHeader) { isHeader false; continue; // 跳过表头 } String[] fields line.split(,); ReconcileRecord record new ReconcileRecord(); record.setOrderNo(fields[0]); record.setAmount(new BigDecimal(fields[1])); record.setStatus(fields[2]); records.add(record); } } // 和本地订单比对 for (ReconcileRecord record : records) { LocalOrder order orderMapper.selectByOrderNo(record.getOrderNo()); if (order null) { log.warn(对账发现本地不存在订单{}, record.getOrderNo()); continue; } if (!order.getAmount().equals(record.getAmount())) { log.warn(金额不一致orderNo{}本地{}对账{}, record.getOrderNo(), order.getAmount(), record.getAmount()); } } }逻辑说明下载对账文件后逐行解析和本地订单比对金额和状态。参数说明date是对账日期fileName是对账文件名fields是 CSV 字段数组。注意对账文件的编码可能是 GBK不是 UTF-8解析前先确认编码否则中文会乱码。另外对账文件可能很大不要一次性加载到内存用流式读取。4. 生产环境避坑指南支付对接最常见的 5 个翻车现场4.1 验签失败但参数看起来没问题现象本地用同样的参数能验签通过生产环境就是失败。原因生产环境的参数经过了网关或容器可能对参数做了 URL 解码或编码导致待签名字符串和实际不一致。解决在验签前打印原始参数和待签名字符串对比本地和生产环境的差异。常见差异点是空格被转成或者中文被转成%XX。4.2 异步通知重复处理导致重复发货现象用户收到两次发货通知或者积分加了两次。原因没有做幂等处理或者幂等键设计不合理。解决用「商户订单号 通知类型」做唯一索引插入成功才处理业务。注意唯一索引要建在数据库层面不要只在代码里判断因为并发情况下代码判断不可靠。4.3 退款状态和本地订单状态不一致现象退款接口返回成功但本地订单还是「已支付」状态。原因退款是异步的接口返回成功只代表请求受理成功不代表退款到账。解决退款后订单状态改成「退款中」等异步通知或对账文件确认后再改成「已退款」。不要依赖同步返回结果更新最终状态。4.4 金额单位搞错导致多付或少付现象用户支付了 100 元实际扣款 1 元或 10000 元。原因金额单位是分不是元代码里没做转换。解决所有金额字段统一用分存储和传输只在展示层转成元。在代码里加注释并且写单元测试覆盖金额转换逻辑。4.5 对账文件解析时内存溢出现象对账文件几百 MB一次性加载到内存导致 OOM。原因用了readAllLines或readAllBytes。解决用BufferedReader逐行读取或者用流式解析库。如果对账文件特别大可以分片处理每处理一万行提交一次数据库事务。5. 进阶技巧用动态编译和热加载加速支付通道调试支付通道调试最烦的是改一行代码就要重启服务尤其是验签和报文组装这种需要反复试错的逻辑。我一般会用 Java 的动态编译能力把签名逻辑抽成一个独立的类运行时编译加载改完立即生效不用重启。// 动态编译并加载签名类 public class DynamicSignLoader { private final JavaCompiler compiler ToolProvider.getSystemJavaCompiler(); private final StandardJavaFileManager fileManager compiler.getStandardFileManager(null, null, null); public Object loadSignClass(String sourceCode) throws Exception { // 把源码写到临时文件 Path sourcePath Files.createTempFile(SignUtil, .java); Files.write(sourcePath, sourceCode.getBytes(StandardCharsets.UTF_8)); // 编译 Path outputDir Files.createTempDirectory(sign-classes); Iterable? extends JavaFileObject units fileManager.getJavaFileObjects(sourcePath.toFile()); ListString options Arrays.asList(-d, outputDir.toString()); compiler.getTask(null, fileManager, null, options, null, units).call(); // 加载类 URLClassLoader classLoader new URLClassLoader(new URL[]{outputDir.toUri().toURL()}); Class? clazz classLoader.loadClass(SignUtil); return clazz.getDeclaredConstructor().newInstance(); } }逻辑说明把签名逻辑的源码写到临时文件用JavaCompiler编译到临时目录再用URLClassLoader加载。参数说明sourceCode是完整的 Java 类源码outputDir是编译输出目录。注意动态编译有安全风险不要在生产环境开放这个能力只在开发和测试环境用。另外动态加载的类无法被 GC 回收频繁加载会导致 Metaspace 溢出所以只适合调试不适合长期运行。验证动态编译是否生效可以写一个简单的测试改一下签名逻辑里的排序规则重新加载看验签结果是否变化。如果变了说明热加载生效。这个技巧帮我在对接新通道时省了大量重启时间但记住调试完要把逻辑固化回静态代码别把动态编译带到生产。我自己的习惯是支付相关的代码宁可多写单元测试也不要依赖手工调试。每次改完签名逻辑先跑一遍测试用例覆盖空值、中文、特殊字符、超长参数这几个边界再上环境验证。希望帮到你。本文还有配套的精品资源点击获取