REST请求中按需排除特定字段不发送null值

本文介绍两种标准、可靠的方式，使同一 Java POJO 能灵活适配不同 REST 接口的字段要求：通过 Optional 或 JsonNullable 控制 JSON 序列化行为，确保目标字段在请求中完全不出现（而非传 null），从而满足接口严格的字段校验规则。

在微服务或前后端分离的架构中，同一个请求 DTO 被多个 REST 接口复用的情况非常普遍——比如一个用户信息对象，有的接口只认三个字段，另一个则必须携带第四个字段，同时要求前三个字段里不能出现多余的“尾巴”。此时如果直接使用 @JsonIgnore，虽然字段会彻底消失，但轮到需要它的接口时，它也不会出现，导致功能中断。反之，如果保留字段并让其为 null，第一个接口的校验规则又会报错：白名单中不允许包含该字段，即便值为 null 也不行。

那么正确的解法是什么？关键在于让字段“可选但可被序列化控制”——字段存在时参与序列化，不存在时彻底消失，而不是传递一个 null 值。这正是 Java 生态中两个经典方案的核心价值：Optional 和 JsonNullable。下面逐一展开说明。

方案一：使用 java.util.Optional（推荐，零依赖）

将需要按需出现的字段声明为 Optional，再配合 Jackson 的 @JsonInclude(JsonInclude.Include.NON_EMPTY) 或更精确的 NON_NULL（注意：Optional.empty() 默认被视为空对象，序列化时会自动跳过）。

import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.Optional;

public class UserRequest {
    private String field1;
    private String field2;
    private String field3;

    @JsonInclude(JsonInclude.Include.NON_NULL) // 或 NON_EMPTY（对 Optional 更安全）
    private Optional field4;

    // 构造器、getter/setter 省略

    public static UserRequest forEndpoint1(String f1, String f2, String f3) {
        UserRequest req = new UserRequest();
        req.field1 = f1;
        req.field2 = f2;
        req.field3 = f3;
        req.field4 = Optional.empty(); // 不参与序列化
        return req;
    }

    public static UserRequest forEndpoint2(String f1, String f2, String f3, String f4) {
        UserRequest req = new UserRequest();
        req.field1 = f1;
        req.field2 = f2;
        req.field3 = f3;
        req.field4 = Optional.of(f4); // 仅此时序列化 field4
        return req;
    }
}

⚠️ 注意：Jackson 默认支持 Optional，但需要确保使用的是 Jackson 2.9+，并且全局或类级的 @JsonInclude 生效。如果发现不生效，可以在 ObjectMapper 初始化时统一设置：

objectMapper.setDefaultPropertyInclusion(JsonInclude.Include.NON_EMPTY);

方案二：使用 JsonNullable（OpenAPI 生态友好）

该方案更适合已集成 OpenAPI Generator 或需要严格区分“未设置”与“显式 null”的场景。引入 Maven 依赖后，将字段声明为 JsonNullable，通过 JsonNullable.undefined() 表示不输出，用 JsonNullable.of(...) 表示有值。

    org.openapitools
    jackson-databind-nullable
    0.2.6

import org.openapitools.jackson.nullable.JsonNullable;

public class UserRequest {
    private String field1;
    private String field2;
    private String field3;
    private JsonNullable field4;

    // 使用示例
    public static UserRequest forEndpoint1(...) {
        UserRequest req = new UserRequest();
        req.field4 = JsonNullable.undefined(); // 序列化时完全省略
        return req;
    }

    public static UserRequest forEndpoint2(...) {
        UserRequest req = new UserRequest();
        req.field4 = JsonNullable.of("value"); // 序列化为 "field4": "value"
        return req;
    }
}

总结与选型建议

• ✅ 优先选用 Optional：JDK 原生、零额外依赖、语义清晰（empty() = 字段未提供），适合绝大多数 Spring Boot / Jackson 项目。
• ✅ 选用 JsonNullable：当项目已基于 OpenAPI 规范生成客户端，或需要明确区分 undefined（不传）、null（显式空值）、"value"（有值）三态时，它是更严谨的选择。
• ❌ 避免 @JsonIgnore + 手动设 null：JSON 中仍然可能出现 "field4": null，这依然违反了 Endpoint-1 的字段白名单策略。