Spring Boot 循环依赖问题解决方案笔记（基于电商系统示例）

最新推荐文章于 2026-06-20 12:58:49 发布

原创最新推荐文章于 2026-06-20 12:58:49 发布 · 2.1k 阅读

13 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

SpringBoot

1. 问题背景

以一个电商系统为例子，Spring Boot 应用启动时抛出了循环依赖（Circular Dependency）异常，错误信息如下：

***************************
APPLICATION FAILED TO START
***************************

Description:

The dependencies of some of the beans in the application context form a cycle:

   orderController
┌─────┐
|  orderServiceImpl
↑     ↓
|  userServiceImpl
└─────┘

Action:

Relying upon circular references is discouraged and they are prohibited by default. Update your application to remove the dependency cycle between beans. As a last resort, it may be possible to break the cycle automatically by setting spring.main.allow-circular-references to true.

1.1 问题描述

循环依赖路径：
- OrderController 依赖 OrderServiceImpl。
- OrderServiceImpl 依赖 UserServiceImpl。
- UserServiceImpl 依赖 OrderServiceImpl。
- 形成闭环：OrderServiceImpl → UserServiceImpl → OrderServiceImpl。
Spring 的行为：
- Spring 在创建 Bean 时需要解析依赖。
- 由于循环依赖，Spring 无法完成 Bean 的创建，抛出异常。
Spring Boot 版本影响：
- Spring Boot 2.6 之前，默认允许循环依赖（通过代理模式解决）。
- Spring Boot 2.6 及之后，默认禁止循环依赖（spring.main.allow-circular-references 默认为 false）。

2. 问题分析

2.1 依赖关系分析

OrderController：

注入 OrderService：

@RestController
public class OrderController {
    @Autowired
    private OrderService orderService;
}

OrderServiceImpl：

依赖 UserService（用于获取用户信息）：

@Service
public class OrderServiceImpl implements OrderService {

    @Autowired
    private OrderMapper orderMapper;

    @Autowired
    private UserService userService;

    @Override
    public OrderVO createOrder(OrderVO orderVO) {
        // 获取用户信息
        UserEntity user = userService.findById(orderVO.getUserId());
        if (user == null) {
            throw new RuntimeException("用户不存在");
        }

        OrderEntity order = new OrderEntity();
        BeanUtils.copyProperties(orderVO, order);
        order.setUserName(user.getName());
        orderMapper.insert(order);

        return orderVO;
    }
}

UserServiceImpl：

依赖 OrderService（用于发送通知时查询用户最近的订单信息）：

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;

    @Autowired
    private OrderService orderService;

    @Override
    public UserEntity findById(String userId) {
        UserEntity user = userMapper.selectById(userId);
        if (user != null) {
            // 查询用户最近的订单并发送通知
            OrderEntity latestOrder = orderService.findLatestOrderByUserId(userId);
            if (latestOrder != null) {
                System.out.println("用户 " + user.getName() + " 的最近订单: " + latestOrder.getId());
            }
        }
        return user;
    }

    // 模拟方法
    public void sendNotification(String userId, String message) {
        System.out.println("发送通知给用户 " + userId + ": " + message);
    }
}

OrderMapper 和 UserMapper：

假设为 MyBatis-Plus 的 Mapper 接口：

@Mapper
public interface OrderMapper extends BaseMapper<OrderEntity> {
    OrderEntity findLatestOrderByUserId(@Param("userId") String userId);
}

@Mapper
public interface UserMapper extends BaseMapper<UserEntity> {
}

2.2 循环依赖的成因

OrderServiceImpl 需要 UserService 来获取用户信息（userService.findById）。
UserServiceImpl 需要 OrderService 来查询用户最近的订单（orderService.findLatestOrderByUserId），以便发送通知。
这种双向依赖形成了循环。

3. 解决方案

Spring 建议通过重构代码消除循环依赖，而不是依赖于允许循环依赖的配置。以下是几种解决方案：

3.1 方案 1：重构依赖关系（推荐）

目标：
- 打破 OrderServiceImpl 和 UserServiceImpl 之间的循环依赖。
方法：
- 移除 UserServiceImpl 对 OrderServiceImpl 的依赖。
- 直接注入 OrderMapper，通过 Mapper 查询订单信息。

实现：

修改 UserServiceImpl：

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;

    @Autowired
    private OrderMapper orderMapper; // 直接注入 Mapper

    @Override
    public UserEntity findById(String userId) {
        UserEntity user = userMapper.selectById(userId);
        if (user != null) {
            // 直接通过 Mapper 查询用户最近的订单
            OrderEntity latestOrder = orderMapper.findLatestOrderByUserId(userId);
            if (latestOrder != null) {
                System.out.println("用户 " + user.getName() + " 的最近订单: " + latestOrder.getId());
            }
        }
        return user;
    }

    public void sendNotification(String userId, String message) {
        System.out.println("发送通知给用户 " + userId + ": " + message);
    }
}

