Java Jackson JSON 空字段怎样区分缺失与 null

在 Java 接收 PATCH 或配置更新 JSON 时，{} 和 {"nickname":null} 不能按同一个意思处理：前者表示调用方没有提交这个字段，后者表示调用方明确提交了空值。Jackson 的树模型正好保留了这层差异。

官方资料：https://github.com/FasterXML/jackson-databind

最稳妥的判断顺序是：先用 has("字段") 判断字段是否出现，再取节点检查 isNull()；需要安全访问多级路径时使用 path()，并识别它返回的 MissingNode。不要只用 get() == null，否则会把“缺失”与“显式 null”混在一起。

先把 missing、null 和普通值分成三类

Jackson 的 JsonNode.get(String) 在字段不存在时返回 Java 的 null；如果字段存在且 JSON 值是 null，返回的是表示显式空值的节点。也就是说，判断“字段有没有出现”与判断“字段值是不是 null”是两件事。

下面的最小示例同时读取三份请求，输出状态标签。代码使用 Jackson 的树模型，不依赖 DTO 上的默认值，因此适合需要区分提交意图的更新接口。

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class JacksonFieldState {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        String[] bodies = {"{}", "{\"nickname\":null}", "{\"nickname\":\"Lin\"}"};

        for (String body : bodies) {
            JsonNode root = mapper.readTree(body);
            JsonNode nickname = root.get("nickname");

            // 先区分字段是否存在，再区分存在的值是不是 JSON null。
            String state = nickname == null
                    ? "missing"
                    : (nickname.isNull() ? "explicit-null" : "value");
            System.out.println(body + " -> " + state);
        }
    }
}

这里的关键不是把字符串转成 Java null，而是保留节点层面的状态。对于对象字段，root.has("nickname") 在显式 null 时仍返回 true；root.hasNonNull("nickname") 则会把显式 null 排除，不能拿它代替“字段是否出现”的判断。

用 has 和 get 判断字段是否真的提交

如果业务只关心字段有没有出现在 JSON 里，使用 has 最直接；如果还要读取值，可以把 get 的结果保存下来，再调用 isNull。这比连续调用 get 更容易读，也能避免对 Java null 直接调用方法。

JsonNode root = mapper.readTree("{\"nickname\":null,\"age\":18}");

// has 判断属性名是否存在，显式 null 也算存在。
if (!root.has("nickname")) {
    System.out.println("调用方没有提交 nickname");
} else {
    JsonNode node = root.get("nickname");
    // 只有字段存在后，才检查它是否明确提交了 JSON null。
    if (node.isNull()) {
        System.out.println("调用方要求清空 nickname");
    } else {
        System.out.println("调用方提交了新 nickname: " + node.asText());
    }
}

可以把三种结果整理成一个小表：

嵌套字段用 path，别让缺失路径制造空指针

读取 profile.contact.email 这类嵌套字段时，连续调用 get 需要层层判空。path 会在路径不存在时返回 Jackson 的缺失节点，因而可以安全链式调用；但缺失节点和显式的 NullNode 仍然要分开判断。

JsonNode root = mapper.readTree("{\"profile\":{\"contact\":{\"email\":null}}}");
JsonNode email = root.path("profile").path("contact").path("email");

// MissingNode 表示路径没有对应字段，不等于 JSON null。
if (email.isMissingNode()) {
    System.out.println("email 字段缺失");
} else if (email.isNull()) {
    System.out.println("email 字段存在，但值为 null");
} else {
    System.out.println("email: " + email.asText());
}

如果字段必须出现，可以使用 required("字段") 或 requireNonNull() 让 Jackson 在缺失或空值时抛出异常。选择哪一个取决于接口契约：required 只约束字段存在，显式 null 仍是一个存在的节点；requireNonNull 才会同时拒绝缺失和显式 null。

把三种状态落到 PATCH 更新策略

架构上可以把它看成一个三态输入协议，而不是一个简单的“有值/没值”开关：missing 表示不修改，explicit null 表示清空，普通值表示覆盖。这样接口层先完成状态判断，领域层只接收明确的更新意图。

static void applyNicknamePatch(JsonNode patch, User user) {
    // 缺失字段代表本次 PATCH 不触碰 nickname。
    if (!patch.has("nickname")) {
        return;
    }

    JsonNode value = patch.get("nickname");
    if (value.isNull()) {
        // 显式 null 是清空指令，是否允许清空由业务规则决定。
        user.setNickname(null);
        return;
    }

    // 普通值进入格式校验后再写入，避免把任意节点直接转成字符串。
    if (!value.isTextual()) {
        throw new IllegalArgumentException("nickname 必须是字符串或 null");
    }
    user.setNickname(value.textValue());
}

需要“非空值”时可以用 hasNonNull；需要“字段出现”时必须用 has。这两个 API 的差别很小，却决定了更新接口能否表达“保持原值”和“主动清空”这两个动作。

常见问题

为什么 get("x") == null 不能判断 JSON 值为 null？ 因为字段缺失时才返回 Java null，显式 JSON null 会返回 NullNode，应该调用节点的 isNull()。

path("x").asText() 能直接判断字段是否存在吗？ 不建议。缺失节点的转换结果可能是空字符串或默认值，先判断 isMissingNode()，再决定是否读取文本。

什么时候用 DTO 而不是 JsonNode？ 如果接口不需要区分缺失和显式 null，DTO 更简洁；如果更新语义依赖三态输入，就在边界层保留 JsonNode 或显式的三态包装类型。

总结：has 看字段是否出现，isNull 看出现后的值是否为 JSON null，isMissingNode 识别 path 链上的缺失路径。把三者分开，Jackson 的 JSON 空字段就不会再被误判。