本文介绍如何通过自定义 DeserializationProblemHandler，在禁用 FAIL_ON_UNKNOWN_PROPERTIES 的前提下，捕获并记录所有 JSON 中存在的、目标 Java 类未声明的字段名，实现“静默忽略 + 可追溯审计”的反序列化策略。
本文介绍如何通过自定义 `deserializationproblemhandler`，在禁用 `fail_on_unknown_properties` 的前提下，捕获并记录所有 json 中存在的、目标 java 类未声明的字段名，实现“静默忽略 + 可追溯审计”的反序列化策略。
Jackson 默认在遇到未知 JSON 字段时会抛出 UnrecognizedPropertyException（当 FAIL_ON_UNKNOWN_PROPERTIES = true）。虽然可通过 objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false) 全局忽略，但这会导致问题“静默丢失”——你无法得知哪些字段被跳过了。为兼顾兼容性与可观测性，推荐使用 DeserializationProblemHandler 机制，在忽略的同时主动收集未知属性名。
核心思路是：继承 DeserializationProblemHandler，重写 handleUnknownProperty 方法，返回 true 表示“已处理，继续反序列化”，并在其中将 propertyName 记录到线程安全的容器（如 ThreadLocal<List<String>> 或外部日志/监控系统）中。
以下是一个生产就绪的示例实现：
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonDeserializer;
import com.fasterxml.jackson.databind.deser.DeserializationProblemHandler;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.DeserializationFeature;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
public class CollectingUnknownPropertyHandler extends DeserializationProblemHandler {
// 使用线程安全集合，避免并发反序列化时数据污染
private final List<String> collectedUnknownProperties = new CopyOnWriteArrayList<>();
@Override
public boolean handleUnknownProperty(
DeserializationContext ctxt,
JsonParser p,
JsonDeserializer<?> deserializer,
Object beanOrClass,
String propertyName) throws IOException {
collectedUnknownProperties.add(propertyName);
// 返回 true：表示该问题已被处理，反序列化流程继续
return true;
}
public List<String> getCollectedUnknownProperties() {
return new ArrayList<>(collectedUnknownProperties);
}
public void clear() {
collectedUnknownProperties.clear();
}
}使用方式如下：
ObjectMapper mapper = new ObjectMapper();
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
CollectingUnknownPropertyHandler handler = new CollectingUnknownPropertyHandler();
mapper.addHandler(handler);
// 示例 JSON：包含未知字段 "age" 和 "email"
String json = "{\"name\":\"Alice\",\"age\":30,\"email\":\"a@example.com\"}";
User user = mapper.readValue(json, User.class);
// 获取本次反序列化中发现的所有未知字段
List<String> unknowns = handler.getCollectedUnknownProperties();
System.out.println("Unknown properties detected: " + unknowns);
// 输出：Unknown properties detected: [age, email]
// 注意：如需支持多请求上下文隔离（如 Web 应用），建议结合 ThreadLocal 或 MDC 封装 handler⚠️ 重要注意事项：
- DeserializationProblemHandler 是 ObjectMapper 级别单例，不自动线程隔离。若在高并发场景（如 Spring MVC）中复用同一 ObjectMapper 实例，需确保 handler 实例本身是线程安全的（如上例使用 CopyOnWriteArrayList），或为每次请求创建独立 handler。
- 若需关联具体请求/业务上下文（如 traceId、接口路径），建议将 handler 封装为 ThreadLocal<CollectingUnknownPropertyHandler>，并在反序列化前后手动管理生命周期。
- 此机制仅捕获顶层对象及嵌套对象中直接声明的未知字段；若某嵌套类也配置了 FAIL_ON_UNKNOWN_PROPERTIES=false 且注册了 handler，则其未知字段也会被捕获——需确保 handler 被全局注册或显式传递。
总结：通过 DeserializationProblemHandler，你无需修改领域模型或引入额外注解（如 @JsonAnyGetter），即可低成本实现未知字段的“可观测式忽略”。它特别适用于微服务间 JSON 协议演进期的灰度兼容、API 兼容性审计或遗留系统字段治理场景。