优点：
- 符合依赖倒挂原则（Service 层不直接依赖其他 Service，而是通过 Mapper 访问数据）。
- 简单直接，彻底消除循环依赖。
缺点：
- 如果 OrderServiceImpl 中有复杂的业务逻辑（例如缓存、权限检查），直接使用 Mapper 会绕过这些逻辑。

3.2 方案 2：使用 `@Lazy` 注解

目标：
- 通过延迟加载的方式，暂时解决循环依赖问题。
方法：
- 在 UserServiceImpl 中，将 OrderService 的注入标记为 @Lazy。

实现：

修改 UserServiceImpl：

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;

    @Autowired
    @Lazy
    private OrderService orderService;

    @Override
    public UserEntity findById(String userId) {
        UserEntity user = userMapper.selectById(userId);
        if (user != null) {
            OrderEntity latestOrder = orderService.findLatestOrderByUserId(userId);
            if (latestOrder != null) {
                System.out.println("用户 " + user.getName() + " 的最近订单: " + latestOrder.getId());
            }
        }
        return user;
    }

    public void sendNotification(String userId, String message) {
        System.out.println("发送通知给用户 " + userId + ": " + message);
    }
}

原理：
- @Lazy 注解告诉 Spring 在第一次使用 orderService 时再创建 Bean，而不是在 UserServiceImpl 初始化时立即创建。
优点：
- 代码改动小，适合临时解决。
缺点：
- 只是治标不治本，循环依赖仍然存在，可能隐藏设计问题。

3.3 方案 3：提取公共服务

目标：
- 将通知逻辑提取到一个独立的服务中，减少 Service 之间的直接依赖。
方法：
- 创建 NotificationService，专门负责通知逻辑。
- UserServiceImpl 依赖 NotificationService，而不是 OrderServiceImpl。

实现：

创建 NotificationService：

@Service
public class NotificationService {

    @Autowired
    private OrderMapper orderMapper;

    public void sendOrderNotification(String userId, String userName) {
        OrderEntity latestOrder = orderMapper.findLatestOrderByUserId(userId);
        if (latestOrder != null) {
            System.out.println("用户 " + userName + " 的最近订单: " + latestOrder.getId());
        }
    }
}

修改 UserServiceImpl：

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;

    @Autowired
    private NotificationService notificationService;

    @Override
    public UserEntity findById(String userId) {
        UserEntity user = userMapper.selectById(userId);
        if (user != null) {
            notificationService.sendOrderNotification(userId, user.getName());
        }
        return user;
    }

    public void sendNotification(String userId, String message) {
        System.out.println("发送通知给用户 " + userId + ": " + message);
    }
}

优点：
- 提高了代码的可维护性和复用性，通知逻辑可以被其他服务复用。
- 彻底消除循环依赖。
缺点：
- 需要新增一个服务类，增加了代码量。

3.4 方案 4：允许循环依赖（不推荐）

目标：
- 临时解决循环依赖问题，允许 Spring 处理循环依赖。
方法：
- 在 application.properties 或 application.yml 中设置：
```
spring.main.allow-circular-references=true
```
原理：
- Spring 通过代理模式解决循环依赖。
优点：
- 改动最小，适合快速验证。
缺点：
- 掩盖了设计问题，可能导致后续维护困难。
- 不符合 Spring 的最佳实践。

4. 推荐方案

优先推荐：方案 1（重构依赖关系）
- 直接通过 OrderMapper 查询订单信息，移除 UserServiceImpl 对 OrderServiceImpl 的依赖。
- 简单直接，符合依赖倒挂原则。
次优选择：方案 3（提取公共服务）
- 如果通知逻辑在多个地方使用，提取 NotificationService 是一个更好的设计。
- 提高了代码的可维护性和复用性。
不推荐：方案 4（允许循环依赖）
- 只是临时解决方案，可能隐藏设计问题。

5. 学习总结

循环依赖的成因：
- Service 之间双向依赖（例如 OrderServiceImpl 和 UserServiceImpl 互相依赖）。
- Spring Boot 2.6 及之后默认禁止循环依赖。
解决方法：
- 重构依赖关系：通过 Mapper 直接访问数据，移除 Service 之间的依赖。
- 使用 @Lazy：延迟加载依赖，临时解决。
- 提取公共服务：将共享逻辑提取到独立服务中。
- 允许循环依赖：设置 spring.main.allow-circular-references=true（不推荐）。
最佳实践：
- 避免 Service 之间直接依赖，优先通过 Mapper 访问数据。
- 如果需要共享逻辑，提取公共服务或工具类。
- 编写单元测试，确保重构后功能正常。

7. 补充

代码设计：
- 遵循单一职责原则（SRP），避免 Service 之间耦合过高。
- 使用依赖倒挂原则（DIP），Service 层依赖 Mapper 而不是其他 Service。
测试：
- 编写单元测试和集成测试，确保重构后功能正常。
- 模拟循环依赖场景，验证解决方案的有效性。
工具：
- 使用 Spring 的依赖分析工具（例如 spring-boot-actuator）查看 Bean 依赖关系。
- 在 IDE 中使用依赖图工具（如 IntelliJ IDEA 的 Dependency Matrix）分析循环依赖。