Jackson jar包常见技术问题： **如何解决Jackson序列化循环引用问题？**

Question

在使用 Jackson 进行 Java 对象序列化为 JSON 的过程中，**循环引用（Circular Reference）** 是一个常见且容易引发异常的问题。当两个或多个对象之间存在相互引用关系时，Jackson 默认会抛出 `java.lang.StackOverflowError` 或 `JsonProcessingException`，导致序列化失败。 例如，用户对象（User）关联部门对象（Department），而部门对象又反过来引用用户列表，这种结构很容易造成无限递归。 解决该问题的常用方法包括： 1. 使用 `@JsonIgnore` 注解手动忽略某一方的序列化； 2. 使用 `@JsonManagedReference` 和 `@JsonBackReference` 控制父子关系的序列化方向； 3. 启用 Jackson 的 `ObjectMapper` 配置，通过 `enable(SerializationFeature.FAIL_ON_EMPTY_BEANS)` 或自定义 `Jackson2ObjectMapperBuilderCustomizer` 来处理循环引用。 掌握这些技巧可有效避免 Jackson 在处理复杂对象图时出现栈溢出或死循环。

Answer 1

一、Jackson 序列化中的循环引用问题概述

在 Java 开发中，使用 Jackson 进行对象序列化为 JSON 是一种常见做法。然而，当对象之间存在相互引用关系时，就可能引发循环引用（Circular Reference）问题。

例如，一个典型的场景是用户对象（User）关联部门对象（Department），而部门对象又包含用户列表：

public class User {
    private String name;
    private Department department;
    // getters and setters
}

public class Department {
    private String name;
    private List<User> users = new ArrayList<>();
    // getters and setters
}
    

这种双向引用结构会导致 Jackson 在序列化过程中无限递归，最终抛出 `StackOverflowError` 或 `JsonProcessingException`。

二、分析循环引用的成因与影响

Jackson 默认采用深度优先的方式遍历对象图进行序列化。当遇到循环引用时，它无法判断是否已访问过某个对象，从而进入无限递归，最终导致栈溢出。

以下是常见的异常堆栈信息示例：

com.fasterxml.jackson.core.JsonProcessingException: Infinite recursion (StackOverflowError)
    at com.fasterxml.jackson.databind.ser.BeanPropertyWriter._findSubClassName(BeanPropertyWriter.java:764)
    ...
    

这类错误不仅影响接口响应，还可能导致整个服务崩溃，尤其是在 RESTful API 中频繁出现。

三、解决方案一：使用 @JsonIgnore 忽略字段

最简单直接的方法是在某一方使用 `@JsonIgnore` 注解来阻止序列化：

public class Department {
    private String name;

    @JsonIgnore
    private List<User> users;
    // getters and setters
}
    

该方式适用于不需要返回完整结构的场景，但缺点是会丢失部分数据，不适合需要完整展示的情况。

四、解决方案二：使用 @JsonManagedReference 与 @JsonBackReference

这两个注解用于明确父子关系，控制序列化方向：

• `@JsonManagedReference`：标记主引用，正常序列化；
• `@JsonBackReference`：标记反向引用，在序列化时被忽略。

修改类定义如下：

public class User {
    private String name;

    @JsonManagedReference
    private Department department;
    // getters and setters
}

public class Department {
    private String name;

    @JsonBackReference
    private List<User> users;
    // getters and setters
}
    

这种方式能保留双向关系的同时避免无限递归，适合具有明显父子结构的数据模型。

五、解决方案三：全局配置 ObjectMapper 避免循环引用

对于大型项目或复杂对象图，手动添加注解可能不够灵活。可以通过自定义 `ObjectMapper` 来统一处理：

@Bean
public Jackson2ObjectMapperBuilder jackson2ObjectMapperBuilder() {
    return new Jackson2ObjectMapperBuilder()
            .featuresToEnable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
            .featuresToEnable(SerializationFeature.INDENT_OUTPUT);
}
    

此外，还可以启用 Jackson 的 `enable()` 方法来设置循环引用行为：

ObjectMapper mapper = new ObjectMapper();
mapper.enable(SerializationFeature.FAIL_ON_EMPTY_BEANS);
    

注意：虽然这种方式可以防止程序崩溃，但并不能真正解决循环引用问题，只是让 Jackson 更“宽容”地处理。

六、进阶方案：使用 Jackson 的 Object Identity 支持

Jackson 提供了 `@JsonIdentityInfo` 注解，通过标识符机制实现对象去重和引用管理：

@JsonIdentityInfo(generator = ObjectIdGenerators.PropertyGenerator.class, property = "id")
public class User {
    private Long id;
    private String name;
    private Department department;
    // getters and setters
}
    

这样，Jackson 在序列化时会记录每个对象的 ID，并在再次遇到相同对象时输出其 ID 而非重复内容，有效避免无限递归。

七、综合对比与选择建议

方法	优点	缺点	适用场景
@JsonIgnore	简单易用	丢失数据	无需展示反向引用字段
@JsonManagedReference / @JsonBackReference	保留双向结构，控制序列化方向	需明确父子关系	有清晰父子层级的对象模型
ObjectMapper 全局配置	统一处理，减少代码侵入性	不能彻底解决循环引用	快速修复线上问题
@JsonIdentityInfo	支持复杂对象图，避免重复	增加 JSON 输出复杂度	需维护对象唯一标识的场景

开发者应根据具体业务需求和技术架构选择合适的策略。