Java使用Gson如何将BigDecimal金额序列化为无引号合规REST请求JSON数字？

问题触发根源 #

• 接口硬性校验规则：
  • 金额必须以无引号的数字字面量格式传入，字符串类型会直接返回500 - Bad request
  • 金额小数位必须匹配对应币种的常规精度要求，超出校验范围即触发报错
• 现有方案的不可用场景：
  • 直接传字符串类型金额：直接命中接口类型校验规则
  • 使用double类型存储/传参：二进制浮点的舍入误差会导致序列化数值出现预期外的小数位（如经典的0.1+0.2精度偏差），无法通过精度校验
  • 原始值为BigDecimal但未做适配时，Gson默认序列化逻辑可能输出科学计数法、多余尾随零等不符合接口要求的格式

可落地实现步骤 #

1. 前置精度规整
   序列化前先按对应币种的精度要求对齐BigDecimal值，全程不做double类型转换，从根源上避免引入浮点误差：

   // 示例：适配两位小数币种（如人民币、美元），采用通用HALF_UP舍入模式
   BigDecimal targetAmount = rawAmount.setScale(currencyRequiredDecimalPlaces, RoundingMode.HALF_UP);
   

2. 适配Gson序列化规则
   自定义BigDecimal的序列化TypeAdapter，强制输出无引号的数字字面量，同时关闭不必要的科学计数法转换：

   Gson compliantGson = new GsonBuilder()
       // 配置数字解析策略，避免隐式类型转换带来的精度丢失
       .setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
       .registerTypeAdapter(BigDecimal.class, new TypeAdapter<BigDecimal>() {
           @Override
           public void write(JsonWriter out, BigDecimal value) throws IOException {
               if (value == null) {
                   out.nullValue();
                   return;
               }
               // 核心逻辑：直接将BigDecimal作为JSON数字写入，不带引号
               out.value(value);
           }
           @Override
           public BigDecimal read(JsonReader in) throws IOException {
               return in.nextBigDecimal();
           }
       })
       .create();
   

3. 输出效果校验
   针对值为23.42的BigDecimal字段，上述逻辑生成的JSON片段为"amount":23.42，完全匹配接口要求：
   • 无引号包裹，不会触发接口的类型校验报错
   • 无舍入误差，小数位完全匹配对应币种的精度要求
   • 不会输出科学计数法等特殊格式的兼容问题

高概率踩坑点 #

• 禁止在序列化链路中插入BigDecimal到double的转换环节，哪怕数值看起来完全一致，隐式的浮点误差会随机触发接口校验失败，排查成本极高
• 禁止在自定义序列化时将BigDecimal转为字符串后调用out.value(String)，这类写法最终输出的JSON值会被双引号包裹，直接命中接口的500报错
• 不要依赖Gson默认序列化逻辑输出未做精度规整的BigDecimal，默认逻辑可能输出多余的尾随零（如23.400），触发接口的小数位校验失败

内容的提问来源于stack exchange，提问作者Avinta