Java Spring Boot请求体double可空字段@Nullable替代方案

核心问题原因 #

Java中的double是基本数据类型，不属于引用类型，不存在null值的概念，默认初始值为0.0。如果直接用基本类型声明字段，JSON反序列化时无法区分「请求未携带该字段」和「请求明确传值为0.0」两种场景，会产生业务逻辑歧义，也无法直接使用@Nullable标记可空属性。

正确处理方式 #

• 将字段类型从基本类型double替换为对应的包装类Double。Double是引用类型，默认值为null，当请求报文未携带amount字段时，反序列化后字段值为null，可以和传值为0的场景明确区分，也支持搭配@Nullable注解标记可空属性。
• 按需搭配参数校验注解：如果业务要求该字段为必传，给字段加@NotNull注解即可；如果允许缺失，不加必传校验、保留@Nullable标记即可，也可以搭配@DecimalMin/@DecimalMax做数值范围校验。
• 如果业务上需要给缺失的字段设置默认值，直接在字段声明时显式初始化即可，不要依赖类型的隐式默认值，避免逻辑歧义。

代码示例 #

正确的实体类写法如下：

import org.springframework.lang.Nullable;

// 可以搭配Lombok的@Data注解省略手写getter、setter、toString等模板代码
public class OrderCreateRequest {
    @Nullable
    private String phoneNumber;

    // 替换为Double包装类型，标记为可空
    @Nullable
    private Double amount;

    // 省略getter、setter方法
}

如果需要设置默认值，写法如下：

// 请求未传amount时，默认赋值为0.0，传值则覆盖默认值
@Nullable
private Double amount = 0.0;

避坑提示：不要强行使用基本类型double处理可空场景。如果保留基本类型，请求未传amount时框架会自动给字段赋值为0.0，后续业务逻辑完全无法区分「用户没填金额」和「用户填的金额就是0」，很容易引发业务bug。只有当业务逻辑中「未传金额」和「金额为0」完全等价时，才可以保留基本类型声明。

内容的提问来源于stack exchange，提问作者Hamza Mustafa Khan