做过支付对接的都知道真正吃时间的往往不是代码本身而是“没有真实商户号之前没法联调”这个尴尬局面。申请正式商户号要营业执照、要签约产品、要等审核这套流程走下来新手光是前置手续就能卡一到两周。所以我在接到第一个 SpringBoot 支付需求时就直接从支付宝沙箱环境切入——零门槛、有真实测试账号、能完整走通支付/回调/退款全链路。这篇内容就是把这套完整流程拆开讲透包含下单接口、异步通知、验签、主动查单、退款以及我实际联调中踩到过的所有高频坑。对 SpringBoot 支付开发还不太熟的读者照着这份思路走一遍基本能把支付链路理解个七八成。1. 沙箱环境准备先别急着写代码把这几个东西配齐1.1 沙箱应用与密钥的获取方式沙箱环境本质上是支付宝开放平台单独划出来的一套模拟系统它和正式环境的接口地址、参数结构几乎完全一致只是用了一套独立的密钥、应用ID和测试账号。好处是你不需要任何营业执照只需要登录支付宝开放平台控制台找到“沙箱环境”入口就能一键创建沙箱应用。创建完成后系统会分配一个沙箱的 APPID类似2021000111111111。这个 APPID 和正式环境里每个应用唯一的 APPID 作用是一样的只是它只匹配沙箱网关。实际开发中我会建议直接用沙箱应用来做一切接口验证等支付逻辑全部跑通再把这套代码切到正式应用参数上。密钥部分是新手最容易懵的地方。支付宝加签用的是 RSA2也就是 SHA256withRSA密钥长度至少 2048 位。你需要自己生成一对 RSA 密钥把公钥上传到支付宝后台同时从后台拿到支付宝的公钥。私钥自己保留绝不外传。具体流程是这样的在沙箱控制台找到“接口加签方式”选择“公钥模式”。使用支付宝官方提供的密钥生成工具生成应用私钥和应用公钥。把应用公钥复制粘贴到后台的公钥输入框。保存后后台会生成对应的“支付宝公钥”这个字符串需要拷贝出来后面代码里要用。这里有非常关键的一个点支付宝公钥 ≠ 应用公钥。我在早期对接时曾把应用公钥当成支付宝公钥拿去验签结果验签永远失败报错信息还特别隐晦。你要记得上传到后台的是应用公钥从后台取出来的是支付宝公钥一个管“我往外发数据时签名用”一个管“我收到支付宝回传数据时验签用”。1.2 全局参数一览这些配置后面都会用到与其边写代码边查参数不如先把整条链路涉及到的配置项拉一张总表出来。以下是我在项目里用到的所有支付相关配置按用途做了分类参数沙箱环境值正式环境值用途网关地址https://openapi.alipaydev.com/gateway.dohttps://openapi.alipay.com/gateway.do所有 API 统一请求入口APPID沙箱控制台生成正式应用申请后生成标识应用应用私钥本地生成的 RSA 私钥重新生成的正式私钥生成请求签名支付宝公钥沙箱后台展示正式后台展示验签支付宝回调通知签名类型RSA2RSA2加签算法回调地址公网可访问的 http/https 地址正式服务器地址接收支付宝异步通知返回地址支付成功后页面跳转地址正式前端页面地址同步跳转展示结果格式/字符集JSON / UTF-8JSON / UTF-8请求与响应编码我强烈建议把这份配置单独抽成一个配置文件管理后续切环境时只需要改配置文件不需要动业务代码。如果你用的是 SpringBoot把这些参数放进application.yml就是最常规的做法。1.3 沙箱账号和测试工具沙箱环境和正式环境还有一个重要区别支付环节使用的账号体系不同。你在沙箱控制台能看到系统自动分配的“沙箱买家”和“沙箱商家”账号。买家账号是一串手机号或邮箱格式的测试账号支付时可以直接选择余额支付默认会有一定的余额可供消费。如果你要在手机端验证支付效果支付宝专门提供了沙箱版支付宝 App这个 App 只能用于沙箱环境不能登录真实的支付宝账号。早期我联调时就犯过一个错在真实支付宝 App 里去扫沙箱支付的付款码结果自然什么都扫不出来。后来才反应过来沙箱支付必须用沙箱版 App 配合沙箱买家账号才能完整走通。另外支付宝后台还有一个“沙箱工具”比如支付宝开放平台开发助手它不仅能帮你生成密钥还能提供一个本地的接口调试工具。不过我更习惯直接看接口返回的报文和日志来定位问题工具可以辅助但不能依赖。2. SpringBoot 工程骨架与支付参数配置2.1 依赖引入与项目结构沙箱环境的事情搞定后就可以开始搭 SpringBoot 工程了。我这里以一个标准的 Maven 工程为例Java 版本 8 就够用SpringBoot 用 2.x 或 3.x 都可以但需要注意 SDK 的兼容性。支付宝官方 Java SDK 的坐标是com.alipay.sdk:alipay-sdk-java。我这里用的版本是4.38.0.ALL这个版本对 Java 8 的兼容性很好接口封装也比较完整。如果你们项目用的是更高版本只要接口方法名一致直接替换版本号就行。dependency groupIdcom.alipay.sdk/groupId artifactIdalipay-sdk-java/artifactId version4.38.0.ALL/version /dependency工程结构上我习惯按照功能分包而不是按技术层分包。支付相关代码集中放在alipay包里里面分别放config、controller、service、param、model几个子包。这样后续做正式环境切换、加日志、加异常处理时改动范围都能控制在一个包内。2.2 配置文件与属性绑定接下来把沙箱参数写进application.yml。这里有一个经验之谈私钥字符串通常比较长而且包含换行符YAML 里直接粘贴会出问题。我建议你在配置里使用连续的字符串也就是去掉换行让私钥变成一行。如果你非要在配置里保留可读性可以放在 properties 文件里用\换行符处理。alipay: app-id: 2021000123456789 app-private-key: MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC... alipay-public-key: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA... gateway: https://openapi.alipaydev.com/gateway.do notify-url: https://你的公网域名/notify return-url: http://localhost:8080/return sign-type: RSA2 charset: UTF-8 format: JSON为了让 SpringBoot 能把这堆配置自动装配成对象我写了一个AlipayProperties配置类Component ConfigurationProperties(prefix alipay) Data public class AlipayProperties { private String appId; private String appPrivateKey; private String alipayPublicKey; private String gateway; private String notifyUrl; private String returnUrl; private String signType; private String charset; private String format; }注意用ConfigurationProperties需要引入spring-boot-configuration-processor的依赖或者在启动类上开启EnableConfigurationProperties。不过即使不做这些只要 SpringBoot 能够扫描到Component配置绑定也能生效只是 IDE 里不会有自动提示。2.3 全局配置里最容易被忽略的两个细节第一个细节是构建AlipayClient的方式。官方推荐的写法是在每次请求时创建一个客户端但那样会重复加载私钥影响性能。我的做法是在配置类里直接构建一个单例的AlipayClient用Bean交给 Spring 容器管理。Configuration public class AlipayConfig { Bean public AlipayClient alipayClient(AlipayProperties props) { return new DefaultAlipayClient( props.getGateway(), props.getAppId(), props.getAppPrivateKey(), props.getFormat(), props.getCharset(), props.getAlipayPublicKey(), props.getSignType() ); } }第二个细节是参数校验。支付金额、订单号、商品标题这些参数如果为空直接去调支付宝接口不仅浪费一次请求还会导致后续回调没数据可匹配。我建议在 Service 层先做一次简单的参数非空校验宁可校验严格一些也好过在日志里排查半天空参数问题。3. 打通核心链路下单、拼接参数、发起支付3.1 为什么用 alipay.trade.page.pay 而不是别的接口支付宝开放平台针对不同场景提供了不同的下单接口。常见的有alipay.trade.page.pay电脑网站支付用于 PC 端打开支付宝收银台。alipay.trade.wap.pay手机网站支付用于 H5 端拉起支付宝。alipay.trade.app.payApp 支付用于原生应用内跳转支付宝。alipay.trade.create统一收单交易创建接口只创建订单不直接跳支付。我在这个教程里用的是alipay.trade.page.pay因为它最适合新手理解“下单——跳转——支付——回调”这个完整闭环。它会把请求参数拼成一个自动提交的 HTML 表单返回给浏览器用户点击按钮或直接访问接口地址就会自动跳转到支付宝收银台页面。很多初学者会纠结alipay.trade.create和alipay.trade.page.pay的区别。简单理解alipay.trade.create只是把订单信息登记到支付宝系统不会直接引导用户支付通常用于 App 等自定义收银台场景而page.pay是交易和支付一气呵成支付页面都由支付宝托管。3.2 代码实现构建请求并返回支付表单先写一个下单的 Service 方法。方法入参只需要三个核心信息业务订单号、支付金额、商品标题。这些信息在真实项目里一般来自你的业务订单表这里只演示核心逻辑。Service public class AlipayService { private final AlipayClient alipayClient; private final AlipayProperties alipayProperties; public AlipayService(AlipayClient alipayClient, AlipayProperties alipayProperties) { this.alipayClient alipayClient; this.alipayProperties alipayProperties; } public String createOrder(String outTradeNo, String totalAmount, String subject) { AlipayTradePagePayRequest request new AlipayTradePagePayRequest(); request.setNotifyUrl(alipayProperties.getNotifyUrl()); request.setReturnUrl(alipayProperties.getReturnUrl()); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(total_amount, totalAmount); bizContent.put(subject, subject); bizContent.put(product_code, FAST_INSTANT_TRADE_PAY); 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是业务参数的核心支付宝所有业务参数都以 JSON 字符串形式放在这里。字段名必须严格遵循官方文档out_trade_no是下划线命名不能写错。total_amount是字符串类型的金额单位为元支持两位小数。很多新手从数据库取金额是分如果直接用整形拼接会变成1000实际应该拼接成10.00。product_code必须设置为FAST_INSTANT_TRADE_PAY它对应电脑网站支付场景。如果你不小心漏了这个字段接口会报“产品码缺失或无效”。然后写一个 Controller 方法把 HTML 表单直接返回给前端。这里有个坑需要提前说接收这个字符串的页面要么通过window.location.href跳转要么直接把接口响应内容以 HTML 方式渲染不能把这个字符串塞进 JSON 里否则浏览器不会自动提交表单。RestController RequestMapping(/alipay) public class AlipayController { private final AlipayService alipayService; public AlipayController(AlipayService alipayService) { this.alipayService alipayService; } GetMapping(/pay) public void pay(RequestParam String orderNo, RequestParam String amount, RequestParam String subject, HttpServletResponse response) throws IOException { String form alipayService.createOrder(orderNo, amount, subject); response.setContentType(text/html;charsetUTF-8); response.getWriter().write(form); response.getWriter().flush(); } }3.3 同步跳转 returnUrl只能做展示不能做订单状态依据支付完成后支付宝会通过浏览器跳转到returnUrl。很多新手会在这个接口里直接更新订单状态这是一个严重的错误认知。returnUrl是同步跳转用户支付完点了“返回商家”才会触发浏览器地址栏也能看到参数。问题是用户可能支付成功后没有点返回也可能页面被强制刷新甚至网银页面异常时压根没有执行跳转。所以这个接口只能用来展示支付结果真正的订单状态更新必须依赖异步通知。我通常会让returnUrl接口做两件事调用alipay.trade.query查询接口获取实时交易状态。在支付结果页展示“支付成功”或“支付失败”的提示。这样用户体验是实时的但业务数据的最终落库以异步通知为准。4. 异步通知与验签钱到账了才算完4.1 异步通知机制说明支付宝的异步通知是整条支付链路里最核心、也最容易出问题的环节。支付成功后支付宝服务器会主动向你的notifyUrl发起一个 POST 请求请求中的参数包括订单号、交易号、支付金额、买家信息、交易状态等一堆字段。这里有几个机制层面的特征需要注意通知最多会发送 8 次按一定时间间隔递增直到你返回“success”字符串或达到上限。你收到通知后必须返回纯文本的success不带引号、不带 JSON、不带 XML如果返回其他内容支付宝会认为通知失败并继续重试。通知请求是支付宝服务器发起的不经过用户浏览器所以它的参数可信度必须通过验签来确认。异步通知参数中的trade_status字段决定了订单的最终走向trade_status含义订单状态处理WAIT_BUYER_PAY交易创建等待买家付款不更新保持待支付TRADE_SUCCESS支付成功更新为已支付发货TRADE_FINISHED交易完成且不可退款更新为交易完成关闭退款功能TRADE_CLOSED未付款交易超时关闭/退款后关闭更新为已关闭大多数业务场景只需要关注TRADE_SUCCESS和TRADE_FINISHED。前者代表买家已付款后者代表整个交易生命周期结束。如果你做的是虚拟商品在TRADE_SUCCESS时发货即可如果做实物商品退款功能在TRADE_FINISHED后就不能再发起了。4.2 验签代码实现验签的目的是确认“这条通知真的是支付宝发来的而不是别的服务伪造的”。支付宝的通知请求是一串参数加上签名参数sign我们使用支付宝公钥进行验签。我给出一个通用的通知处理代码PostMapping(/notify) public String notify(HttpServletRequest request) throws AlipayApiException { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { String[] values requestParams.get(name); String valueStr ; for (int i 0; i values.length; i) { valueStr (i values.length - 1) ? valueStr values[i] : valueStr values[i] ,; } params.put(name, valueStr); } boolean signVerified AlipaySignature.rsaCheckV1( params, alipayProperties.getAlipayPublicKey(), alipayProperties.getCharset(), alipayProperties.getSignType() ); if (!signVerified) { return failure; } String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); String tradeStatus params.get(trade_status); String totalAmount params.get(total_amount); String appId params.get(app_id); // 追加校验同一订单金额必须与本地订单一致appId 必须匹配 // 这里省略业务查询逻辑读者需要自行对比本地订单金额 if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { // 更新本地订单为已支付 // 注意幂等处理防止重复通知导致重复发货 } return success; }代码里那个参数拼接逻辑看起来有点绕但它是官方推荐的写法。原因是有个别参数值本身可能包含逗号直接用request.getParameter()只拿到第一个值会丢数据所以手动用逗号拼接所有值。4.3 幂等处理与订单状态更新异步通知会重试也就是说同一个订单的“支付成功”通知你可能会收到两次、三次甚至更多次。如果每次收到通知都执行“更新库存”、“发送邮件”、“赠送积分”之类的操作用户会被重复发货、重复加积分。我处理幂等的思路很简单根据out_trade_no查本地订单。如果订单状态已经是“已支付”直接返回success不重复执行业务逻辑。如果订单状态是“待支付”才执行状态更新和后续业务动作。这里有个细节值得注意从第一次收到成功通知到更新订单状态之间可能存在并发问题。两个重试通知几乎同时到达线程 A 和线程 B 同时查到“待支付”同时执行更新造成重复发货。我建议在更新订单状态时加一个数据库条件更新int rows orderMapper.updateStatus( orderNo, OrderStatus.PAID.getCode(), OrderStatus.WAIT_PAY.getCode() );也就是update ... set status PAID where order_no ? and status WAIT_PAY。如果rows 0说明已经被其他线程更新过了直接返回success。这个做法比在代码里用 synchronized 或分布式锁更轻量也更保险。5. 查询订单与退款逻辑备用的两道保险5.1 主动查询交易状态异步通知虽然可靠但不能完全依赖。用户支付成功后可能由于网络原因导致通知延迟或者你服务端的回调地址暂时不可用这时主动查询就是一个兜底方案。查询接口是alipay.trade.query代码实现比较简洁public AlipayTradeQueryResponse queryTrade(String outTradeNo) throws AlipayApiException { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); request.setBizContent(bizContent.toJSONString()); return alipayClient.execute(request); }响应对象里有tradeStatus、sendPayDate、totalAmount等字段。我在实际项目中编写了一个定时任务每 10 分钟扫描一次订单表中“已下单但长时间未支付”的订单调用查询接口确认最终状态补偿异步通知丢失导致的漏单。这里要提醒一下定时任务的频率不要太高否则对支付宝接口的调用量会暴涨也可能触发业务风控。查询兜底的作用是防止漏单不是替代异步通知。5.2 退款接口的适用场景退款是支付类项目早晚会碰到的需求。支付宝的退款接口是alipay.trade.refund需要注意的是它支持部分退款同一个订单可以多次退款只要总的退款金额不超过订单金额就行。public AlipayTradeRefundResponse refund(String outTradeNo, String refundAmount, String outRequestNo) throws AlipayApiException { AlipayTradeRefundRequest request new AlipayTradeRefundRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(refund_amount, refundAmount); bizContent.put(out_request_no, outRequestNo); request.setBizContent(bizContent.toJSONString()); return alipayClient.execute(request); }out_request_no是退款请求号每次退款必须保证唯一它用于防止重复退款。你在生成这个号时可以用订单号 退款批次号拼接保证同一订单多次退款时各批次号不同。退款成功返回后支付宝同样会发送异步通知通知的trade_status或refund_status字段会标识退款结果。如果是自动退款到账一般以接口返回结果为准如果是资金延迟清算就要以异步通知为准。最简单的做法是退款时直接把本地订单状态改成“退款中”收到退款成功通知后再改成“已退款”。6. 沙箱实测中的高频坑与上线切换清单6.1 我踩过的那些坑列举出来帮你提前避雷对接支付宝的时间久了每个坑都对应过一段调试日志。下面挑几个出现频率最高的按影响程度排序金额单位不一致。数据库里存的是分接口传参的是元。如果直接把 1000 分当 10 元传给支付宝那支付的金额就直接翻了一百倍。我建议在业务代码里统一用BigDecimal并且用字符串构造器来避免精度问题new BigDecimal(10.00)。不要直接用double乘除法否则会出现 0.1 0.2 不等于 0.3 这种经典精度问题。私钥文件里的换行符。从密钥工具导出私钥时文件里是带换行的-----BEGIN PRIVATE KEY-----和-----END PRIVATE KEY-----。如果你把整个文件内容直接粘贴到application.ymlYAML 解析时会把它拆成多行导致签名报错。解决办法是在代码里读取文件内容时保留换行或者在配置中手动去掉换行。更稳妥的做法是不要把私钥放配置文件而是利用环境变量或密钥管理服务注入。验签时用错公钥。验签必须用支付宝公钥不是应用私钥、不是应用公钥。如果发现验签一直失败先检查密钥配置是不是反了。我见过不少同事改了半天代码最后发现是配置里把两个公钥位置放反了。回调地址不稳定。notifyUrl必须是一个公网可访问的地址且不能带参数或 IP 直连。如果你本地联调没有公网地址可以用内网穿透工具把本地 8080 端口映射到公网域名上。但要注意有些穿透工具分配的域名会变导致支付宝通知第一次成功、第二次就超时。回调里拿不到某些参数。异步通知的参数是以 POST 表单形式传输的如果你在 SpringBoot 中用了防盗链的过滤器或者统一参数包装可能导致参数被提前读取导致getParameterMap()为空。排查这类问题时建议先在 Controller 入口处打印所有参数再一层层查过滤链。日志打印导致死循环。有人会把异步通知请求体和响应直接打到业务库里结果收到通知后更新状态又产生一条新的日志记录通知重试时再打一条……看起来像异步通知风暴。其实只是日志逻辑写得太重建议把通知日志写到独立的日志文件即可不要与其他业务操作绑定。6.2 沙箱切换到正式环境的完整清单当沙箱环境验证通过后切到正式环境并没有想象中那么难但要核对的事项很多。我总结过一份切换清单每次上线支付功能前都会逐项过一遍检查项沙箱中的值正式环境的操作网关地址openapi.alipaydev.com/gateway.do改为openapi.alipay.com/gateway.doAPPID沙箱应用 ID替换为正式应用 ID应用私钥沙箱私钥生成新的正式私钥并妥善保存支付宝公钥沙箱公钥从正式应用后台取出并更新产品签约沙箱默认支持正式应用必须签约“电脑网站支付”产品回调地址公网测试域名改为正式服务器域名并配置 HTTPS测试买家沙箱买家账号无需处理使用真实买家支付上线前还建议用一笔极小的金额比如 0.01 元跑一遍真实支付验证支付和回调链路都通。之后再做退款测试确认买家能收到退款通知。全链路真实跑通一次比看一百遍文档都管用。最后再分享一个我在多轮对接后形成的小习惯支付接口的入参、出参、回调参数统一打好结构化日志。沙箱调试时把这些日志打到独立文件上线后通过日志关键字TRADE_SUCCESS、notify、signVerified等快速定位问题。支付链路涉及钱出问题时要做到“一眼定位”这比任何代码技巧都重要。 
长河君 · 2026/10/18 8:43:46 · 阅读 1.2k SpringBoot对接支付宝沙箱：从下单到退款全链路实战
做过支付对接的都知道真正吃时间的往往不是代码本身而是“没有真实商户号之前没法联调”这个尴尬局面。申请正式商户号要营业执照、要签约产品、要等审核这套流程走下来新手光是前置手续就能卡一到两周。所以我在接到第一个 SpringBoot 支付需求时就直接从支付宝沙箱环境切入——零门槛、有真实测试账号、能完整走通支付/回调/退款全链路。这篇内容就是把这套完整流程拆开讲透包含下单接口、异步通知、验签、主动查单、退款以及我实际联调中踩到过的所有高频坑。对 SpringBoot 支付开发还不太熟的读者照着这份思路走一遍基本能把支付链路理解个七八成。1. 沙箱环境准备先别急着写代码把这几个东西配齐1.1 沙箱应用与密钥的获取方式沙箱环境本质上是支付宝开放平台单独划出来的一套模拟系统它和正式环境的接口地址、参数结构几乎完全一致只是用了一套独立的密钥、应用ID和测试账号。好处是你不需要任何营业执照只需要登录支付宝开放平台控制台找到“沙箱环境”入口就能一键创建沙箱应用。创建完成后系统会分配一个沙箱的 APPID类似2021000111111111。这个 APPID 和正式环境里每个应用唯一的 APPID 作用是一样的只是它只匹配沙箱网关。实际开发中我会建议直接用沙箱应用来做一切接口验证等支付逻辑全部跑通再把这套代码切到正式应用参数上。密钥部分是新手最容易懵的地方。支付宝加签用的是 RSA2也就是 SHA256withRSA密钥长度至少 2048 位。你需要自己生成一对 RSA 密钥把公钥上传到支付宝后台同时从后台拿到支付宝的公钥。私钥自己保留绝不外传。具体流程是这样的在沙箱控制台找到“接口加签方式”选择“公钥模式”。使用支付宝官方提供的密钥生成工具生成应用私钥和应用公钥。把应用公钥复制粘贴到后台的公钥输入框。保存后后台会生成对应的“支付宝公钥”这个字符串需要拷贝出来后面代码里要用。这里有非常关键的一个点支付宝公钥 ≠ 应用公钥。我在早期对接时曾把应用公钥当成支付宝公钥拿去验签结果验签永远失败报错信息还特别隐晦。你要记得上传到后台的是应用公钥从后台取出来的是支付宝公钥一个管“我往外发数据时签名用”一个管“我收到支付宝回传数据时验签用”。1.2 全局参数一览这些配置后面都会用到与其边写代码边查参数不如先把整条链路涉及到的配置项拉一张总表出来。以下是我在项目里用到的所有支付相关配置按用途做了分类参数沙箱环境值正式环境值用途网关地址https://openapi.alipaydev.com/gateway.dohttps://openapi.alipay.com/gateway.do所有 API 统一请求入口APPID沙箱控制台生成正式应用申请后生成标识应用应用私钥本地生成的 RSA 私钥重新生成的正式私钥生成请求签名支付宝公钥沙箱后台展示正式后台展示验签支付宝回调通知签名类型RSA2RSA2加签算法回调地址公网可访问的 http/https 地址正式服务器地址接收支付宝异步通知返回地址支付成功后页面跳转地址正式前端页面地址同步跳转展示结果格式/字符集JSON / UTF-8JSON / UTF-8请求与响应编码我强烈建议把这份配置单独抽成一个配置文件管理后续切环境时只需要改配置文件不需要动业务代码。如果你用的是 SpringBoot把这些参数放进application.yml就是最常规的做法。1.3 沙箱账号和测试工具沙箱环境和正式环境还有一个重要区别支付环节使用的账号体系不同。你在沙箱控制台能看到系统自动分配的“沙箱买家”和“沙箱商家”账号。买家账号是一串手机号或邮箱格式的测试账号支付时可以直接选择余额支付默认会有一定的余额可供消费。如果你要在手机端验证支付效果支付宝专门提供了沙箱版支付宝 App这个 App 只能用于沙箱环境不能登录真实的支付宝账号。早期我联调时就犯过一个错在真实支付宝 App 里去扫沙箱支付的付款码结果自然什么都扫不出来。后来才反应过来沙箱支付必须用沙箱版 App 配合沙箱买家账号才能完整走通。另外支付宝后台还有一个“沙箱工具”比如支付宝开放平台开发助手它不仅能帮你生成密钥还能提供一个本地的接口调试工具。不过我更习惯直接看接口返回的报文和日志来定位问题工具可以辅助但不能依赖。2. SpringBoot 工程骨架与支付参数配置2.1 依赖引入与项目结构沙箱环境的事情搞定后就可以开始搭 SpringBoot 工程了。我这里以一个标准的 Maven 工程为例Java 版本 8 就够用SpringBoot 用 2.x 或 3.x 都可以但需要注意 SDK 的兼容性。支付宝官方 Java SDK 的坐标是com.alipay.sdk:alipay-sdk-java。我这里用的版本是4.38.0.ALL这个版本对 Java 8 的兼容性很好接口封装也比较完整。如果你们项目用的是更高版本只要接口方法名一致直接替换版本号就行。dependency groupIdcom.alipay.sdk/groupId artifactIdalipay-sdk-java/artifactId version4.38.0.ALL/version /dependency工程结构上我习惯按照功能分包而不是按技术层分包。支付相关代码集中放在alipay包里里面分别放config、controller、service、param、model几个子包。这样后续做正式环境切换、加日志、加异常处理时改动范围都能控制在一个包内。2.2 配置文件与属性绑定接下来把沙箱参数写进application.yml。这里有一个经验之谈私钥字符串通常比较长而且包含换行符YAML 里直接粘贴会出问题。我建议你在配置里使用连续的字符串也就是去掉换行让私钥变成一行。如果你非要在配置里保留可读性可以放在 properties 文件里用\换行符处理。alipay: app-id: 2021000123456789 app-private-key: MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC... alipay-public-key: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA... gateway: https://openapi.alipaydev.com/gateway.do notify-url: https://你的公网域名/notify return-url: http://localhost:8080/return sign-type: RSA2 charset: UTF-8 format: JSON为了让 SpringBoot 能把这堆配置自动装配成对象我写了一个AlipayProperties配置类Component ConfigurationProperties(prefix alipay) Data public class AlipayProperties { private String appId; private String appPrivateKey; private String alipayPublicKey; private String gateway; private String notifyUrl; private String returnUrl; private String signType; private String charset; private String format; }注意用ConfigurationProperties需要引入spring-boot-configuration-processor的依赖或者在启动类上开启EnableConfigurationProperties。不过即使不做这些只要 SpringBoot 能够扫描到Component配置绑定也能生效只是 IDE 里不会有自动提示。2.3 全局配置里最容易被忽略的两个细节第一个细节是构建AlipayClient的方式。官方推荐的写法是在每次请求时创建一个客户端但那样会重复加载私钥影响性能。我的做法是在配置类里直接构建一个单例的AlipayClient用Bean交给 Spring 容器管理。Configuration public class AlipayConfig { Bean public AlipayClient alipayClient(AlipayProperties props) { return new DefaultAlipayClient( props.getGateway(), props.getAppId(), props.getAppPrivateKey(), props.getFormat(), props.getCharset(), props.getAlipayPublicKey(), props.getSignType() ); } }第二个细节是参数校验。支付金额、订单号、商品标题这些参数如果为空直接去调支付宝接口不仅浪费一次请求还会导致后续回调没数据可匹配。我建议在 Service 层先做一次简单的参数非空校验宁可校验严格一些也好过在日志里排查半天空参数问题。3. 打通核心链路下单、拼接参数、发起支付3.1 为什么用 alipay.trade.page.pay 而不是别的接口支付宝开放平台针对不同场景提供了不同的下单接口。常见的有alipay.trade.page.pay电脑网站支付用于 PC 端打开支付宝收银台。alipay.trade.wap.pay手机网站支付用于 H5 端拉起支付宝。alipay.trade.app.payApp 支付用于原生应用内跳转支付宝。alipay.trade.create统一收单交易创建接口只创建订单不直接跳支付。我在这个教程里用的是alipay.trade.page.pay因为它最适合新手理解“下单——跳转——支付——回调”这个完整闭环。它会把请求参数拼成一个自动提交的 HTML 表单返回给浏览器用户点击按钮或直接访问接口地址就会自动跳转到支付宝收银台页面。很多初学者会纠结alipay.trade.create和alipay.trade.page.pay的区别。简单理解alipay.trade.create只是把订单信息登记到支付宝系统不会直接引导用户支付通常用于 App 等自定义收银台场景而page.pay是交易和支付一气呵成支付页面都由支付宝托管。3.2 代码实现构建请求并返回支付表单先写一个下单的 Service 方法。方法入参只需要三个核心信息业务订单号、支付金额、商品标题。这些信息在真实项目里一般来自你的业务订单表这里只演示核心逻辑。Service public class AlipayService { private final AlipayClient alipayClient; private final AlipayProperties alipayProperties; public AlipayService(AlipayClient alipayClient, AlipayProperties alipayProperties) { this.alipayClient alipayClient; this.alipayProperties alipayProperties; } public String createOrder(String outTradeNo, String totalAmount, String subject) { AlipayTradePagePayRequest request new AlipayTradePagePayRequest(); request.setNotifyUrl(alipayProperties.getNotifyUrl()); request.setReturnUrl(alipayProperties.getReturnUrl()); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(total_amount, totalAmount); bizContent.put(subject, subject); bizContent.put(product_code, FAST_INSTANT_TRADE_PAY); 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是业务参数的核心支付宝所有业务参数都以 JSON 字符串形式放在这里。字段名必须严格遵循官方文档out_trade_no是下划线命名不能写错。total_amount是字符串类型的金额单位为元支持两位小数。很多新手从数据库取金额是分如果直接用整形拼接会变成1000实际应该拼接成10.00。product_code必须设置为FAST_INSTANT_TRADE_PAY它对应电脑网站支付场景。如果你不小心漏了这个字段接口会报“产品码缺失或无效”。然后写一个 Controller 方法把 HTML 表单直接返回给前端。这里有个坑需要提前说接收这个字符串的页面要么通过window.location.href跳转要么直接把接口响应内容以 HTML 方式渲染不能把这个字符串塞进 JSON 里否则浏览器不会自动提交表单。RestController RequestMapping(/alipay) public class AlipayController { private final AlipayService alipayService; public AlipayController(AlipayService alipayService) { this.alipayService alipayService; } GetMapping(/pay) public void pay(RequestParam String orderNo, RequestParam String amount, RequestParam String subject, HttpServletResponse response) throws IOException { String form alipayService.createOrder(orderNo, amount, subject); response.setContentType(text/html;charsetUTF-8); response.getWriter().write(form); response.getWriter().flush(); } }3.3 同步跳转 returnUrl只能做展示不能做订单状态依据支付完成后支付宝会通过浏览器跳转到returnUrl。很多新手会在这个接口里直接更新订单状态这是一个严重的错误认知。returnUrl是同步跳转用户支付完点了“返回商家”才会触发浏览器地址栏也能看到参数。问题是用户可能支付成功后没有点返回也可能页面被强制刷新甚至网银页面异常时压根没有执行跳转。所以这个接口只能用来展示支付结果真正的订单状态更新必须依赖异步通知。我通常会让returnUrl接口做两件事调用alipay.trade.query查询接口获取实时交易状态。在支付结果页展示“支付成功”或“支付失败”的提示。这样用户体验是实时的但业务数据的最终落库以异步通知为准。4. 异步通知与验签钱到账了才算完4.1 异步通知机制说明支付宝的异步通知是整条支付链路里最核心、也最容易出问题的环节。支付成功后支付宝服务器会主动向你的notifyUrl发起一个 POST 请求请求中的参数包括订单号、交易号、支付金额、买家信息、交易状态等一堆字段。这里有几个机制层面的特征需要注意通知最多会发送 8 次按一定时间间隔递增直到你返回“success”字符串或达到上限。你收到通知后必须返回纯文本的success不带引号、不带 JSON、不带 XML如果返回其他内容支付宝会认为通知失败并继续重试。通知请求是支付宝服务器发起的不经过用户浏览器所以它的参数可信度必须通过验签来确认。异步通知参数中的trade_status字段决定了订单的最终走向trade_status含义订单状态处理WAIT_BUYER_PAY交易创建等待买家付款不更新保持待支付TRADE_SUCCESS支付成功更新为已支付发货TRADE_FINISHED交易完成且不可退款更新为交易完成关闭退款功能TRADE_CLOSED未付款交易超时关闭/退款后关闭更新为已关闭大多数业务场景只需要关注TRADE_SUCCESS和TRADE_FINISHED。前者代表买家已付款后者代表整个交易生命周期结束。如果你做的是虚拟商品在TRADE_SUCCESS时发货即可如果做实物商品退款功能在TRADE_FINISHED后就不能再发起了。4.2 验签代码实现验签的目的是确认“这条通知真的是支付宝发来的而不是别的服务伪造的”。支付宝的通知请求是一串参数加上签名参数sign我们使用支付宝公钥进行验签。我给出一个通用的通知处理代码PostMapping(/notify) public String notify(HttpServletRequest request) throws AlipayApiException { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { String[] values requestParams.get(name); String valueStr ; for (int i 0; i values.length; i) { valueStr (i values.length - 1) ? valueStr values[i] : valueStr values[i] ,; } params.put(name, valueStr); } boolean signVerified AlipaySignature.rsaCheckV1( params, alipayProperties.getAlipayPublicKey(), alipayProperties.getCharset(), alipayProperties.getSignType() ); if (!signVerified) { return failure; } String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); String tradeStatus params.get(trade_status); String totalAmount params.get(total_amount); String appId params.get(app_id); // 追加校验同一订单金额必须与本地订单一致appId 必须匹配 // 这里省略业务查询逻辑读者需要自行对比本地订单金额 if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { // 更新本地订单为已支付 // 注意幂等处理防止重复通知导致重复发货 } return success; }代码里那个参数拼接逻辑看起来有点绕但它是官方推荐的写法。原因是有个别参数值本身可能包含逗号直接用request.getParameter()只拿到第一个值会丢数据所以手动用逗号拼接所有值。4.3 幂等处理与订单状态更新异步通知会重试也就是说同一个订单的“支付成功”通知你可能会收到两次、三次甚至更多次。如果每次收到通知都执行“更新库存”、“发送邮件”、“赠送积分”之类的操作用户会被重复发货、重复加积分。我处理幂等的思路很简单根据out_trade_no查本地订单。如果订单状态已经是“已支付”直接返回success不重复执行业务逻辑。如果订单状态是“待支付”才执行状态更新和后续业务动作。这里有个细节值得注意从第一次收到成功通知到更新订单状态之间可能存在并发问题。两个重试通知几乎同时到达线程 A 和线程 B 同时查到“待支付”同时执行更新造成重复发货。我建议在更新订单状态时加一个数据库条件更新int rows orderMapper.updateStatus( orderNo, OrderStatus.PAID.getCode(), OrderStatus.WAIT_PAY.getCode() );也就是update ... set status PAID where order_no ? and status WAIT_PAY。如果rows 0说明已经被其他线程更新过了直接返回success。这个做法比在代码里用 synchronized 或分布式锁更轻量也更保险。5. 查询订单与退款逻辑备用的两道保险5.1 主动查询交易状态异步通知虽然可靠但不能完全依赖。用户支付成功后可能由于网络原因导致通知延迟或者你服务端的回调地址暂时不可用这时主动查询就是一个兜底方案。查询接口是alipay.trade.query代码实现比较简洁public AlipayTradeQueryResponse queryTrade(String outTradeNo) throws AlipayApiException { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); request.setBizContent(bizContent.toJSONString()); return alipayClient.execute(request); }响应对象里有tradeStatus、sendPayDate、totalAmount等字段。我在实际项目中编写了一个定时任务每 10 分钟扫描一次订单表中“已下单但长时间未支付”的订单调用查询接口确认最终状态补偿异步通知丢失导致的漏单。这里要提醒一下定时任务的频率不要太高否则对支付宝接口的调用量会暴涨也可能触发业务风控。查询兜底的作用是防止漏单不是替代异步通知。5.2 退款接口的适用场景退款是支付类项目早晚会碰到的需求。支付宝的退款接口是alipay.trade.refund需要注意的是它支持部分退款同一个订单可以多次退款只要总的退款金额不超过订单金额就行。public AlipayTradeRefundResponse refund(String outTradeNo, String refundAmount, String outRequestNo) throws AlipayApiException { AlipayTradeRefundRequest request new AlipayTradeRefundRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(refund_amount, refundAmount); bizContent.put(out_request_no, outRequestNo); request.setBizContent(bizContent.toJSONString()); return alipayClient.execute(request); }out_request_no是退款请求号每次退款必须保证唯一它用于防止重复退款。你在生成这个号时可以用订单号 退款批次号拼接保证同一订单多次退款时各批次号不同。退款成功返回后支付宝同样会发送异步通知通知的trade_status或refund_status字段会标识退款结果。如果是自动退款到账一般以接口返回结果为准如果是资金延迟清算就要以异步通知为准。最简单的做法是退款时直接把本地订单状态改成“退款中”收到退款成功通知后再改成“已退款”。6. 沙箱实测中的高频坑与上线切换清单6.1 我踩过的那些坑列举出来帮你提前避雷对接支付宝的时间久了每个坑都对应过一段调试日志。下面挑几个出现频率最高的按影响程度排序金额单位不一致。数据库里存的是分接口传参的是元。如果直接把 1000 分当 10 元传给支付宝那支付的金额就直接翻了一百倍。我建议在业务代码里统一用BigDecimal并且用字符串构造器来避免精度问题new BigDecimal(10.00)。不要直接用double乘除法否则会出现 0.1 0.2 不等于 0.3 这种经典精度问题。私钥文件里的换行符。从密钥工具导出私钥时文件里是带换行的-----BEGIN PRIVATE KEY-----和-----END PRIVATE KEY-----。如果你把整个文件内容直接粘贴到application.ymlYAML 解析时会把它拆成多行导致签名报错。解决办法是在代码里读取文件内容时保留换行或者在配置中手动去掉换行。更稳妥的做法是不要把私钥放配置文件而是利用环境变量或密钥管理服务注入。验签时用错公钥。验签必须用支付宝公钥不是应用私钥、不是应用公钥。如果发现验签一直失败先检查密钥配置是不是反了。我见过不少同事改了半天代码最后发现是配置里把两个公钥位置放反了。回调地址不稳定。notifyUrl必须是一个公网可访问的地址且不能带参数或 IP 直连。如果你本地联调没有公网地址可以用内网穿透工具把本地 8080 端口映射到公网域名上。但要注意有些穿透工具分配的域名会变导致支付宝通知第一次成功、第二次就超时。回调里拿不到某些参数。异步通知的参数是以 POST 表单形式传输的如果你在 SpringBoot 中用了防盗链的过滤器或者统一参数包装可能导致参数被提前读取导致getParameterMap()为空。排查这类问题时建议先在 Controller 入口处打印所有参数再一层层查过滤链。日志打印导致死循环。有人会把异步通知请求体和响应直接打到业务库里结果收到通知后更新状态又产生一条新的日志记录通知重试时再打一条……看起来像异步通知风暴。其实只是日志逻辑写得太重建议把通知日志写到独立的日志文件即可不要与其他业务操作绑定。6.2 沙箱切换到正式环境的完整清单当沙箱环境验证通过后切到正式环境并没有想象中那么难但要核对的事项很多。我总结过一份切换清单每次上线支付功能前都会逐项过一遍检查项沙箱中的值正式环境的操作网关地址openapi.alipaydev.com/gateway.do改为openapi.alipay.com/gateway.doAPPID沙箱应用 ID替换为正式应用 ID应用私钥沙箱私钥生成新的正式私钥并妥善保存支付宝公钥沙箱公钥从正式应用后台取出并更新产品签约沙箱默认支持正式应用必须签约“电脑网站支付”产品回调地址公网测试域名改为正式服务器域名并配置 HTTPS测试买家沙箱买家账号无需处理使用真实买家支付上线前还建议用一笔极小的金额比如 0.01 元跑一遍真实支付验证支付和回调链路都通。之后再做退款测试确认买家能收到退款通知。全链路真实跑通一次比看一百遍文档都管用。最后再分享一个我在多轮对接后形成的小习惯支付接口的入参、出参、回调参数统一打好结构化日志。沙箱调试时把这些日志打到独立文件上线后通过日志关键字TRADE_SUCCESS、notify、signVerified等快速定位问题。支付链路涉及钱出问题时要做到“一眼定位”这比任何代码技巧都重要。