说实话支付宝沙箱支付可以说是新手入门支付环节必走的一条路。我当年第一次跑通沙箱支付回调时踩了整整一个下午的坑基本都是配置项和异步通知签名验签的问题。现在把整套流程梳理成这篇Spring Boot整合支付宝沙箱测试的文章从准备环境到代码实现再到常见问题排查尽量把每一步“为什么要这么做”也讲清楚方便后面二开的同学少走弯路。1. 项目概述与整体设计思路1.1 这个项目要解决什么问题这篇文章的核心是带你完成一套完整的支付宝沙箱环境下的支付闭环包含创建订单、发起支付、异步通知接收、订单状态回写、主动查询、以及退款操作。沙箱环境是由支付宝提供的模拟测试环境接口逻辑和生产环境一致唯一不同是资金流是虚拟的你用测试买家账号付款钱不会真的扣订单也是模拟状态流转。很多人在学习支付时会先去翻官方文档结果发现文档内容分散在“电脑网站支付”“手机网站支付”“App支付”“小程序支付”等多个产品线里光对齐产品参数就要花不少时间。而整合进Spring Boot项目时还有几个容易纠缠的点支付宝SDK版本选择不统一不同版本的Request/Response对象变化很大。异步通知的参数校验和验签逻辑容易漏掉导致回调被伪造。本地联调时内网回调地址接收不到支付宝的通知需要借助内网穿透工具才能把公网请求转发到本机。沙箱的APPID、密钥和公钥配置和线上模式互相混淆跑到上线时才发现配错了环境。这个项目正是围绕这些问题展开的我会给出一个可以直接落地的方案而不是“仅仅能跑通Demo”的那种半吊子写法。读者最好有一点点Spring Boot基础比如知道Controller、Service、配置文件这些基本概念。完全零基础的话先补一下Spring MVC、Maven依赖管理这些前置知识再回来看效果会好一些。1.2 技术选型背后的考量支付方案选型上第一批要决定的是走官方SDK还是自己拼报文。很多人觉得SDK黑盒、不好排错想自己用HttpClient拼请求参数。我的建议是沙箱学习和项目落地阶段都用官方SDK理由有几点官方SDK负责了RSA2签名、请求参数编码、响应解析这些高频且容易出错的部分你手动拼一遍纯属重复造轮子。支付宝接口版本升级时SDK的兼容性维护比个人代码可靠得多尤其是证书模式和公钥模式的切换手写代码改动量很大。官方SDK在验签时会主动校验支付宝返回结果的签名这块逻辑自己写容易遗漏而遗漏等于给接口埋下一颗雷。当然SDK版本要选中长期维护的版本不要追最新也不要守着古董版本。我选的是com.alipay.sdk:alipay-sdk-java的最新稳定版搭配Spring Boot 2.7.x和JDK 8。这套组合在兼容性和稳定性上比较平衡社区资料多踩坑了也容易搜到解决方案。存储层我直接用了Spring Data JPA搭配H2内存库主要目的是把代码重心放在支付逻辑本身而不是被数据库表设计分散注意力。你要是项目里已经用了MySQL把application.yml里的数据源地址、账号密码和驱动改一下就可以跑起来表结构代码保持不变。1.3 项目目录结构预览我习惯把代码按功能模块划分避免所有类堆在同一个包下。下面是本文项目的目录结构src/main/java └── com.example.alipaydemo ├── AlipayDemoApplication.java ├── config │ └── AlipayConfig.java ├── controller │ ├── PayController.java │ └── NotifyController.java ├── service │ ├── AlipayService.java │ └── impl │ └── AlipayServiceImpl.java ├── repository │ └── OrderRepository.java ├── entity │ └── PayOrder.java ├── dto │ ├── PayRequest.java │ ├── PayResponse.java │ └── RefundRequest.java ├── constants │ └── PayStatus.java └── utils └── OrderNoGenerator.java src/main/resources ├── application.yml ├── alipay.properties这个结构下来新手一眼能看出来请求入口在哪里、业务逻辑在哪里、配置在哪里。最后跑测试的时候从Controller层往下打断点整个调用链路非常清晰。2. 沙箱环境准备与核心配置2.1 开通沙箱应用进入支付宝开放平台后台在“沙箱环境”应用列表里创建沙箱应用。创建完成后你会拿到三个关键信息APPID、应用私钥、支付宝公钥。注意这里的APPID是以沙箱专用段开头的字符串和线上应用的APPID完全不同。密钥生成这里要单独展开说。支付宝推荐使用RSA2签名算法也就是SHA256WithRSA。我们可以用支付宝提供的密钥生成工具也可以直接用openssl命令生成然后上传公钥到平台。我个人习惯用openssl因为能清楚看到密钥格式openssl genrsa -out app_private_key.pem 2048 openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem第一步生成2048位的RSA私钥第二步导出公钥第三步把私钥转换成PKCS8格式。Java环境中加载私钥时一般需要PKCS8格式否则解析时会报Invalid key format。之后把app_public_key.pem的内容上传到沙箱应用的“接口加签方式”中保存后平台会生成对应的支付宝公钥。这个支付宝公钥是平台端的公钥用来验证支付宝请求和响应的签名和我们自己的应用公钥不是同一个东西。这一点特别容易搞混很多人把这两个公钥填反了结果请求接口时一直报“签名验证失败”。2.2 配置文件里的关键项在application.yml之外我单独建了一个alipay.properties来放支付相关配置方便以后对接线上环境时区分开避免改代码。# 支付宝网关地址沙箱 alipay.gatewayhttps://openapi.alipaydev.com/gateway.do # 应用APPID alipay.app-id2021000123456789 # 应用私钥PKCS8格式注意换行转义 alipay.app-private-key你的应用私钥 # 支付宝公钥 alipay.alipay-public-key你的支付宝公钥 # 签名类型 alipay.sign-typeRSA2 # 支付成功异步通知地址 alipay.notify-urlhttps://your-domain.com/api/alipay/notify # 支付完成后的同步跳转页面地址 alipay.return-urlhttps://your-domain.com/#/pay-success # 销售产品码电脑网站支付固定为 QUICK_WAP_WAY alipay.product-codeQUICK_WAP_WAY网关地址是沙箱专用的openapi.alipaydev.com线上环境则是openapi.alipay.com这两个域名不一样。很多线上事故就是配置里忘了改网关地址导致沙箱请求发到线上白花花的银子被真实扣除。私钥里有换行符放在properties文件里容易出问题。简单起见配置类里加载时做一次字符串清洗把\\n还原成换行符并去掉多余空格这一步见下面的配置类代码。2.3 读取配置的配置类我把配置读取封装成一个AlipayConfig类用ConfigurationProperties注解绑定代码里随时可以注入。Component ConfigurationProperties(prefix alipay) public class AlipayConfig { private String gateway; private String appId; private String appPrivateKey; private String alipayPublicKey; private String signType; private String notifyUrl; private String returnUrl; private String productCode; // getter / setter 省略使用 Lombok Data 也行 public String getAppPrivateKey() { return appPrivateKey.replace(\\n, \n).replace(\\\\n, \n); } }这里有个小坑properties里如果写成alipay.app-private-key-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----Spring读取时反斜杠n会被当作普通字符还是转义字符取决于资源文件加载方式。我直接在getter里做了替换保证任何方式加载都能拿到正确的换行。这个方法有点土但非常可靠。3. 支付链路设计与订单表结构3.1 支付状态机设计设计订单状态时不要只设计一个“成功/失败”字段因为支付场景存在“等待付款”“已支付待处理”“已退款”“关闭”等多个中间状态。我定义了一个枚举类PayStatuspublic enum PayStatus { WAIT_PAY(0, 待支付), PAID(1, 已支付), REFUNDED(2, 已退款), CLOSED(3, 已关闭); private final int code; private final String desc; PayStatus(int code, String desc) { this.code code; this.desc desc; } public int getCode() { return code; } }在实际业务里“已支付”后可能还要经历发货、完成、评价这些流转但那些不属于支付模块我们只关注支付到退款这个闭环。把状态收敛到这四个可以让Demo足够简单又不失真实性。为什么要单独把“已关闭”抽出来因为在订单超时未支付、用户主动取消等场景下支付单需要落一个终态否则对账单时会出现一堆“既不成功也不失败”的悬挂数据。沙箱测试时不会真正发生超时关单但退款、关闭这些接口都可以模拟所以状态还是要留好。3.2 订单表和实体类订单表字段不需要多豪华抓住支付单的核心信息就行CREATE TABLE pay_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(64) NOT NULL UNIQUE, amount DECIMAL(10, 2) NOT NULL, subject VARCHAR(256), status TINYINT NOT NULL DEFAULT 0, alipay_trade_no VARCHAR(64), create_time DATETIME DEFAULT CURRENT_TIMESTAMP, pay_time DATETIME, notify_time DATETIME, refund_time DATETIME );order_no是商户系统自己的订单号要求全局唯一。alipay_trade_no是支付宝交易号支付成功后会回传对账时要靠它对应上支付宝那边的流水。实体类就按这个表字段映射Entity Table(name pay_order) public class PayOrder { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(name order_no, unique true) private String orderNo; private BigDecimal amount; private String subject; private Integer status; Column(name alipay_trade_no) private String alipayTradeNo; Column(name create_time) private LocalDateTime createTime; Column(name pay_time) private LocalDateTime payTime; Column(name notify_time) private LocalDateTime notifyTime; Column(name refund_time) private LocalDateTime refundTime; }订单号生成器我用的是“时间戳随机数”组合生产上建议用分布式ID但Demo够用了public class OrderNoGenerator { public static String generate() { return System.currentTimeMillis() String.format(%06d, ThreadLocalRandom.current().nextInt(1000000)); } }这个格式的订单号有20位左右保证短时间内不会重复。如果你自己测试时连续下单前13位时间戳是一样的但后6位随机数基本不会发生碰撞所以唯一性没问题。3.3 统一下单接口设计发起支付前Controller接收前端传来的金额、订单标题等参数先创建一条待支付订单然后调用支付宝SDK的alipay.trade.page.pay接口生成一个表单字符串返回给前端。PostMapping(/create) public Result createPayOrder(RequestBody PayRequest request) { String orderNo OrderNoGenerator.generate(); PayOrder order new PayOrder(); order.setOrderNo(orderNo); order.setAmount(request.getAmount()); order.setSubject(request.getSubject()); order.setStatus(PayStatus.WAIT_PAY.getCode()); order.setCreateTime(LocalDateTime.now()); orderRepository.save(order); String form alipayService.createPayForm(order); return Result.success(form); }这里有个设计取舍到底是前端传订单号还是后端自动生成我的建议是后端永远不要信任前端传来的订单号。订单号一旦被伪造支付回调时对不上账整个订单体系就乱了。所以无论业务侧把订单创建逻辑放在哪里支付模块都应该有自己的订单号生成规则并且和业务订单做绑定。4. 核心代码实现从发起支付到回调验签4.1 封装支付宝SDK客户端每次请求支付宝接口都需要构建一个AlipayClient实例。这个实例是线程安全的所以在配置类中直接声明为一个Bean整个Spring容器共用。Configuration public class AlipayClientConfig { Resource private AlipayConfig alipayConfig; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient( alipayConfig.getGateway(), alipayConfig.getAppId(), alipayConfig.getAppPrivateKey(), json, UTF-8, alipayConfig.getAlipayPublicKey(), alipayConfig.getSignType() ); } }构造参数里的“json”是请求格式支付宝目前支持xml和json现在主流都用json。编码必须写UTF-8否则回调验签时中文参数会因为编码不一致而乱掉导致签名比对失败。4.2 创建支付表单public String createPayForm(PayOrder order) { AlipayTradePagePayRequest request new AlipayTradePagePayRequest(); request.setNotifyUrl(alipayConfig.getNotifyUrl()); request.setReturnUrl(alipayConfig.getReturnUrl()); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, order.getOrderNo()); bizContent.put(total_amount, order.getAmount().toPlainString()); bizContent.put(subject, order.getSubject()); bizContent.put(product_code, alipayConfig.getProductCode()); request.setBizContent(bizContent.toJSONString()); try { AlipayTradePagePayResponse response alipayClient.pageExecute(request); if (response.isSuccess()) { return response.getBody(); } throw new RuntimeException(支付宝下单失败: response.getMsg()); } catch (AlipayApiException e) { throw new RuntimeException(支付宝下单异常, e); } }这段代码里bizContent通过JSONObject组装而不是直接拼字符串原因是避免字段顺序和空格影响签名。SDK签名时会对bizContent做特定处理如果手动拼接不规范会直接导致签名报错。使用JSONObject虽然多了一个依赖但安全系数高很多。返回的response.getBody()是一整段HTML表单里面包含了automatic自动提交的form表单前端可以直接用一个iframe或者新窗口加载。4.3 异步通知接收与验签异步通知是支付环节最容易出问题的地方。支付成功后支付宝会向notify_url发送一个POST请求携带订单号、交易号、支付金额、卖家ID等参数并且带有签名。我们必须在收到通知后先验签再校验业务参数最后更新订单状态。完整代码如下PostMapping(/notify) public String handleNotify(HttpServletRequest request) { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { String[] values requestParams.get(name); if (values.length 1) { params.put(name, String.join(,, values)); } else { params.put(name, values[0]); } } String tradeStatus params.get(trade_status); String outTradeNo params.get(out_trade_no); String alipayTradeNo params.get(trade_no); try { boolean signVerified AlipaySignature.rsaCheckV1(params, alipayConfig.getAlipayPublicKey(), UTF-8, alipayConfig.getSignType()); if (!signVerified) { log.warn(验证签名失败, params{}, params); return failure; } PayOrder order orderRepository.findByOrderNo(outTradeNo); if (order null) { log.error(订单不存在, outTradeNo{}, outTradeNo); return failure; } if (order.getStatus() PayStatus.PAID.getCode() alipayTradeNo.equals(order.getAlipayTradeNo())) { return success; } if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { boolean amountMatch order.getAmount() .compareTo(new BigDecimal(params.get(total_amount))) 0; if (!amountMatch) { log.error(通知金额不一致, orderNo{}, orderAmount{}, notifyAmount{}, outTradeNo, order.getAmount(), params.get(total_amount)); return failure; } order.setStatus(PayStatus.PAID.getCode()); order.setAlipayTradeNo(alipayTradeNo); order.setPayTime(LocalDateTime.now()); order.setNotifyTime(LocalDateTime.now()); orderRepository.save(order); log.info(订单支付成功回调, orderNo{}, tradeNo{}, outTradeNo, alipayTradeNo); return success; } return success; } catch (Exception e) { log.error(异步通知处理异常, e); return failure; } }有几个细节要特别强调第一验签不能放在try块外面。如果验签方法抛出异常比如参数缺失我们应该返回failure让支付宝后续重试通知而不是返回200。第二对重复通知的处理。支付宝会以一定时间间隔例如15秒、30秒、1分钟多次通知直到应用返回“success”。收到重复通知时不能直接再走一遍业务逻辑应该先判断订单状态是不是已经是PAID且alipayTradeNo相同直接返回success幂等处理。第三金额校验。回调里的total_amount能不能直接信任答案是不能。理论上支付宝签名通过后内容不会被篡改但业务数据的一致性必须由商户侧自己校验。比如有人篡改了前端下单金额导致商户订单金额是1分钱但实际付款是2分钱这种情况虽然签名是支付宝签的但业务上却是被攻击了。所以回调后必须把通知里的金额和本地订单金额做compareTo比对。第四TRADE_SUCCESS和TRADE_FINISHED的区别。TRADE_SUCCESS表示交易支付成功TRADE_FINISHED表示交易已完成且不能再退款。对于大多数业务两种状态都可以置为“已支付”但如果是允许售后退款的业务建议只在TRADE_SUCCESS时发已支付事件TRADE_FINISHED时可能代表超过退款期限了。4.4 同步跳转处理return_url是用户支付完成从支付宝页面跳转回商户页面的地址。这个跳转是浏览器行为不一定靠谱用户可能支付完成后直接关掉浏览器没跳回来。所以同步跳转只能做展示用绝对不能在这里更新订单状态。如果业务系统靠同步跳转来确认支付成功大概率会出现“用户付了钱系统没更新订单”的投诉。Controller层接收同步跳转返回的参数校验签名后把订单号传给前端由前端调后端接口查询最终结果。GetMapping(/return) public String returnUrl(HttpServletRequest request) { MapString, String params new HashMap(); request.getParameterMap().forEach((key, value) - params.put(key, value[0])); try { boolean signVerified AlipaySignature.rsaCheckV1(params, alipayConfig.getAlipayPublicKey(), UTF-8, alipayConfig.getSignType()); if (!signVerified) { return 签名校验失败; } String outTradeNo params.get(out_trade_no); return redirect:https://your-frontend.com/pay-result?orderNo outTradeNo; } catch (AlipayApiException e) { log.error(同步通知验签异常, e); return 系统异常; } }前端拿到orderNo以后应该再向后端发一个主动查询请求拿到确切的支付状态。这样即使页面刷新或者延迟也不会出现状态不一致的问题。4.5 主动查询订单状态主动查询接口是我们在异步通知偶发延迟或丢失情况下的兜底方案。接口如下public PayStatus queryOrder(String orderNo) { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); request.setBizContent(bizContent.toJSONString()); try { AlipayTradeQueryResponse response alipayClient.execute(request); if (response.isSuccess()) { String tradeStatus response.getTradeStatus(); if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { updateOrderPaid(orderNo, response.getTradeNo()); return PayStatus.PAID; } else if (WAIT_BUYER_PAY.equals(tradeStatus)) { return PayStatus.WAIT_PAY; } else if (TRADE_CLOSED.equals(tradeStatus)) { orderRepository.findByOrderNo(orderNo).ifPresent(order - { order.setStatus(PayStatus.CLOSED.getCode()); orderRepository.save(order); }); return PayStatus.CLOSED; } } throw new RuntimeException(查询失败: response.getSubMsg()); } catch (AlipayApiException e) { throw new RuntimeException(查询异常, e); } }这里要注意主动查询和异步通知都可能改变订单状态所以更新方法要保证幂等。实现幂等最简单的方法就是更新前先查一遍当前状态如果已经是PAID且支付流水号一致就直接返回。4.6 退款实现退款接口整体比支付接口简单一些。沙箱环境下可以频繁测试退款方便验证“已支付→已退款”的流转逻辑。public void refund(String orderNo, BigDecimal refundAmount, String refundReason) { AlipayTradeRefundRequest request new AlipayTradeRefundRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); bizContent.put(refund_amount, refundAmount.toPlainString()); bizContent.put(refund_reason, refundReason); bizContent.put(out_request_no, OrderNoGenerator.generate()); request.setBizContent(bizContent.toJSONString()); try { AlipayTradeRefundResponse response alipayClient.execute(request); if (!response.isSuccess()) { throw new RuntimeException(退款失败: response.getSubMsg()); } PayOrder order orderRepository.findByOrderNo(orderNo).orElseThrow( () - new RuntimeException(订单不存在)); order.setStatus(PayStatus.REFUNDED.getCode()); order.setRefundTime(LocalDateTime.now()); orderRepository.save(order); } catch (AlipayApiException e) { throw new RuntimeException(退款异常, e); } }out_request_no是退款请求号用于区分多次部分退款。如果同一订单发生多次退款每次退款请求号必须不同否则支付宝会认为请求重复。沙箱测试退款建议先做一次全额退款再做一次部分退款体验一下out_request_no的作用。5. 内网穿透与本地联调5.1 为什么要用内网穿透支付宝异步通知是支付宝服务器主动请求我们的notify_url。在本地开发时电脑通常在局域网内外网无法直接访问所以需要将本地服务暴露到公网让支付宝的回调请求能打到开发机上。有很多现成的内网穿透工具比如钩子、花生壳之类。我不在这里推荐具体品牌但可以提一下通用步骤映射本地服务端口假设Spring Boot启动在8080端口。工具会分配一个公网域名比如xxx.ngrok.free.com。把alipay.notify-url配置成http://xxx.ngrok.free.com/api/alipay/notify。在支付宝沙箱应用后台把“授权回调地址”也填成对应的地址。发起支付支付完成后观察工具控制台的请求记录。用内网穿透时有几个注意事项免费版域名经常变化每次重启工具后域名可能都不一样配置要同步更新。有些穿透工具会限制POST请求体大小而支付宝异步通知的参数并不算大一般不会超限但还是要留意日志里有没有请求中断。开发完成后记得把notify_url改回正式的服务器域名否则上线后回调打到一个不存在的地址支付单全卡在“待支付”状态。5.2 沙箱买家账号和支付操作在沙箱控制台里能看到系统提供的测试买家账号和登录密码。支付时在收银台选择“扫码支付”或“账号登录”然后使用测试买家账号完成付款。支付宝沙箱还有一个“沙箱钱包”App支持扫码体验功能和真实支付宝类似。不过测试时我一般直接用网页端登录测试买家账号更省事。付款完成后页面会跳转到商户的return_url同时后台可以观察异步通知是否到达。5.3 手动触发回调的调试技巧有时候内网穿透工具不稳定异步通知迟迟不来我们可以自己模拟一个通知请求。方式很简单从支付宝沙箱控制台的“交易记录”里找到刚才的订单复制支付宝返回的参数手动POST到本地的/api/alipay/notify接口。但要注意手工模拟的请求大概率验签不通过因为支付宝控制台展示的参数是明文没有重新签名。这种情况下可以在本地临时写一个跳过验签的notify接口专门用来调试业务逻辑等验签逻辑成型后再删掉。这个“跳过验签”的接口只留在开发环境千万别发布到生产。6. 常见问题与排查技巧实录6.1 高频报错一览我把沙箱整合过程中最容易踩的坑整理成了一张速查表大家可以直接对照异常现象根因解决方案签名验证失败应用私钥、支付宝公钥配置错误或把应用公钥当支付宝公钥重新核对密钥配置确认私钥为PKCS8格式公钥为平台上获取的支付宝公钥报错“code is invalid”APPID传错或沙箱环境配置成线上检查配置文件的app_id是否来自沙箱控制台报“Product code is invalid”product_code参数值不对文档和产品线不匹配电脑网站支付填QUICK_WAP_WAY手机网站支付填QUICK_WAP_WAY不同产品线需区分异步通知一直收不到内网穿透失效、notify_url填错、防火墙拦截检查穿透工具日志确认外网URL能访问到本机接口订单状态一直待支付异步通知处理失败返回了非success查看应用日志确认验签是否通过、订单是否存在中文乱码编码格式不统一部分参数出现UTF-8转GBK请求统一使用UTF-8配置里确认Tomcat URI编码为UTF-8金额对不上前端修改金额后端未校验回调时对金额做compareTo比对不匹配直接拒绝6.2 验签失败的定位思路验签失败是排查成本最高的一个问题因为现象单一但根因可能分散在多处。我的排查顺序是这样的打印收到的参数集合看签名参数sign是否存在且参数中是否包含它。rsaCheckV1在验签时会自动剔除sign和sign_type如果你手动拼参数时把sign也拼进去很容易出错。确认alipay_public_key是不是支付宝公钥不是应用公钥也不是应用私钥。这三个最容易搞混。确认私钥换行是否被吃掉。很多配置读取工具会把\n当成普通字符处理导致私钥变成一行格式错误。此时解密出来的签名值会乱掉。确认时间戳是否同步。服务器时间如果和真实时间差太多签名也会有一定影响但支付宝验签主要看签名算法本身时间偏差的影响相对小。不过还是建议服务器开启时间同步。6.3 回调解密与日志打印调试异步通知时最忌讳的就是只打日志摘要不打全量参数。因为签名参数可能在你打摘要时已经被过滤掉了看不到全貌就定位不到问题。我建议在验签之前先加一行全量参数日志级别设为DEBUG生产环境默认不输出开发环境方便调试。log.debug(支付宝异步通知参数: {}, JSON.toJSONString(params));这里还有个经验之谈支付宝异步通知的sign参数放在URL参数里而biz_content等字段放在POST body里。当你从request.getParameterMap()获取参数时Spring容器解析POST表单会自动合并这没问题。但如果正好用了RequestBody去接那会直接爆炸因为支付宝发的是application/x-www-form-urlencoded格式不是JSON。6.4 沙箱与线上环境切换的优雅方案Demo里我直接把配置文件写成固定环境但真实项目开发中最好通过Spring Profile来切换沙箱和线上配置。spring: profiles: active: dev然后在resources下放两个配置文件application-dev.yml使用沙箱gateway、沙箱APPID、沙箱密钥。application-prod.yml使用线上gateway、线上APPID、线上密钥。这样本地开发用dev上线打包用prod密钥不会混在一起排查问题也方便。上线前运维只需要检查prod配置里的网关和APPID是不是线上值就能避免踩“沙箱配置发布到生产”的大坑。7. 项目安全性与扩展方向7.1 支付接口防重与幂等支付接口和回调接口其实都涉及幂等。发起支付时同一个业务订单不应该能重复创建支付单否则用户可能发起两笔支付导致重复扣款。简单做法是业务订单表和支付单表建立唯一约束或者支付单创建前先查一遍是否存在未关闭的待支付单。回调接口的幂等在前面已经提到过核心就是状态判断加交易号判断。已支付并且交易号一致时直接返回成功不再走一遍业务逻辑。退款接口同样需要幂等。已经退款成功的订单不能再次发起全额退款否则会报“退款金额超过可退金额”。部分退款场景则要累加已退款金额并且在退款前判断剩余可退余额。7.2 对账与订单归档沙箱测试阶段不需要考虑对账但真实上线后这个问题很重要。支付宝开放平台提供了“账单下载”接口可以下载日账单文件商户需要拿着日账单和自己库里交易成功的订单做比对找出差异单。对账逻辑通常分三步拉取支付宝日账单文件解析出交易号、金额、状态。与本地当日支付成功的订单做比对。差异部分走人工复核比如本地有单但支付宝没有可能是异步通知漏了主动查询一次支付宝有但本地没有可能是订单创建后没有发起支付成功回调需要手工补单。这些逻辑虽然不属于Demo闭环的必修课但既然做支付就该从第一天养成对账意识。7.3 拦截器与统一日志支付模块涉及金额和敏感操作建议给所有支付相关Controller加上统一拦截器记录用户IP、请求路径、请求参数、响应体、耗时等。沙箱测试时可能觉得日志啰嗦但万一线上发生资损问题没有日志基本无法定位。统一日志框架推荐用Slf4j配合拦截器在preHandle记录入参在afterCompletion记录耗时和异常。如果公司有全链路追踪系统可以Span ID一并打进去排障效率会高很多。7.4 从沙箱走向线上前必须做的事很多同学跑通沙箱Demo后觉得万事大吉实际上线前有一堆收尾工作要做申请线上应用拿到线上的APPID和密钥配置到prod环境。把网关地址从沙箱域名切到线上域名。配置线上应用的接口加签方式重新上传应用公钥获取新的支付宝公钥。把notify_url改成正式环境域名并确保该URL支持HTTPS。支付宝对线上回调地址有HTTPS要求。在开放平台后台配置应用功能权限支付相关产品需要签约开通不是申请完应用就能直接用。线上支付回调验签失败时会触发支付宝的重试机制重试几次后停止。此时务必人工介入避免丢单。8. 实操总结与我的个人建议这套Spring Boot整合支付宝沙箱测试的Demo从下单到支付再到回调、查询、退款基本覆盖了支付闭环的全部核心节点。代码量不大但每一步背后的设计都有讲究验签和金额校验是安全底线幂等和状态机是数据一致性保障日志和主动查询是排查问题的基础。说几个我实际操作中的体会第一支付模块的坑百分之六十发生在配置上而不是代码上。网关、APPID、密钥、回调地址这四个配置项只要错一个整个链路都转不起来。调试时我会先把配置打印到日志里确认它们和沙箱控制台一致再开始排查代码。第二异步通知是整个支付链路里最值得花时间打磨的环节。线下联调时把内网穿透配好让支付宝真实回调几次比手动模拟岔子少很多。回调处理函数里日志要打全异常要捕获完整不要用空catch吞掉真正的问题。第三支付宝沙箱虽然模拟了核心流程但毕竟不是线上环境异步通知的频率和稳定性可能和线上有差异。测试时如果发现回调一直不来先别怀疑代码看看穿透工具是否失效URL是否能公网访问。很多时候我以为是自己代码Bug排查半天最后发现是工具连接断开了。第四这个Demo如果你想进一步扩展可以考虑接入支付宝的“资金授权”“花呗分期”“预授权完成”等更高级的产品也可以把支付能力抽成独立的微服务通过消息队列把支付结果发给业务方还可以在回调里集成库存扣减、会员积分等下游业务。但无论扩展方向是什么支付的四个基本动作——下单、支付、回调、退款——始终是核心先把这四个动作吃透后续的功能都是锦上添花。按这个项目实践一遍从零到跑通完整支付闭环一整天时间基本够用。后面如果有什么新问题欢迎在实际操作中多翻日志、多打断点支付这块代码不怕改就怕不敢调试。祝早日跑通沙箱顺利上线。
说实话支付宝沙箱支付可以说是新手入门支付环节必走的一条路。我当年第一次跑通沙箱支付回调时踩了整整一个下午的坑基本都是配置项和异步通知签名验签的问题。现在把整套流程梳理成这篇Spring Boot整合支付宝沙箱测试的文章从准备环境到代码实现再到常见问题排查尽量把每一步“为什么要这么做”也讲清楚方便后面二开的同学少走弯路。1. 项目概述与整体设计思路1.1 这个项目要解决什么问题这篇文章的核心是带你完成一套完整的支付宝沙箱环境下的支付闭环包含创建订单、发起支付、异步通知接收、订单状态回写、主动查询、以及退款操作。沙箱环境是由支付宝提供的模拟测试环境接口逻辑和生产环境一致唯一不同是资金流是虚拟的你用测试买家账号付款钱不会真的扣订单也是模拟状态流转。很多人在学习支付时会先去翻官方文档结果发现文档内容分散在“电脑网站支付”“手机网站支付”“App支付”“小程序支付”等多个产品线里光对齐产品参数就要花不少时间。而整合进Spring Boot项目时还有几个容易纠缠的点支付宝SDK版本选择不统一不同版本的Request/Response对象变化很大。异步通知的参数校验和验签逻辑容易漏掉导致回调被伪造。本地联调时内网回调地址接收不到支付宝的通知需要借助内网穿透工具才能把公网请求转发到本机。沙箱的APPID、密钥和公钥配置和线上模式互相混淆跑到上线时才发现配错了环境。这个项目正是围绕这些问题展开的我会给出一个可以直接落地的方案而不是“仅仅能跑通Demo”的那种半吊子写法。读者最好有一点点Spring Boot基础比如知道Controller、Service、配置文件这些基本概念。完全零基础的话先补一下Spring MVC、Maven依赖管理这些前置知识再回来看效果会好一些。1.2 技术选型背后的考量支付方案选型上第一批要决定的是走官方SDK还是自己拼报文。很多人觉得SDK黑盒、不好排错想自己用HttpClient拼请求参数。我的建议是沙箱学习和项目落地阶段都用官方SDK理由有几点官方SDK负责了RSA2签名、请求参数编码、响应解析这些高频且容易出错的部分你手动拼一遍纯属重复造轮子。支付宝接口版本升级时SDK的兼容性维护比个人代码可靠得多尤其是证书模式和公钥模式的切换手写代码改动量很大。官方SDK在验签时会主动校验支付宝返回结果的签名这块逻辑自己写容易遗漏而遗漏等于给接口埋下一颗雷。当然SDK版本要选中长期维护的版本不要追最新也不要守着古董版本。我选的是com.alipay.sdk:alipay-sdk-java的最新稳定版搭配Spring Boot 2.7.x和JDK 8。这套组合在兼容性和稳定性上比较平衡社区资料多踩坑了也容易搜到解决方案。存储层我直接用了Spring Data JPA搭配H2内存库主要目的是把代码重心放在支付逻辑本身而不是被数据库表设计分散注意力。你要是项目里已经用了MySQL把application.yml里的数据源地址、账号密码和驱动改一下就可以跑起来表结构代码保持不变。1.3 项目目录结构预览我习惯把代码按功能模块划分避免所有类堆在同一个包下。下面是本文项目的目录结构src/main/java └── com.example.alipaydemo ├── AlipayDemoApplication.java ├── config │ └── AlipayConfig.java ├── controller │ ├── PayController.java │ └── NotifyController.java ├── service │ ├── AlipayService.java │ └── impl │ └── AlipayServiceImpl.java ├── repository │ └── OrderRepository.java ├── entity │ └── PayOrder.java ├── dto │ ├── PayRequest.java │ ├── PayResponse.java │ └── RefundRequest.java ├── constants │ └── PayStatus.java └── utils └── OrderNoGenerator.java src/main/resources ├── application.yml ├── alipay.properties这个结构下来新手一眼能看出来请求入口在哪里、业务逻辑在哪里、配置在哪里。最后跑测试的时候从Controller层往下打断点整个调用链路非常清晰。2. 沙箱环境准备与核心配置2.1 开通沙箱应用进入支付宝开放平台后台在“沙箱环境”应用列表里创建沙箱应用。创建完成后你会拿到三个关键信息APPID、应用私钥、支付宝公钥。注意这里的APPID是以沙箱专用段开头的字符串和线上应用的APPID完全不同。密钥生成这里要单独展开说。支付宝推荐使用RSA2签名算法也就是SHA256WithRSA。我们可以用支付宝提供的密钥生成工具也可以直接用openssl命令生成然后上传公钥到平台。我个人习惯用openssl因为能清楚看到密钥格式openssl genrsa -out app_private_key.pem 2048 openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem第一步生成2048位的RSA私钥第二步导出公钥第三步把私钥转换成PKCS8格式。Java环境中加载私钥时一般需要PKCS8格式否则解析时会报Invalid key format。之后把app_public_key.pem的内容上传到沙箱应用的“接口加签方式”中保存后平台会生成对应的支付宝公钥。这个支付宝公钥是平台端的公钥用来验证支付宝请求和响应的签名和我们自己的应用公钥不是同一个东西。这一点特别容易搞混很多人把这两个公钥填反了结果请求接口时一直报“签名验证失败”。2.2 配置文件里的关键项在application.yml之外我单独建了一个alipay.properties来放支付相关配置方便以后对接线上环境时区分开避免改代码。# 支付宝网关地址沙箱 alipay.gatewayhttps://openapi.alipaydev.com/gateway.do # 应用APPID alipay.app-id2021000123456789 # 应用私钥PKCS8格式注意换行转义 alipay.app-private-key你的应用私钥 # 支付宝公钥 alipay.alipay-public-key你的支付宝公钥 # 签名类型 alipay.sign-typeRSA2 # 支付成功异步通知地址 alipay.notify-urlhttps://your-domain.com/api/alipay/notify # 支付完成后的同步跳转页面地址 alipay.return-urlhttps://your-domain.com/#/pay-success # 销售产品码电脑网站支付固定为 QUICK_WAP_WAY alipay.product-codeQUICK_WAP_WAY网关地址是沙箱专用的openapi.alipaydev.com线上环境则是openapi.alipay.com这两个域名不一样。很多线上事故就是配置里忘了改网关地址导致沙箱请求发到线上白花花的银子被真实扣除。私钥里有换行符放在properties文件里容易出问题。简单起见配置类里加载时做一次字符串清洗把\\n还原成换行符并去掉多余空格这一步见下面的配置类代码。2.3 读取配置的配置类我把配置读取封装成一个AlipayConfig类用ConfigurationProperties注解绑定代码里随时可以注入。Component ConfigurationProperties(prefix alipay) public class AlipayConfig { private String gateway; private String appId; private String appPrivateKey; private String alipayPublicKey; private String signType; private String notifyUrl; private String returnUrl; private String productCode; // getter / setter 省略使用 Lombok Data 也行 public String getAppPrivateKey() { return appPrivateKey.replace(\\n, \n).replace(\\\\n, \n); } }这里有个小坑properties里如果写成alipay.app-private-key-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----Spring读取时反斜杠n会被当作普通字符还是转义字符取决于资源文件加载方式。我直接在getter里做了替换保证任何方式加载都能拿到正确的换行。这个方法有点土但非常可靠。3. 支付链路设计与订单表结构3.1 支付状态机设计设计订单状态时不要只设计一个“成功/失败”字段因为支付场景存在“等待付款”“已支付待处理”“已退款”“关闭”等多个中间状态。我定义了一个枚举类PayStatuspublic enum PayStatus { WAIT_PAY(0, 待支付), PAID(1, 已支付), REFUNDED(2, 已退款), CLOSED(3, 已关闭); private final int code; private final String desc; PayStatus(int code, String desc) { this.code code; this.desc desc; } public int getCode() { return code; } }在实际业务里“已支付”后可能还要经历发货、完成、评价这些流转但那些不属于支付模块我们只关注支付到退款这个闭环。把状态收敛到这四个可以让Demo足够简单又不失真实性。为什么要单独把“已关闭”抽出来因为在订单超时未支付、用户主动取消等场景下支付单需要落一个终态否则对账单时会出现一堆“既不成功也不失败”的悬挂数据。沙箱测试时不会真正发生超时关单但退款、关闭这些接口都可以模拟所以状态还是要留好。3.2 订单表和实体类订单表字段不需要多豪华抓住支付单的核心信息就行CREATE TABLE pay_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(64) NOT NULL UNIQUE, amount DECIMAL(10, 2) NOT NULL, subject VARCHAR(256), status TINYINT NOT NULL DEFAULT 0, alipay_trade_no VARCHAR(64), create_time DATETIME DEFAULT CURRENT_TIMESTAMP, pay_time DATETIME, notify_time DATETIME, refund_time DATETIME );order_no是商户系统自己的订单号要求全局唯一。alipay_trade_no是支付宝交易号支付成功后会回传对账时要靠它对应上支付宝那边的流水。实体类就按这个表字段映射Entity Table(name pay_order) public class PayOrder { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(name order_no, unique true) private String orderNo; private BigDecimal amount; private String subject; private Integer status; Column(name alipay_trade_no) private String alipayTradeNo; Column(name create_time) private LocalDateTime createTime; Column(name pay_time) private LocalDateTime payTime; Column(name notify_time) private LocalDateTime notifyTime; Column(name refund_time) private LocalDateTime refundTime; }订单号生成器我用的是“时间戳随机数”组合生产上建议用分布式ID但Demo够用了public class OrderNoGenerator { public static String generate() { return System.currentTimeMillis() String.format(%06d, ThreadLocalRandom.current().nextInt(1000000)); } }这个格式的订单号有20位左右保证短时间内不会重复。如果你自己测试时连续下单前13位时间戳是一样的但后6位随机数基本不会发生碰撞所以唯一性没问题。3.3 统一下单接口设计发起支付前Controller接收前端传来的金额、订单标题等参数先创建一条待支付订单然后调用支付宝SDK的alipay.trade.page.pay接口生成一个表单字符串返回给前端。PostMapping(/create) public Result createPayOrder(RequestBody PayRequest request) { String orderNo OrderNoGenerator.generate(); PayOrder order new PayOrder(); order.setOrderNo(orderNo); order.setAmount(request.getAmount()); order.setSubject(request.getSubject()); order.setStatus(PayStatus.WAIT_PAY.getCode()); order.setCreateTime(LocalDateTime.now()); orderRepository.save(order); String form alipayService.createPayForm(order); return Result.success(form); }这里有个设计取舍到底是前端传订单号还是后端自动生成我的建议是后端永远不要信任前端传来的订单号。订单号一旦被伪造支付回调时对不上账整个订单体系就乱了。所以无论业务侧把订单创建逻辑放在哪里支付模块都应该有自己的订单号生成规则并且和业务订单做绑定。4. 核心代码实现从发起支付到回调验签4.1 封装支付宝SDK客户端每次请求支付宝接口都需要构建一个AlipayClient实例。这个实例是线程安全的所以在配置类中直接声明为一个Bean整个Spring容器共用。Configuration public class AlipayClientConfig { Resource private AlipayConfig alipayConfig; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient( alipayConfig.getGateway(), alipayConfig.getAppId(), alipayConfig.getAppPrivateKey(), json, UTF-8, alipayConfig.getAlipayPublicKey(), alipayConfig.getSignType() ); } }构造参数里的“json”是请求格式支付宝目前支持xml和json现在主流都用json。编码必须写UTF-8否则回调验签时中文参数会因为编码不一致而乱掉导致签名比对失败。4.2 创建支付表单public String createPayForm(PayOrder order) { AlipayTradePagePayRequest request new AlipayTradePagePayRequest(); request.setNotifyUrl(alipayConfig.getNotifyUrl()); request.setReturnUrl(alipayConfig.getReturnUrl()); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, order.getOrderNo()); bizContent.put(total_amount, order.getAmount().toPlainString()); bizContent.put(subject, order.getSubject()); bizContent.put(product_code, alipayConfig.getProductCode()); request.setBizContent(bizContent.toJSONString()); try { AlipayTradePagePayResponse response alipayClient.pageExecute(request); if (response.isSuccess()) { return response.getBody(); } throw new RuntimeException(支付宝下单失败: response.getMsg()); } catch (AlipayApiException e) { throw new RuntimeException(支付宝下单异常, e); } }这段代码里bizContent通过JSONObject组装而不是直接拼字符串原因是避免字段顺序和空格影响签名。SDK签名时会对bizContent做特定处理如果手动拼接不规范会直接导致签名报错。使用JSONObject虽然多了一个依赖但安全系数高很多。返回的response.getBody()是一整段HTML表单里面包含了automatic自动提交的form表单前端可以直接用一个iframe或者新窗口加载。4.3 异步通知接收与验签异步通知是支付环节最容易出问题的地方。支付成功后支付宝会向notify_url发送一个POST请求携带订单号、交易号、支付金额、卖家ID等参数并且带有签名。我们必须在收到通知后先验签再校验业务参数最后更新订单状态。完整代码如下PostMapping(/notify) public String handleNotify(HttpServletRequest request) { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { String[] values requestParams.get(name); if (values.length 1) { params.put(name, String.join(,, values)); } else { params.put(name, values[0]); } } String tradeStatus params.get(trade_status); String outTradeNo params.get(out_trade_no); String alipayTradeNo params.get(trade_no); try { boolean signVerified AlipaySignature.rsaCheckV1(params, alipayConfig.getAlipayPublicKey(), UTF-8, alipayConfig.getSignType()); if (!signVerified) { log.warn(验证签名失败, params{}, params); return failure; } PayOrder order orderRepository.findByOrderNo(outTradeNo); if (order null) { log.error(订单不存在, outTradeNo{}, outTradeNo); return failure; } if (order.getStatus() PayStatus.PAID.getCode() alipayTradeNo.equals(order.getAlipayTradeNo())) { return success; } if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { boolean amountMatch order.getAmount() .compareTo(new BigDecimal(params.get(total_amount))) 0; if (!amountMatch) { log.error(通知金额不一致, orderNo{}, orderAmount{}, notifyAmount{}, outTradeNo, order.getAmount(), params.get(total_amount)); return failure; } order.setStatus(PayStatus.PAID.getCode()); order.setAlipayTradeNo(alipayTradeNo); order.setPayTime(LocalDateTime.now()); order.setNotifyTime(LocalDateTime.now()); orderRepository.save(order); log.info(订单支付成功回调, orderNo{}, tradeNo{}, outTradeNo, alipayTradeNo); return success; } return success; } catch (Exception e) { log.error(异步通知处理异常, e); return failure; } }有几个细节要特别强调第一验签不能放在try块外面。如果验签方法抛出异常比如参数缺失我们应该返回failure让支付宝后续重试通知而不是返回200。第二对重复通知的处理。支付宝会以一定时间间隔例如15秒、30秒、1分钟多次通知直到应用返回“success”。收到重复通知时不能直接再走一遍业务逻辑应该先判断订单状态是不是已经是PAID且alipayTradeNo相同直接返回success幂等处理。第三金额校验。回调里的total_amount能不能直接信任答案是不能。理论上支付宝签名通过后内容不会被篡改但业务数据的一致性必须由商户侧自己校验。比如有人篡改了前端下单金额导致商户订单金额是1分钱但实际付款是2分钱这种情况虽然签名是支付宝签的但业务上却是被攻击了。所以回调后必须把通知里的金额和本地订单金额做compareTo比对。第四TRADE_SUCCESS和TRADE_FINISHED的区别。TRADE_SUCCESS表示交易支付成功TRADE_FINISHED表示交易已完成且不能再退款。对于大多数业务两种状态都可以置为“已支付”但如果是允许售后退款的业务建议只在TRADE_SUCCESS时发已支付事件TRADE_FINISHED时可能代表超过退款期限了。4.4 同步跳转处理return_url是用户支付完成从支付宝页面跳转回商户页面的地址。这个跳转是浏览器行为不一定靠谱用户可能支付完成后直接关掉浏览器没跳回来。所以同步跳转只能做展示用绝对不能在这里更新订单状态。如果业务系统靠同步跳转来确认支付成功大概率会出现“用户付了钱系统没更新订单”的投诉。Controller层接收同步跳转返回的参数校验签名后把订单号传给前端由前端调后端接口查询最终结果。GetMapping(/return) public String returnUrl(HttpServletRequest request) { MapString, String params new HashMap(); request.getParameterMap().forEach((key, value) - params.put(key, value[0])); try { boolean signVerified AlipaySignature.rsaCheckV1(params, alipayConfig.getAlipayPublicKey(), UTF-8, alipayConfig.getSignType()); if (!signVerified) { return 签名校验失败; } String outTradeNo params.get(out_trade_no); return redirect:https://your-frontend.com/pay-result?orderNo outTradeNo; } catch (AlipayApiException e) { log.error(同步通知验签异常, e); return 系统异常; } }前端拿到orderNo以后应该再向后端发一个主动查询请求拿到确切的支付状态。这样即使页面刷新或者延迟也不会出现状态不一致的问题。4.5 主动查询订单状态主动查询接口是我们在异步通知偶发延迟或丢失情况下的兜底方案。接口如下public PayStatus queryOrder(String orderNo) { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); request.setBizContent(bizContent.toJSONString()); try { AlipayTradeQueryResponse response alipayClient.execute(request); if (response.isSuccess()) { String tradeStatus response.getTradeStatus(); if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { updateOrderPaid(orderNo, response.getTradeNo()); return PayStatus.PAID; } else if (WAIT_BUYER_PAY.equals(tradeStatus)) { return PayStatus.WAIT_PAY; } else if (TRADE_CLOSED.equals(tradeStatus)) { orderRepository.findByOrderNo(orderNo).ifPresent(order - { order.setStatus(PayStatus.CLOSED.getCode()); orderRepository.save(order); }); return PayStatus.CLOSED; } } throw new RuntimeException(查询失败: response.getSubMsg()); } catch (AlipayApiException e) { throw new RuntimeException(查询异常, e); } }这里要注意主动查询和异步通知都可能改变订单状态所以更新方法要保证幂等。实现幂等最简单的方法就是更新前先查一遍当前状态如果已经是PAID且支付流水号一致就直接返回。4.6 退款实现退款接口整体比支付接口简单一些。沙箱环境下可以频繁测试退款方便验证“已支付→已退款”的流转逻辑。public void refund(String orderNo, BigDecimal refundAmount, String refundReason) { AlipayTradeRefundRequest request new AlipayTradeRefundRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); bizContent.put(refund_amount, refundAmount.toPlainString()); bizContent.put(refund_reason, refundReason); bizContent.put(out_request_no, OrderNoGenerator.generate()); request.setBizContent(bizContent.toJSONString()); try { AlipayTradeRefundResponse response alipayClient.execute(request); if (!response.isSuccess()) { throw new RuntimeException(退款失败: response.getSubMsg()); } PayOrder order orderRepository.findByOrderNo(orderNo).orElseThrow( () - new RuntimeException(订单不存在)); order.setStatus(PayStatus.REFUNDED.getCode()); order.setRefundTime(LocalDateTime.now()); orderRepository.save(order); } catch (AlipayApiException e) { throw new RuntimeException(退款异常, e); } }out_request_no是退款请求号用于区分多次部分退款。如果同一订单发生多次退款每次退款请求号必须不同否则支付宝会认为请求重复。沙箱测试退款建议先做一次全额退款再做一次部分退款体验一下out_request_no的作用。5. 内网穿透与本地联调5.1 为什么要用内网穿透支付宝异步通知是支付宝服务器主动请求我们的notify_url。在本地开发时电脑通常在局域网内外网无法直接访问所以需要将本地服务暴露到公网让支付宝的回调请求能打到开发机上。有很多现成的内网穿透工具比如钩子、花生壳之类。我不在这里推荐具体品牌但可以提一下通用步骤映射本地服务端口假设Spring Boot启动在8080端口。工具会分配一个公网域名比如xxx.ngrok.free.com。把alipay.notify-url配置成http://xxx.ngrok.free.com/api/alipay/notify。在支付宝沙箱应用后台把“授权回调地址”也填成对应的地址。发起支付支付完成后观察工具控制台的请求记录。用内网穿透时有几个注意事项免费版域名经常变化每次重启工具后域名可能都不一样配置要同步更新。有些穿透工具会限制POST请求体大小而支付宝异步通知的参数并不算大一般不会超限但还是要留意日志里有没有请求中断。开发完成后记得把notify_url改回正式的服务器域名否则上线后回调打到一个不存在的地址支付单全卡在“待支付”状态。5.2 沙箱买家账号和支付操作在沙箱控制台里能看到系统提供的测试买家账号和登录密码。支付时在收银台选择“扫码支付”或“账号登录”然后使用测试买家账号完成付款。支付宝沙箱还有一个“沙箱钱包”App支持扫码体验功能和真实支付宝类似。不过测试时我一般直接用网页端登录测试买家账号更省事。付款完成后页面会跳转到商户的return_url同时后台可以观察异步通知是否到达。5.3 手动触发回调的调试技巧有时候内网穿透工具不稳定异步通知迟迟不来我们可以自己模拟一个通知请求。方式很简单从支付宝沙箱控制台的“交易记录”里找到刚才的订单复制支付宝返回的参数手动POST到本地的/api/alipay/notify接口。但要注意手工模拟的请求大概率验签不通过因为支付宝控制台展示的参数是明文没有重新签名。这种情况下可以在本地临时写一个跳过验签的notify接口专门用来调试业务逻辑等验签逻辑成型后再删掉。这个“跳过验签”的接口只留在开发环境千万别发布到生产。6. 常见问题与排查技巧实录6.1 高频报错一览我把沙箱整合过程中最容易踩的坑整理成了一张速查表大家可以直接对照异常现象根因解决方案签名验证失败应用私钥、支付宝公钥配置错误或把应用公钥当支付宝公钥重新核对密钥配置确认私钥为PKCS8格式公钥为平台上获取的支付宝公钥报错“code is invalid”APPID传错或沙箱环境配置成线上检查配置文件的app_id是否来自沙箱控制台报“Product code is invalid”product_code参数值不对文档和产品线不匹配电脑网站支付填QUICK_WAP_WAY手机网站支付填QUICK_WAP_WAY不同产品线需区分异步通知一直收不到内网穿透失效、notify_url填错、防火墙拦截检查穿透工具日志确认外网URL能访问到本机接口订单状态一直待支付异步通知处理失败返回了非success查看应用日志确认验签是否通过、订单是否存在中文乱码编码格式不统一部分参数出现UTF-8转GBK请求统一使用UTF-8配置里确认Tomcat URI编码为UTF-8金额对不上前端修改金额后端未校验回调时对金额做compareTo比对不匹配直接拒绝6.2 验签失败的定位思路验签失败是排查成本最高的一个问题因为现象单一但根因可能分散在多处。我的排查顺序是这样的打印收到的参数集合看签名参数sign是否存在且参数中是否包含它。rsaCheckV1在验签时会自动剔除sign和sign_type如果你手动拼参数时把sign也拼进去很容易出错。确认alipay_public_key是不是支付宝公钥不是应用公钥也不是应用私钥。这三个最容易搞混。确认私钥换行是否被吃掉。很多配置读取工具会把\n当成普通字符处理导致私钥变成一行格式错误。此时解密出来的签名值会乱掉。确认时间戳是否同步。服务器时间如果和真实时间差太多签名也会有一定影响但支付宝验签主要看签名算法本身时间偏差的影响相对小。不过还是建议服务器开启时间同步。6.3 回调解密与日志打印调试异步通知时最忌讳的就是只打日志摘要不打全量参数。因为签名参数可能在你打摘要时已经被过滤掉了看不到全貌就定位不到问题。我建议在验签之前先加一行全量参数日志级别设为DEBUG生产环境默认不输出开发环境方便调试。log.debug(支付宝异步通知参数: {}, JSON.toJSONString(params));这里还有个经验之谈支付宝异步通知的sign参数放在URL参数里而biz_content等字段放在POST body里。当你从request.getParameterMap()获取参数时Spring容器解析POST表单会自动合并这没问题。但如果正好用了RequestBody去接那会直接爆炸因为支付宝发的是application/x-www-form-urlencoded格式不是JSON。6.4 沙箱与线上环境切换的优雅方案Demo里我直接把配置文件写成固定环境但真实项目开发中最好通过Spring Profile来切换沙箱和线上配置。spring: profiles: active: dev然后在resources下放两个配置文件application-dev.yml使用沙箱gateway、沙箱APPID、沙箱密钥。application-prod.yml使用线上gateway、线上APPID、线上密钥。这样本地开发用dev上线打包用prod密钥不会混在一起排查问题也方便。上线前运维只需要检查prod配置里的网关和APPID是不是线上值就能避免踩“沙箱配置发布到生产”的大坑。7. 项目安全性与扩展方向7.1 支付接口防重与幂等支付接口和回调接口其实都涉及幂等。发起支付时同一个业务订单不应该能重复创建支付单否则用户可能发起两笔支付导致重复扣款。简单做法是业务订单表和支付单表建立唯一约束或者支付单创建前先查一遍是否存在未关闭的待支付单。回调接口的幂等在前面已经提到过核心就是状态判断加交易号判断。已支付并且交易号一致时直接返回成功不再走一遍业务逻辑。退款接口同样需要幂等。已经退款成功的订单不能再次发起全额退款否则会报“退款金额超过可退金额”。部分退款场景则要累加已退款金额并且在退款前判断剩余可退余额。7.2 对账与订单归档沙箱测试阶段不需要考虑对账但真实上线后这个问题很重要。支付宝开放平台提供了“账单下载”接口可以下载日账单文件商户需要拿着日账单和自己库里交易成功的订单做比对找出差异单。对账逻辑通常分三步拉取支付宝日账单文件解析出交易号、金额、状态。与本地当日支付成功的订单做比对。差异部分走人工复核比如本地有单但支付宝没有可能是异步通知漏了主动查询一次支付宝有但本地没有可能是订单创建后没有发起支付成功回调需要手工补单。这些逻辑虽然不属于Demo闭环的必修课但既然做支付就该从第一天养成对账意识。7.3 拦截器与统一日志支付模块涉及金额和敏感操作建议给所有支付相关Controller加上统一拦截器记录用户IP、请求路径、请求参数、响应体、耗时等。沙箱测试时可能觉得日志啰嗦但万一线上发生资损问题没有日志基本无法定位。统一日志框架推荐用Slf4j配合拦截器在preHandle记录入参在afterCompletion记录耗时和异常。如果公司有全链路追踪系统可以Span ID一并打进去排障效率会高很多。7.4 从沙箱走向线上前必须做的事很多同学跑通沙箱Demo后觉得万事大吉实际上线前有一堆收尾工作要做申请线上应用拿到线上的APPID和密钥配置到prod环境。把网关地址从沙箱域名切到线上域名。配置线上应用的接口加签方式重新上传应用公钥获取新的支付宝公钥。把notify_url改成正式环境域名并确保该URL支持HTTPS。支付宝对线上回调地址有HTTPS要求。在开放平台后台配置应用功能权限支付相关产品需要签约开通不是申请完应用就能直接用。线上支付回调验签失败时会触发支付宝的重试机制重试几次后停止。此时务必人工介入避免丢单。8. 实操总结与我的个人建议这套Spring Boot整合支付宝沙箱测试的Demo从下单到支付再到回调、查询、退款基本覆盖了支付闭环的全部核心节点。代码量不大但每一步背后的设计都有讲究验签和金额校验是安全底线幂等和状态机是数据一致性保障日志和主动查询是排查问题的基础。说几个我实际操作中的体会第一支付模块的坑百分之六十发生在配置上而不是代码上。网关、APPID、密钥、回调地址这四个配置项只要错一个整个链路都转不起来。调试时我会先把配置打印到日志里确认它们和沙箱控制台一致再开始排查代码。第二异步通知是整个支付链路里最值得花时间打磨的环节。线下联调时把内网穿透配好让支付宝真实回调几次比手动模拟岔子少很多。回调处理函数里日志要打全异常要捕获完整不要用空catch吞掉真正的问题。第三支付宝沙箱虽然模拟了核心流程但毕竟不是线上环境异步通知的频率和稳定性可能和线上有差异。测试时如果发现回调一直不来先别怀疑代码看看穿透工具是否失效URL是否能公网访问。很多时候我以为是自己代码Bug排查半天最后发现是工具连接断开了。第四这个Demo如果你想进一步扩展可以考虑接入支付宝的“资金授权”“花呗分期”“预授权完成”等更高级的产品也可以把支付能力抽成独立的微服务通过消息队列把支付结果发给业务方还可以在回调里集成库存扣减、会员积分等下游业务。但无论扩展方向是什么支付的四个基本动作——下单、支付、回调、退款——始终是核心先把这四个动作吃透后续的功能都是锦上添花。按这个项目实践一遍从零到跑通完整支付闭环一整天时间基本够用。后面如果有什么新问题欢迎在实际操作中多翻日志、多打断点支付这块代码不怕改就怕不敢调试。祝早日跑通沙箱顺利上线。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
