1. 引言：JSON字段读写分离的需求
在构建RESTful API时，我们经常会遇到这样的场景：某些数据字段在从客户端接收（反序列化）JSON时是必需的，我们需要读取并处理它们；但在服务器向客户端发送响应（序列化）JSON时，这些字段却不应包含在输出中。
例如，一个产品实体可能包含一个 id 字段。当客户端提交一个新产品或更新产品信息时，这个 id 字段可能用于内部验证或关联现有数据。然而，在服务器返回产品详情时，该 id 可能由服务器内部管理，不希望或不需要回传给客户端，以简化响应结构或遵循特定的API契约。
传统的Jackson注解如 @JsonIgnore 可以完全忽略一个字段，使其在序列化和反序列化时都不被处理。但这无法满足我们对字段进行“只读”（反序列化时读取，序列化时忽略）或“只写”（反序列化时忽略，序列化时包含）的细粒度控制需求。为了解决这一问题，Jackson提供了更强大的机制。
2. 解决方案：@JsonProperty的access属性
Jackson库通过 @JsonProperty 注解的 access 属性，为我们提供了对字段读写行为的精确控制。该属性接受 JsonProperty.Access 枚举类型的值，允许我们定义字段在序列化和反序列化过程中的可见性。
核心枚举值及其作用如下：
-
JsonProperty.Access.WRITE_ONLY:
- 反序列化 (JSON -> Java对象)：该字段会被读取并写入Java对象。
- 序列化 (Java对象 -> JSON)：该字段将被忽略，不会出现在输出的JSON字符串中。
- 应用场景：最适合本文开头描述的需求，例如，需要接收但无需回传的ID、密码等。
-
JsonProperty.Access.READ_ONLY:
- 反序列化 (JSON -> Java对象)：该字段将被忽略，不会从JSON中读取。
- 序列化 (Java对象 -> JSON)：该字段会被读取并包含在输出的JSON字符串中。
- 应用场景：适用于由服务器生成且客户端只读的字段，例如创建时间、最后更新时间、只读的计算属性等。
-
JsonProperty.Access.READ_WRITE:
- 反序列化 & 序列化：该字段在两个方向上都可见并被处理。
- 应用场景：这是默认行为，适用于大多数常规字段。
-
JsonProperty.Access.AUTO:
- Jackson会根据字段的getter/setter方法自动推断其访问权限。通常与 READ_WRITE 行为一致，除非有其他注解明确指定。
3. 实践示例
下面通过一个具体的Java实体类和使用Jackson ObjectMapper 的示例，演示如何利用 JsonProperty.Access.WRITE_ONLY 实现字段的单向控制。
3.1 Java实体类定义
我们定义一个 Product 类，其中 id 字段被标记为 WRITE_ONLY，而 name 字段保持默认的读写行为。
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonProperty.Access;
public class Product {
// id 字段只在反序列化时写入，序列化时忽略
@JsonProperty(access = Access.WRITE_ONLY)
public String id;
// name 字段默认是 READ_WRITE，双向处理
public String name;
// 构造函数
public Product() {}
public Product(String id, String name) {
this.id = id;
this.name = name;
}
// Getter 和 Setter 方法
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
@Override
public String toString() {
return "Product{id='" + id + "', name='" + name + "'}";
}
}3.2 使用示例代码
接下来，我们使用 ObjectMapper 进行反序列化和序列化操作，观察 id 字段的行为。
import com.fasterxml.jackson.databind.ObjectMapper;
public class JacksonAccessDemo {
public static void main(String[] args) throws Exception {
ObjectMapper mapper = new ObjectMapper();
// 模拟接收到的JSON字符串，包含id和name
String incomingJson = """
{
"id": "prod123",
"name": "Widget A"
}
""";
System.out.println("--- 反序列化 (JSON -> Object) ---");
// 1. 反序列化：将JSON字符串转换为Product对象
// 由于id被标记为WRITE_ONLY，它将在反序列化时被正确读取并赋值给Product对象的id字段
Product product = mapper.readValue(incomingJson, Product.class);
System.out.println("反序列化后的Product对象: " + product.toString());
// 验证id是否被读取
System.out.println("Product对象中的ID: " + product.getId());
System.out.println("\n--- 序列化 (Object -> JSON) ---");
// 2. 序列化：将Product对象转换为JSON字符串
// 假设我们修改了name，但id保持不变（或由系统内部生成）
product.setName("Updated Widget A");
// 由于id被标记为WRITE_ONLY，它将在序列化时被忽略，不会出现在输出的JSON中
String outgoingJson = mapper.writeValueAsString(product);
System.out.println("序列化后的JSON字符串: " + outgoingJson);
}
}3.3 运行结果分析
运行上述 JacksonAccessDemo 类，你将看到以下输出：
--- 反序列化 (JSON -> Object) ---
反序列化后的Product对象: Product{id='prod123', name='Widget A'}
Product对象中的ID: prod123
--- 序列化 (Object -> JSON) ---
序列化后的JSON字符串: {"name":"Updated Widget A"}从输出中我们可以清晰地看到：
- 在反序列化阶段，id 字段 (prod123) 成功地从 incomingJson 中读取并赋值给了 product 对象的 id 属性。
- 在序列化阶段，尽管 product 对象的 id 属性仍然持有值 (prod123)，但由于 @JsonProperty(access = Access.WRITE_ONLY) 的作用，它在生成 outgoingJson 时被完全忽略，输出的JSON中只包含 name 字段。
这完美地实现了对 id 字段的单向控制：只在反序列化时写入对象，在序列化时从JSON中排除。
4. 注意事项与最佳实践
- 明确API契约： 在设计API时，应明确哪些字段是只读、只写或读写，并在API文档中详细注明，以避免客户端误解。
- 安全性考量： 对于敏感信息（如密码哈希、内部审计ID等），应始终使用 WRITE_ONLY 或 @JsonIgnore 来防止意外泄露。
- 代码可读性： 明确使用 Access 枚举值，增强代码的意图表达，让其他开发者一目了然地理解字段的JSON行为。
- 与@JsonIgnore的区别： 再次强调，@JsonIgnore 会在序列化和反序列化两个方向上完全忽略字段。而 access 属性提供了更细粒度的控制，允许我们选择性地在某个方向上处理字段。
- 构造函数与Setter： 确保当字段被标记为 WRITE_ONLY 时，反序列化过程能够通过公共的构造函数或Setter方法正确地将JSON值赋给Java对象的该字段。如果字段是私有的且没有Setter，Jackson可能无法反序列化。
- Jackson版本兼容性： 确保你使用的Jackson库版本支持 JsonProperty.Access 枚举。此功能在Jackson 2.x 版本中广泛可用。
5. 总结
@JsonProperty(access) 是Jackson库中一个非常强大且实用的特性，它允许开发者对JSON字段的序列化和反序列化行为进行精细控制。通过灵活运用 WRITE_ONLY 和 READ_ONLY 等访问模式，我们可以构建出更加健壮、安全且符合业务需求的API，有效管理数据流，避免不必要的信息泄露，并简化API响应结构。掌握这一特性对于任何使用Jackson进行JSON处理的Java开发者都至关重要。
