Spring Boot Bean注入失败本质两类：容器无Bean或存在歧义。需检查扫描路径、注解有效性、接口多实现匹配、多模块包覆盖、注入时机与作用域兼容性。

Spring Boot 中 Bean 注入失败，本质就两类：容器里压根没有这个 Bean，或者容器里有但 Spring 不知道该选哪一个、或没法完成装配。下面从高频、可操作的角度，帮你快速定位和解决。

检查 Bean 是否被 Spring 扫描并注册

这是最常见也最容易忽略的一环。Spring Boot 默认只扫描启动类所在包及其子包，其他路径的类即使加了 @Service、@Repository 等注解，也不会进容器。

• 确认目标类是否加了有效注解（如 @Service、@Mapper、@Component），且不是拼写错误（比如写成 @Servcie）
• 查看启动类位置：如果启动类在 com.example.app，那 com.example.util 或 com.common 就不会被扫到
• 补救方式：在启动类上加 @ComponentScan(basePackages = {"com.example.app", "com.common"})，注意必须显式包含原包，否则默认扫描会失效
• 验证是否注册成功：启动时加 --debug 参数，Spring Boot 会输出 Condition Evaluation Report，里面能看到所有已注册的 Bean 名称

确认接口与实现类匹配是否明确

当一个接口有多个实现类（比如 UserService 有两个实现类 UserAServiceImpl 和 UserBServiceImpl），@Autowired 按类型注入就会失败，因为 Spring 不知道选谁。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• 报错典型提示：No qualifying bean of type 'xxx.UserService' available
• 解决方法一：用 @Qualifier("userAServiceImpl") 明确指定 Bean 名（注意名称是类名首字母小写）
• 解决方法二：在某个实现类上加 @Primary，表示优先选用它
• 解决方法三：改用 @Resource(name = "userAServiceImpl")，它是按名称注入，不依赖类型唯一性

排查多模块或外部依赖中 Bean 丢失

项目拆分成 common + service 模块时，common 里的 Bean 很容易“看不见”——尤其当你把 common install 到本地仓库后单独运行 service 模块，扫描路径没覆盖 common 的包，Bean 就消失了。

立即学习“Java免费学习笔记（深入）”；

• 检查 service 模块的启动类是否通过 @ComponentScan 或 @SpringBootApplication(scanBasePackages = {...}) 把 common 模块的包路径也纳入了
• 确认 common 模块的 jar 包中确实包含编译后的 class 文件（不是空 jar 或只含源码）
• 如果 common 是纯工具类、不含 Spring 注解，那就不能靠扫描；需在 service 模块的配置类中用 @Bean 手动注册

留意注入时机与作用域冲突

有些注入失败不是找不到 Bean，而是时机不对或作用域不兼容。

• 在 @PostConstruct 方法里直接使用未初始化完的依赖，可能为 null —— 应确保依赖字段已注入后再调用
• 把 prototype（原型）Bean 注入 singleton（单例）Bean 是允许的，但每次取到的都是新实例；若误以为是同一个对象，逻辑会出错
• 过滤器（Filter）、监听器（Listener）、拦截器（Interceptor）默认不受 Spring 管理，其中用 @Autowired 会失败；需用 @ServletComponentScan 或手动注入 ApplicationContext 获取 Bean