发生了什么

用户通过合作渠道的 App 下单租用电池套餐,提交时要先支付一笔押金。这笔钱不在本平台直接扣,而是由平台把一条“押金支付请求”发给负责收单的支付服务,支付服务受理后渠道侧才继续走下单流程。请求里带订单标识、用户标识、系统编码,还有一个“客户端版本号”——支付服务用它判断调用方是否为受支持的版本,该字段缺失或不在支持范围内,请求会被直接拒绝。

一次运行环境升级中,团队把 JDK 从 8 升到 21。升级本身没有改动业务代码,但编译期使用的两个依赖必须跟着升版本才能编译通过:负责生成 getter/setter/builder 的 Lombok,以及负责在编译期生成对象转换实现的 MapStruct。升级上线后,渠道用户押金支付开始失败,渠道侧拿到的是“网络开小差了,请稍后重试”,用户没能下单成功。

研发把升级前后同一个支付接口的请求参数拉出来逐个比对:订单标识、系统编码、用户标识、押金相关标识都在,唯独客户端版本号不见了。同期的调用统计是绝大多数请求失败、少量重试后成功;落到业务上,十余笔套餐订单受影响,其中大部分重试后成功,仍有 3 笔失败,需要与渠道侧协调重试处理。

本质

问题不在“要不要带版本号”这条业务规则,而在升级之后,对象转换的实现方式变了,版本号在一次对象转换中被丢掉。

  1. 支付请求对象分两层:公共基类定义所有下游调用共用的字段,其中就有客户端版本号;押金业务的子类只声明押金相关字段,并用 Lombok 的 @Builder 生成构造器。
  2. 渠道下单进入平台后,平台用一个转换器把渠道请求对象转成押金支付请求对象。这个方法的实现是 MapStruct 在编译期生成的,开发人员只写了接口方法。
  3. 旧版 MapStruct 不识别 builder,一律调用目标对象的 setter 赋值。setter 由 @Data 生成,包含从父类继承来的字段,所以版本号能正常写进去。
  4. 升级后的 MapStruct 会先看目标类有没有 builder,有就优先用 builder 构造。而 Lombok 的 @Builder 只为本类声明的字段生成构造方法,父类字段不在其中。生成的转换实现里,版本号根本没有被赋值,构造出的对象中它是空值。
  5. 支付服务收到请求后校验客户端版本号,空值被判为不受支持的调用方,直接返回校验失败。渠道侧把失败翻译成“网络开小差”,用户看到的就是下单不成功。

这个缺口在联调时没有暴露,有两个原因。一是转换之后本来就有一段手工补偿逻辑,会把个别字段重新 set 一遍,请求“看起来是完整的”,联调只核对了订单、金额这些显眼字段;二是从字段丢失到请求被拒的因果只体现在支付服务的校验规则里,本端既不报错也不打日志,不逐字段比对就看不出差别。

影响面也不止这一处:扫描项目后发现,同时使用 @Builder 并继承父类的类有 11 个,其中 2 个被转换器直接使用,6 个继承公共基类、可能丢失基类的十余个字段,3 个继承分页基类、可能丢失分页相关字段。

处理上,确认先采用“在转换器方法上关闭 builder 推导”的方式快速修复,让 MapStruct 回到 setter 构造;再在后续工作日把继承链上的 @Builder 统一换成 @SuperBuilder,从根上让 builder 包含父类字段。另有一种在转换后手工补 set 的做法,改动最小,但只能补当前这一个字段,属于临时处理。

错误代码

// 脱敏教学示例:只保留导致字段丢失的结构,不是事故源码
@Mapper
public interface ChannelPayConverter {
    // 升级后的 MapStruct 检测到目标类带 builder,就改用 builder 构造目标对象
    DepositPayRequest toPayRequest(ChannelDepositCmd cmd);
}

@Data
public class BasePayRequest {
    private String version;      // 客户端版本号,支付服务按它校验调用方
    private String systemCode;
}

@Data
@Builder                         // 为什么错:@Builder 只覆盖本类字段,父类 version 不在 builder 里
public class DepositPayRequest extends BasePayRequest {
    private String depositId;
    private String userNewId;
}

// 调用方:转换后手工补了部分字段,version 没人补,发出去的请求里它是空值
DepositPayRequest req = converter.toPayRequest(cmd);
req.setDepositId(cmd.getPackageId());
payClient.pay(req);              // 支付服务校验 version 为空,直接拒绝受理

修复代码示例

@Mapper
public interface ChannelPayConverter {
    // 修复一(快速止血):只对该方法关闭 builder 推导,回退到 setter 构造,
    // 父类继承来的 version 随 setter 一起被赋值
    @BeanMapping(builder = @Builder(disableBuilder = true))
    DepositPayRequest toPayRequest(ChannelDepositCmd cmd);
}

// 修复二(根治):继承链上所有类统一改为 @SuperBuilder,
// builder 才会包含父类字段;同一继承链上不能再混用 @Builder
@Data
@SuperBuilder
public class BasePayRequest {
    private String version;
    private String systemCode;
}

@Data
@SuperBuilder
public class DepositPayRequest extends BasePayRequest {
    private String depositId;
    private String userNewId;
}

下次遇到这些场景要警惕

  • 升级 Lombok、MapStruct 这类编译期代码生成依赖:挑一个“目标类带 @Builder 且继承父类”的转换器,把转换前后的对象按全部字段(含父类)打印比对,观察是否有字段静默为空,而不是只跑一遍主流程接口。
  • 转换之后存在手工补偿 set:把补偿逻辑当信号,列出该目标对象的所有字段并逐个确认来源;只有被补偿的字段是“显式处理过”的,其余字段可能一直在丢。
  • 下游用某个字段做准入校验:在本端发请求前对该字段加非空断言或契约测试,构造一次“转换器漏字段”的用例,确认请求会在本端被拦住并报警,而不是等到下游返回校验失败。
  • 接口升级牵动依赖版本:先用搜索统计“@Builder 加继承父类”的类清单,标注哪些被转换器直接使用,按清单逐个回归,覆盖公共基类字段与分页字段。