企业官网建设流程全解析

1. 项目概述：为什么现在还要专门做Java对接PayPal支付（v2）？

PayPal支付（v2）不是新概念，但真正用Java稳稳落地、不踩坑、能过生产环境审计、还能应对订单幂等、退款闭环、Webhook验签、汇率动态处理这些细节的项目，其实少之又少。我最近帮某跨境电商SaaS平台重构支付模块，把原来基于v1 REST API的旧逻辑全部迁到v2，前后花了三周时间——不是写代码花的时间长，而是反复验证签名机制、调试Webhook重试策略、对齐PayPal沙箱与真实账户的响应差异、处理Java生态里OkHttp和Jackson在JSON序列化时对amount字段精度的隐式截断问题。这些坑，官方文档里一句不提，Stack Overflow上的答案大多过时，GitHub上开源SDK又太重、耦合Spring Boot自动配置，而我们用的是纯Java + Vert.x微服务架构。

核心关键词“java对接PayPal支付（v2）”背后，实际藏着五个刚性需求：第一是协议合规性——v2强制使用OAuth 2.0 Client Credentials Flow获取访问令牌，且Token有效期仅9小时，必须实现自动续期；第二是金额精度控制——PayPal要求所有货币金额必须精确到小数点后两位（USD/EUR等），但Java的double类型在序列化时极易产生0.9999999999999999这类浮点误差，直接导致支付失败；第三是Webhook事件可靠性——PayPal会因网络抖动重发事件，你的Java服务必须能识别重复ID并跳过处理，否则同一笔退款可能执行两次；第四是错误分类可操作性——比如PAYER_ACTION_REQUIRED不是报错，而是要跳转到PayPal页面让用户确认，而INVALID_PAYMENT_SOURCE才是真异常，需要记录日志并通知运营；第五是灰度发布支持——你不能一刀切切到v2，得让老订单走v1、新订单走v2，还得在日志里打标区分来源。这些都不是“调个API”就能解决的，而是要吃透PayPal v2的请求生命周期、状态机流转、以及Java生态中HTTP客户端、JSON处理器、定时任务调度器之间的协同逻辑。适合谁？不是刚学完Servlet的应届生，而是至少带过两个线上支付模块、熟悉Spring MVC拦截器链或Vert.x Router路由机制、能看懂OpenAPI 3.0规范的中级以上Java开发者。如果你正被“支付回调收不到”“退款提示400 Bad Request但日志没报错”“沙箱测试成功、上线就500”这些问题卡住，这篇就是为你写的。

2. 整体设计思路与方案选型解析

2.1 为什么放弃PayPal官方Java SDK，选择手写REST Client？

PayPal官方提供的paypal-java-sdk（v1.0.0+）确实封装了v2接口，但它存在三个硬伤：第一，它强制依赖Spring Boot 2.7+，而我们生产环境跑的是Spring Boot 2.4.13（JDK 11），升级框架风险太大；第二，它的Webhook验签逻辑把PAYPAL-REQUEST-ID和PAYPAL-TRANSMISSION-ID混在一起校验，而PayPal最新文档明确要求只用PAYPAL-TRANSMISSION-ID+PAYPAL-CERT-URL+PAYPAL-TRANSMISSION-TIME三元组生成HMAC-SHA256签名，官方SDK的实现反而会导致验签失败；第三，它的AmountWithBreakdown对象内部用BigDecimal存储金额，但序列化时Jackson默认会把0.00转成0，而PayPal API严格要求"value": "199.00"这种字符串格式，不是数字。我试过给SDK提PR，维护者回复说“这是设计使然”，然后就没下文了。

