【技术底稿 37】Spring Boot 3.x 自动装配 “死锁” 排查：3 个注解实现条件化装配与 Mock 兜底

一、核心背景

正在开发 RAG 项目，生产环境依赖 MySQL + Redis + Milvus + 大模型 API。日常需要搭建本地零依赖 Demo 版本，用于前端快速联调。剔除所有外部中间件配置后，Spring Boot 启动直接报错：

自动装配缺失依赖 Bean，外部服务不可用导致实例创建失败
多层构造函数注入引发容器初始化阻塞

既定目标：

全程不改动任何核心业务代码
Demo 本地环境无依赖正常启动
线上生产环境运行逻辑不受任何影响

二、最终方案

表格

组件	生产模式	Demo 模式
DeepSeekAiChatFacadeImpl	✅ 正常注入	❌ 拒绝装配
MockAiChatFacadeImpl	❌ 拒绝装配	✅ 优先注入（@Primary）
SimpleRagWorkflow	正常直接注入	@Lazy 延迟代理注入

核心思路：条件注解管控 Bean 加载、@Lazy 破除启动注入阻塞、@Primary 兜底多实现优先级，一套注解完成双环境无缝切换。

三、踩坑实录与根因分析

坑 1：移除配置后，依旧强制装配依赖 Bean

报错信息：

text

复制代码

Parameter 1 of constructor in SimpleRagWorkflow required a bean of type AiChatFacade that could not be found

根因：业务层组件标注@Component，容器启动即刻实例化，逐级向下依赖大模型实现类，配置缺失直接导致启动终止。

解决方案：给生产业务实现类添加条件注解，仅生产环境生效。

java

运行

复制代码

@Component
@ConditionalOnExpression("'${ai.chat-mode}' != 'demo'")
public class DeepSeekAiChatFacadeImpl implements AiChatFacade {
    // 生产模式才加载
}

配置文件区分环境：

yaml

复制代码

ai.chat-mode: demo

坑 2：上层业务组件强依赖，屏蔽实现类依旧启动报错

根因：Spring 默认单例 Bean 在启动阶段完成所有构造器依赖注入，属于强绑定依赖，无法跳过。

解决方案 ：使用@Lazy实现延迟注入，启动仅注入代理对象，调用阶段才初始化真实实例。

java

运行

复制代码

@Component
@RequiredArgsConstructor
public class SimpleRagWorkflow {
    private final @Lazy AiChatFacade aiChatFacade;
}

坑 3：Demo 环境启动成功，接口调用无实例报错

根因：仅关闭生产实现，未提供本地替代实现，代理对象无实际执行载体。

解决方案：编写 Mock 模拟实现，反向条件匹配 + @Primary 优先加载。

java

运行

复制代码

@Component
@Primary
@ConditionalOnExpression("'${ai.chat-mode}' == 'demo'")
public class MockAiChatFacadeImpl implements AiChatFacade {
    @Override
    public String chat(String prompt) {
        return "【Demo模式】Mock响应：联调成功";
    }
}

坑 4：@ConditionalOnExpression 表达式书写失效

常见问题：缺少引号、无默认配置值、格式空格错误，造成条件判断错乱，双 Bean 共存或全部不加载。

标准规范写法：

java

运行

复制代码

@ConditionalOnExpression("'${ai.chat-mode:production}' != 'demo'")

补齐默认值，避免配置缺失引发启动异常。

四、固化铁律

优先使用条件注解管控组件加载，避免直接删改业务代码
构造器注入出现依赖阻塞，优先使用 @Lazy 延迟注入解决
多实现类场景，@Primary 快速指定默认兜底 Bean
条件表达式统一标准格式，配置项增加默认兜底值
生产实现与 Mock 实现条件互斥，保证单一环境唯一实例
核心 Bean 新增初始化日志，快速校验实际加载状态

五、迁移前后对比

表格

模式	启动耗时	外部依赖	业务功能
生产模式	约 8 秒	全量中间件 + 大模型	完整 RAG 业务流程
Demo 模式	1.7 秒	无任何外部依赖	Mock 模拟响应，满足联调

代码改动成本：新增 1 个 Mock 模拟实现类，2 个原有类追加注解，配置新增一行环境标识，核心业务代码零改动。

六、常用配置与注解速查

多环境分离配置

yaml

复制代码

---
spring:
  config:
    activate:
      on-profile: demo
ai:
  chat-mode: demo
---
spring:
  config:
    activate:
      on-profile: prod
ai:
  chat-mode: production

高频条件注解

java

运行

复制代码

// 按配置精准匹配
@ConditionalOnProperty(name = "ai.chat-mode", havingValue = "demo")

// 无指定Bean时加载
@ConditionalOnMissingBean

// 依赖指定Class存在才加载
@ConditionalOnClass

Bean 装配日志排查

bash

运行

复制代码

# 启动打印自动装配详情
java -jar xxx.jar --debug

# 日志级别精简排查
logging.level.org.springframework.boot.autoconfigure=DEBUG

七、底稿收尾

核心价值：3 个注解 + 1 个 Mock 类，零业务代码改动，实现生产 / Demo 双环境无缝切换。

本文为《技术底稿》系列第 37 篇，基于自研 RAG 项目实战复盘 Spring Boot 3.x 自动装配阻塞问题，用极简注解完成本地调试与线上生产环境隔离。整套方案无侵入、易落地、可直接复刻，完美解决后端项目本地零依赖联调痛点，规避多环境切换带来的各类启动异常。