Jackson UnrecognizedPropertyException — 未知 JSON 字段

症状

遇到“Jackson UnrecognizedPropertyException — 未知 JSON 字段”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field “x”
• API 新增字段后解析失败
• 错误指向看似不重要的字段

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

jshell -q <<'EOF'
var m = new com.fasterxml.jackson.databind.ObjectMapper();
try { m.readValue("{\"a\":1,\"b\":2}", java.util.Map.class); } catch (Exception e) { System.out.println(e.getClass()); }
EOF

用具体负载复现失败，可看出类未声明哪个字段。

步骤 2

m.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

关闭严格检查可容忍额外字段；标注字段则可在需要处保持严格。

常见诱因（按出现频率排序）：

• JSON 含目标类中不存在的字段，且映射器为严格模式
• 字段名大小写不同，或用 snake_case 而类期望 camelCase
• 被忽略或改名的属性未标注 @JsonIgnoreProperties/@JsonProperty

根因

当 FAIL_ON_UNKNOWN_PROPERTIES 启用（默认）时，Jackson 对未知属性报错。任何未映射到类成员的 JSON 字段都会中止反序列化并抛 UnrecognizedPropertyException。

修复

可全局关闭 FAIL_ON_UNKNOWN_PROPERTIES 以获得前向兼容，给类加 @JsonIgnoreProperties(ignoreUnknown = true)，或补齐字段并用 @JsonProperty 映射名称。

注意：忽略未知属性会掩盖字段名拼写错误；在断言契约的测试中保留 FAIL_ON_UNKNOWN。

@JsonIgnoreProperties(ignoreUnknown = true) // tolerate new fields
public class User {
    @JsonProperty("user_id") // map snake_case
    private long id;
    private String name;
    // getters/setters
}

// or globally
ObjectMapper mapper = new ObjectMapper()
    .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

验证

重新解析同一负载并确认成功；补充测试断言已知字段被填充，并保留一个对真正畸形输入失败的测试。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。