所以最终方案是：完全手写轻量级REST Client，仅依赖OkHttp 4.12.0 + Jackson 2.15.2 + Bouncy Castle 1.70（用于SHA256withRSA验签）。OkHttp负责连接池管理、超时控制、重试策略（注意：PayPal明确禁止对POST /v2/checkout/orders这类创建订单接口做自动重试，否则会生成多笔订单）；Jackson用自定义Serializer强制将BigDecimal序列化为带两位小数的字符串；Bouncy Castle则用来解析PayPal公钥证书并执行验签。整个Client代码不到800行，所有逻辑可控，出问题能秒级定位。比如当Webhook验签失败时，我可以直接打印出原始payload、transmission-id、timestamp、cert-url四要素，再用openssl命令行手动比对，而不是在SDK层层包装里扒源码。

2.2 架构分层怎么划？为什么Controller层绝不碰业务状态？

很多团队把支付逻辑全塞进Spring MVC的@RestController里，结果一个方法里既有调PayPal API、又有查本地订单、还有发MQ消息，最后连单元测试都写不出来。我们按“职责原子化”原则拆成四层：

• Adapter层（最外层）：只做协议转换。比如接收前端传来的{ "currency": "USD", "amount": 199.99 }，Adapter把它转成PayPal要求的{"intent":"CAPTURE","purchase_units":[{"amount":{"currency_code":"USD","value":"199.99"}}]}，同时校验amount是否为正数、小数位是否≤2。这里不做任何数据库操作，失败就抛IllegalArgumentException，由全局异常处理器返回400。

• Client层（核心）：封装所有PayPal HTTP调用。每个方法对应一个API端点，如createOrder()、capturePayment()、refundPayment()。关键点在于：所有方法都接受AccessToken作为参数（而不是从ThreadLocal里取），强制调用方显式传递凭证，避免因线程复用导致Token过期；所有返回值都是ResponseEntity<PayPalOrder>这种泛型结构，不解析业务字段，把JSON反序列化交给上层。

• Service层（业务中枢）：协调本地事务与远程调用。比如用户点击“支付”，Service先在本地DB插入payment_order记录（status=CREATING），再调用Client.createOrder()，如果PayPal返回成功，就把paypal_order_id更新到本地记录，status改为CREATED；如果PayPal超时，就捕获IOException，把本地记录status设为FAILED，并触发告警。这里用@Transactional保证本地DB操作原子性，但绝不把PayPal调用包进事务——因为HTTP调用不可回滚。

• Webhook Handler层（独立线程）：单独起一个Vert.x Worker verticle监听/webhook/paypal路径，收到请求后立即存入Redis缓存（key=webhook:${transmissionId}，ttl=10分钟），再异步处理。这样即使PayPal重发，第二次请求查Redis发现已存在，直接返回200，避免重复消费。

这个分层看着多，实测下来好处极明显：Adapter层单元测试覆盖率100%，Client层用MockWebServer伪造PayPal响应，Service层用H2内存库测事务边界，Webhook Handler用Embedded Redis测幂等。上线三个月，支付成功率从92.3%提升到99.8%，根本原因不是技术多高深，而是每一层都只干一件事，出了问题一眼定位到哪一层。

2.3 Token管理为什么不用Spring Security OAuth2，而用Quartz定时刷新？

PayPal v2的Access Token有效期是9小时（32400秒），官方建议在剩余30分钟时刷新。有人用Spring Security OAuth2的ClientRegistrationRepository自动管理，但问题在于：它把Token存在SecurityContext里，而Webhook Handler是独立线程，拿不到上下文；而且它刷新失败时会静默fallback到旧Token，导致后续调用401。我们改用Quartz 2.3.2配@DisallowConcurrentExecution注解，每天凌晨0点、上午9点、下午3点各刷一次，每次刷之前先查Redis里是否存在有效Token（key=paypal:token，value={ "access_token": "...", "expires_in": 32400, "timestamp": 1717023456 }），存在且剩余时间>1800秒就跳过。关键代码就三行：

String tokenJson = redisTemplate.opsForValue().get("paypal:token"); if (tokenJson != null) { PayPalToken token = objectMapper.readValue(tokenJson, PayPalToken.class); if (System.currentTimeMillis() - token.getTimestamp() < (token.getExpiresIn() - 1800) * 1000) { return token.getAccessToken(); } }

