Jackson Databind 中 Java Record 的 READ_ONLY 属性反序列化问题解析

在 Jackson Databind 2.18.x 版本中，开发者在使用 Java Record 类型配合 @JsonProperty(access = READ_ONLY) 注解时遇到了一个意外的异常问题。本文将深入分析该问题的技术背景、产生原因及解决方案。

问题现象

当开发者定义如下 Record 类型时：

record Dummy(
    @JsonProperty(value = "a", access = READ_ONLY) String a,
    @JsonProperty(value = "b", access = READ_ONLY) String b
) {}

在 2.18.x 版本中执行反序列化操作时，会抛出 InvalidDefinitionException 异常，提示存在重复的 creator 属性 "b"。而在 2.18 之前的版本中，虽然不会抛出异常，但 READ_ONLY 的语义并未被正确遵守。

技术背景

Java Record 特性

Java 14 引入的 Record 类型是一种特殊的数据载体类，其组件（components）默认就是不可变的字段。Jackson 从 2.12 版本开始支持 Record 类型的序列化/反序列化。

@JsonProperty.access 语义

Jackson 的 @JsonProperty 注解中的 access 属性用于控制属性的访问权限：

• READ_ONLY：只能读取（序列化），不能写入（反序列化）
• WRITE_ONLY：只能写入（反序列化），不能读取（序列化）

问题根源

经过 Jackson 开发团队分析，这个问题源于 2.18 版本中对 Record 类型处理逻辑的调整。具体表现为：

1. 参数名处理冲突：当 @JsonProperty.value 显式指定与 Record 组件名相同的值时，2.18.x 版本会在内部创建重复的参数绑定
2. 版本行为差异：
   • 2.14-2.17：静默忽略 READ_ONLY 设置，仍会反序列化字段值
   • 2.18.0-2.18.3：抛出重复属性异常
   • 2.18.4+/2.19+：正确处理为传递 null 值

解决方案

临时解决方案

对于 2.18.0-2.18.3 版本，可以移除冗余的 value 属性：

record Dummy(
    @JsonProperty(access = READ_ONLY) String a,
    @JsonProperty(access = READ_ONLY) String b
) {}

长期解决方案

升级到 Jackson Databind 2.18.4 或 2.19.0 及以上版本，这些版本已修复该问题。

设计建议

根据 Jackson 团队的说明，开发者可能需要重新考虑属性访问控制的设计：

• 如果目标是"客户端可写但服务器端只读"，应使用 WRITE_ONLY 而非 READ_ONLY
• 2.19 版本新增的 MapperFeature.INVERSE_READ_WRITE_ACCESS 可以交换两者的语义

最佳实践

1. 对于 Record 类型，避免同时使用 @JsonProperty.value 和组件同名
2. 明确区分序列化/反序列化方向的需求，正确选择 READ_ONLY/WRITE_ONLY
3. 在 OpenAPI 等代码生成场景中，注意生成的注解是否符合实际需求

总结

这个问题展示了 Jackson 在处理现代 Java 特性时的复杂性。Record 类型与注解的组合使用需要特别注意语义一致性。开发者应当：

• 了解所用 Jackson 版本的具体行为
• 明确属性访问控制的真实需求
• 及时更新到修复版本以获得预期行为

Jackson 团队已确认该问题将在 2.18.4 和 2.19.0 版本中修复，届时 Record 类型配合 READ_ONLY 注解将能正确传递 null 值而非抛出异常。