Jackson库中实现JSON字段的单向读写控制

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:

  

  Tanka

  具备AI长期记忆的下一代团队协作沟通工具

  110

  查看详情
  • 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开发者都至关重要。

以上就是Jackson库中实现JSON字段的单向读写控制的详细内容，更多请关注php中文网其它相关文章！