刷新逻辑走独立HTTP请求，成功后写Redis并设置过期时间（比PayPal返回的expires_in少60秒，留缓冲）。这么做的好处是：Token全局可见，所有线程都能取；刷新失败会发企业微信告警，运维能立刻介入；而且Redis里存的是完整Token对象，调试时直接redis-cli get paypal:token就能看到当前凭证状态。比任何框架封装都透明、可控。

3. 核心细节解析与实操要点

3.1 金额精度控制：为什么BigDecimal.valueOf(199.99)还是错的？

这是Java开发者最容易栽跟头的地方。你以为BigDecimal.valueOf(199.99)就安全了？错。199.99本身是double字面量，JVM先把它转成二进制浮点数，再转BigDecimal，中间已经失真。我实测过：

System.out.println(BigDecimal.valueOf(199.99)); // 输出：199.98999999999998 System.out.println(new BigDecimal("199.99")); // 输出：199.99 ✅

PayPal API收到"value": 199.98999999999998这种JSON，直接返回INVALID_REQUEST。解决方案有两个层级：

第一层（输入校验）：在Adapter层，所有金额字段必须用字符串接收。前端传{"amount": "199.99"}，后端用@JsonProperty("amount") private String amountStr;接收，再用new BigDecimal(amountStr)构造。如果前端非要用数字，就加@JsonDeserialize(using = StringToBigDecimalDeserializer.class)，自定义反序列化器强制转字符串再构造。

第二层（序列化控制）：Jackson默认把BigDecimal序列化成数字，必须重写。我们定义PayPalAmountSerializer：

public class PayPalAmountSerializer extends JsonSerializer<BigDecimal> { @Override public void serialize(BigDecimal value, JsonGenerator gen, SerializerProvider serializers) throws IOException { // 强制保留两位小数，不足补零 String formatted = value.setScale(2, RoundingMode.HALF_UP).toString(); gen.writeString(formatted); } }

然后在Amount类上标注：

public class Amount { @JsonSerialize(using = PayPalAmountSerializer.class) private BigDecimal value; private String currencyCode; }

这样无论value是199.99还是200，序列化后都是"199.99"和"200.00"。别小看这个setScale(2, RoundingMode.HALF_UP)，它解决了199.995这种临界值该进还是舍的问题——PayPal要求银行四舍五入，不是Java默认的HALF_EVEN。

3.2 Webhook验签：三步法手算签名，比SDK更可靠

PayPal Webhook验签是v2最烧脑的部分。它不像JWT用简单HMAC，而是用RSA公钥加密传输ID、时间戳、原始payload的拼接字符串。官方文档说“用cert-url下载证书，提取公钥，对transmissionId|time|payload|certUrl做SHA256哈希，再用公钥验签”，但没告诉你time格式必须是ISO 8601（2024-05-30T08:23:45Z），少个Z就失败；也没说payload必须是原始字节流，不能经过JSON美化或空格替换。

我们手写验签逻辑分三步：

第一步：预处理要素

String transmissionId = request.getHeader("PAYPAL-TRANSMISSION-ID"); String time = request.getHeader("PAYPAL-TRANSMISSION-TIME"); // 必须是"2024-05-30T08:23:45Z" String certUrl = request.getHeader("PAYPAL-CERT-URL"); String rawPayload = IOUtils.toString(request.getInputStream(), StandardCharsets.UTF_8); // 原始字节，不parse

第二步：拼接待签名字符串

String signatureBase = transmissionId + "|" + time + "|" + rawPayload + "|" + certUrl;

第三步：用Bouncy Castle验签

// 1. 下载certUrl证书（缓存到本地文件，避免每次HTTP请求） X509Certificate cert = loadCertificateFromUrl(certUrl); // 2. 提取公钥 PublicKey publicKey = cert.getPublicKey(); // 3. 解析PayPal传来的base64签名 byte[] signatureBytes = Base64.getDecoder().decode(request.getHeader("PAYPAL-SIGNATURE")); // 4. 验证 Signature sig = Signature.getInstance("SHA256withRSA", "BC"); sig.initVerify(publicKey); sig.update(signatureBase.getBytes(StandardCharsets.UTF_8)); boolean isValid = sig.verify(signatureBytes);

关键点在于：loadCertificateFromUrl()必须加本地缓存（我们用Caffeine Cache，key=certUrl，expireAfterWrite=24h），否则每笔Webhook都要HTTP请求PayPal证书服务器，QPS上去就拖垮服务；signatureBase必须严格按顺序拼接，中间用|分隔，不能多空格、不能换行；rawPayload必须用IOUtils.toString()原样读取，不能用@RequestBody String payload，因为Spring MVC默认会做字符编码转换。

3.3 订单状态机：如何用本地状态映射PayPal的12种订单状态？

PayPal v2订单有CREATED、APPROVED、COMPLETED、VOIDED、CAPTURED等12种状态，但我们的本地订单表只有PENDING、PAID、REFUNDED、CANCELLED四个状态。硬映射会出问题：比如PayPal的APPROVED只是用户点了“同意支付”，钱还没到账，对应本地应该是PENDING；而COMPLETED才是资金结算完成，才该设为PAID。更麻烦的是CAPTURED——它可能出现在COMPLETED之后（部分捕获），也可能单独出现（延迟捕获）。

我们设计了一个双向状态映射表：

重点在COMPLETED和CAPTURED的处理逻辑：Webhook收到PAYMENT.CAPTURE.COMPLETED事件时，先查本地订单，如果已是PAID，就只更新capture_id和captured_amount；如果是PENDING，就先设为PAID再更新。这样既兼容即时捕获（用户付款后立刻到账），也支持延迟捕获（用户付款后，商家后台手动触发捕获）。上线后遇到过一次PayPal状态乱序：先发COMPLETED，5秒后又发CAPTURED，因为我们的幂等设计，第二次CAPTURED事件查到本地已是PAID，直接跳过，没造成数据不一致。

4. 实操过程与核心环节实现

4.1 沙箱环境配置：三步拿到可用凭证，避开90%的401错误

PayPal沙箱不是注册完就能用，必须走完三个隐藏步骤，否则POST /v2/checkout/orders永远返回401：

第一步：创建两个沙箱账号
登录 PayPal Developer Dashboard ，点“Accounts” → “Create Account”，创建一个Business账号（模拟商户）和一个Personal账号（模拟买家）。Business账号的邮箱必须是全新未注册过PayPal的，否则创建失败。创建完记下Business账号的Client ID和Secret，这是调API的凭证。

第二步：开启Webhook并获取Webhook ID
在Dashboard左侧菜单点“Webooks” → “Add webhook”，填入你的内网穿透地址（如https://xxx.ngrok.io/webhook/paypal），勾选PAYMENT.CAPTURE.COMPLETED、CHECKOUT.ORDER.APPROVED等事件。保存后，页面会显示Webhook ID（形如wh-1234567890abcdef），这个ID要填到后端配置里，PayPal回调时会带上它。

第三步：在Business账号里启用“Live Mode”开关
这是最坑的一步！沙箱账号默认关闭Live Mode，导致Webhook无法触发。登录Business沙箱账号（用创建时的邮箱密码），进入 Profile Settings → “My selling tools” → “Update”右侧的“Website payments preferences”，把“Block accidental payments”设为“No”，再点“Update”。然后回到Developer Dashboard，点右上角账号头像 → “Account Settings” → “Sandbox accounts”，找到你的Business账号，点“Manage”，在“Features”里把“Live Mode”开关打开。做完这三步，curl -X POST https://api.sandbox.paypal.com/v1/oauth2/token才能返回200。

我踩过的坑：第一次用公司域名配Webhook，PayPal沙箱不认HTTPS证书，必须用ngrok或localtunnel；第二次用错Personal账号的邮箱登录Business账号，一直提示“Invalid credentials”；第三次没开Live Mode，Webhook配置页显示“Active”，但实际一条回调都不发。建议把这三步写成checklist，每次新项目都过一遍。

4.2 创建订单接口：从请求体构建到响应解析的完整链路

以创建一笔199.99美元订单为例，Java代码实录如下：

// 1. 构建请求体（注意：所有金额字段必须是字符串） PayPalOrderRequest orderReq = new PayPalOrderRequest(); orderReq.setIntent("CAPTURE"); PurchaseUnit unit = new PurchaseUnit(); Amount amount = new Amount(); amount.setCurrencyCode("USD"); amount.setValue("199.99"); // 强制字符串 unit.setAmount(amount); unit.setReferenceId("ORDER-20240530-001"); orderReq.setPurchaseUnits(Collections.singletonList(unit)); // 2. 获取AccessToken（从Redis取，过期则刷新） String accessToken = tokenService.getValidAccessToken(); // 3. 发起HTTP请求 Request request = new Request.Builder() .url("https://api.sandbox.paypal.com/v2/checkout/orders") .post(RequestBody.create( objectMapper.writeValueAsBytes(orderReq), MediaType.parse("application/json") )) .addHeader("Content-Type", "application/json") .addHeader("Authorization", "Bearer " + accessToken) .build(); Response response = okHttpClient.newCall(request).execute(); if (!response.isSuccessful()) { throw new PayPalApiException("Create order failed: " + response.code()); } // 4. 解析响应（PayPal返回的id是订单唯一标识） String responseBody = response.body().string(); PayPalOrder order = objectMapper.readValue(responseBody, PayPalOrder.class); String paypalOrderId = order.getId(); // 如"5YK51234567890123" // 5. 本地持久化 PaymentOrder localOrder = new PaymentOrder(); localOrder.setPaypalOrderId(paypalOrderId); localOrder.setStatus("PENDING"); localOrder.setAmount(new BigDecimal("199.99")); paymentOrderMapper.insert(localOrder);

关键细节：

• PurchaseUnit.setReferenceId()必须填你本地的订单号，PayPal会在Webhook里原样返回，方便你关联；
• Amount.setValue()必须是字符串，且setScale(2)后无多余字符；
• okHttpClient要配置连接超时（3s）、读超时（10s）、写超时（10s），PayPal沙箱响应慢，超时设太短会误判失败；
• response.body().string()必须在response.isSuccessful()判断后调用，否则response.body()可能为null；
• 解析PayPalOrder时，id字段是PayPal生成的21位字符串，不要用Long类型接收，会溢出。

4.3 捕获支付：同步调用与异步Webhook的双保险策略

用户在PayPal页面点击“Pay Now”后，PayPal会重定向回你的return_url，此时你必须立即调用POST /v2/checkout/orders/{id}/capture捕获资金。但网络可能超时，所以必须设计双保险：

保险一：同步捕获（redirect后立即执行）
在return_url对应的Controller里：

@GetMapping("/return") public String handleReturn(@RequestParam String token) { try { // 1. 调用Capture API CaptureResponse captureResp = client.capturePayment(token); // 2. 更新本地订单为PAID paymentOrderService.markAsPaid(token, captureResp.getCaptureId()); return "redirect:/success?order=" + token; } catch (PayPalApiException e) { // 同步失败，记录日志，但不报错给用户 log.error("Sync capture failed for order {}", token, e); // 保险二启动：等待Webhook return "redirect:/pending?order=" + token; } }

保险二：Webhook兜底（PAYMENT.CAPTURE.COMPLETED事件）
Webhook Handler收到事件后：

@PostMapping("/webhook/paypal") public ResponseEntity<String> handleWebhook(@RequestBody String payload, @RequestHeader("PAYPAL-TRANSMISSION-ID") String transmissionId, @RequestHeader("PAYPAL-TRANSMISSION-TIME") String time, @RequestHeader("PAYPAL-CERT-URL") String certUrl, @RequestHeader("PAYPAL-SIGNATURE") String signature) { if (!webhookValidator.isValid(payload, transmissionId, time, certUrl, signature)) { return ResponseEntity.status(401).body("Invalid signature"); } PayPalWebhookEvent event = objectMapper.readValue(payload, PayPalWebhookEvent.class); if ("PAYMENT.CAPTURE.COMPLETED".equals(event.getEventType())) { String paypalOrderId = event.getResource().getOrderId(); // 查本地订单，如果还是PENDING，就更新为PAID paymentOrderService.markAsPaid(paypalOrderId, event.getResource().getCaptureId()); } return ResponseEntity.ok().body("OK"); }

这样，99%的订单走同步捕获，剩下1%网络抖动的由Webhook兜底。上线后统计，同步捕获成功率98.7%，Webhook兜底成功率100%，整体支付完成率99.99%。注意：markAsPaid()方法必须加数据库行锁（SELECT ... FOR UPDATE），防止Webhook和同步请求并发更新同一订单。

4.4 退款实现：全额退与部分退的参数差异及风控点

PayPal v2退款分两种：POST /v2/payments/captures/{capture_id}/refund（针对已捕获的资金）和POST /v2/checkout/orders/{order_id}/authorize（针对已批准未捕获的订单）。我们只用第一种，因为业务要求资金到账后才能退款。

全额退款请求体：

{ "amount": { "currency_code": "USD", "value": "199.99" }, "invoice_id": "REF-20240530-001" }

部分退款请求体：

{ "amount": { "currency_code": "USD", "value": "50.00" }, "invoice_id": "REF-20240530-001", "note_to_payer": "Partial refund for damaged item" }

关键风控点：

• invoice_id必须全局唯一，我们用"REF-" + orderId + "-" + System.currentTimeMillis()生成，避免重复；
• 部分退款时，value不能超过该capture_id的总金额，PayPal会校验，失败返回REFUND_AMOUNT_EXCEEDS_CAPTURE_AMOUNT；
• 退款必须在捕获后180天内发起，超时返回REFUND_NOT_ALLOWED；
• 同一笔capture_id最多支持50次退款（PayPal限制），所以invoice_id要带时间戳，方便排查。

Java实现退款的核心方法：

public RefundResponse refundCapture(String captureId, BigDecimal amount, String invoiceId) { // 1. 校验本地订单状态是否为PAID PaymentOrder order = paymentOrderMapper.selectByCaptureId(captureId); if (!"PAID".equals(order.getStatus())) { throw new BusinessException("Cannot refund non-paid order"); } // 2. 校验退款金额是否超限 BigDecimal capturedAmount = order.getCapturedAmount(); if (amount.compareTo(capturedAmount) > 0) { throw new BusinessException("Refund amount exceeds captured amount"); } // 3. 构建请求体 RefundRequest req = new RefundRequest(); Amount amt = new Amount(); amt.setCurrencyCode(order.getCurrencyCode()); amt.setValue(amount.setScale(2, RoundingMode.HALF_UP).toString()); req.setAmount(amt); req.setInvoiceId(invoiceId); // 4. 调用PayPal API return client.refundCapture(captureId, req); }

上线后遇到过一次事故：运营同学误操作，对同一笔订单连续点了三次全额退款，PayPal返回三次成功，但实际只退了一次（PayPal幂等），而我们的本地退款流水写了三条。修复方案是在refundCapture()方法开头加Redis分布式锁：redisTemplate.opsForValue().setIfAbsent("refund:" + captureId, "locked", Duration.ofMinutes(5))，锁存在才执行，避免重复提交。

5. 常见问题与排查技巧实录

5.1 401 Unauthorized：Token失效的七种可能及定位方法

PayPal v2返回401，90%不是Token真的过期，而是以下七种情况之一：

我最常犯的错是第五种：本地开发用沙箱，测试环境切生产，但忘了改paypal.api.url，结果用沙箱Token调生产API，PayPal直接返回401。后来我们在tokenService里加了断言：

String apiUrl = payPalConfig.getApiUrl(); if (apiUrl.contains("sandbox") && !clientId.startsWith("sb-")) { throw new IllegalStateException("Sandbox API url but production client id"); }

5.2 Webhook收不到：网络、配置、代码三层排查法

Webhook收不到是最高频问题，按“网络层→配置层→代码层”顺序排查：

网络层（占30%问题）
PayPal只支持HTTPS回调，且证书必须由权威CA签发（Let's Encrypt可以，自签名不行）。用openssl s_client -connect yourdomain.com:443 -servername yourdomain.com检查证书链是否完整。如果用ngrok，确保ngrok http 8080 --host-header=rewrite，否则PayPal回调时Host头不匹配。

配置层（占50%问题）

• 检查Webhook ID是否填到后端代码里（webhookValidator.setWebhookId("wh-xxx")）；
• 检查Dashboard里Webhook状态是否为“Active”，不是“Inactive”；
• 检查Webhook事件类型是否勾选了你要监听的（如漏勾CHECKOUT.ORDER.APPROVED，用户同意后就不会回调）；
• 检查沙箱Business账号是否绑定了Webhook（Dashboard → Webhooks → 点击你的Webhook → “Associated Accounts”里要有Business账号）。

代码层（占20%问题）

• @PostMapping("/webhook/paypal")必须加consumes = MediaType.ALL_VALUE，否则PayPal的application/json请求被Spring拒掉；
• 方法里不能有@RequestBody以外的参数（如@RequestParam），PayPal回调不带Query参数；
• response.body().string()必须在response.isSuccessful()后调用，否则空指针；
• 验签失败必须返回401，不能返回200，否则PayPal认为成功，不再重试。

我们写了个自动化检测脚本，每天凌晨用curl模拟PayPal回调：

curl -X POST https://yourdomain.com/webhook/paypal \ -H "PAYPAL-TRANSMISSION-ID: test-id" \ -H "PAYPAL-TRANSMISSION-TIME: $(date -u +"%Y-%m-%dT%H:%M:%SZ")" \ -H "PAYPAL-CERT-URL: https://api.sandbox.paypal.com/v1/cert/production.crt" \ -H "PAYPAL-SIGNATURE: invalid-signature" \ -d '{"event_type":"test"}'

如果返回401，说明验签逻辑正常；如果返回500，说明代码有bug。这个脚本集成到CI里，每次发版自动跑。

5.3 金额不一致：从Java字节码到PayPal JSON的全流程精度追踪

前端传199.99，PayPal返回199.98999999999998，这种问题必须从源头追踪：

Step 1：前端传参检查
用浏览器Network面板看请求Payload，确认是"amount":"199.99"（字符串）还是"amount":199.99（数字）。如果是后者，在Adapter层加日志：

log.info("Raw amount from frontend: {}", amountStr); if (amountStr.matches("\\d+\\.\\d+")) { // 是数字字符串，继续 } else { throw new IllegalArgumentException("Amount must be decimal string"); }

Step 2：Jackson反序列化检查
在@RequestBody对象的amount字段上加@JsonCreator，强制走字符串构造：

public class PaymentRequest { private final BigDecimal amount; @JsonCreator public PaymentRequest(@JsonProperty("amount") String amountStr) { this.amount = new BigDecimal(amountStr).setScale(2, RoundingMode.HALF_UP); } }

Step 3：PayPal API请求体检查
用OkHttp的LoggingInterceptor打印出站请求：

HttpLoggingInterceptor logging = new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BODY); okHttpClient = new OkHttpClient.Builder().addInterceptor(logging).build();

看日志里"value":"199.99"是否正确。

Step 4：PayPal响应体检查
同样用LoggingInterceptor看PayPal返回的"amount":{"value":"199.99"}，确认PayPal没改。

Step 5：本地数据库存储检查
查MySQL的payment_order表，amount字段类型必须是DECIMAL(10,2)，不能是FLOAT或DOUBLE。

我们曾在线上发现MySQL字段是FLOAT，导致199.99存进去变成199.98999，修复后所有金额显示正常。所以，**精度问题从来不是单一环节的锅，而是从前端到数据库的全链路