说到Spring Boot的依赖注入，很多开发者（包括我自己）都曾经在一个深夜对着屏幕发呆，看着那个红得刺眼的报错信息，心里一万只羊驼奔腾而过。”BeanNotFoundException”、”Could not autowire”——这些词汇在Java圈子里的影响力，大概仅次于”NPE”和”404”。
今天我想和你聊聊三个真实发生过的、让人头秃的Spring Boot Service和Mapper注入失败案例。不是那种教科书式的”配置没写对”，而是真正在项目中踩过的坑。希望能帮你在下次遇到类似问题时，少掉几根头发。
案例一：那个被遗忘在错误包路径下的Service
问题现场
这是一个典型的”明明写了注解，却死活注入不进去”的场景。我们的项目结构大概是这样：
com.example.project
├── ProjectApplication.java
├── config
│ └── MyBatisConfig.java
├── controller
│ └── UserController.java
├── service
│ └── UserService.java
├── mapper
│ └── UserMapper.java
└── entity
└── User.java
UserController里写着：
@RestController
@RequestMapping("/api/users")
public class UserController {
@Autowired
private UserService userService; // 这里报红了！
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}
}
IDE直接给你画了个红线，启动时报错：Field userService in com.example.project.controller.UserController required a bean of type 'com.example.project.service.UserService' that could not be found.
根本原因
第一眼看上去，UserService上加了@Service，包扫描路径也没错，为什么就是找不到？
问题的根源在于主应用类的包路径。我们的ProjectApplication.java是这样的：
package com.example; // 注意！这里只有两层
@SpringBootApplication
public class ProjectApplication {
public static void main(String[] args) {
SpringApplication.run(ProjectApplication.class, args);
}
}
而Service、Controller、Mapper都在com.example.project包下。Spring Boot的@SpringBootApplication默认会扫描主类所在包及其子包。主类在com.example，所以它会扫描com.example.*，但不会扫描到com.example.project.*，因为project是com.example的子包，这个逻辑是对的… 等等，让我重新理一下。
实际上，com.example的子包应该包括com.example.project。那问题出在哪？
原来，我们的项目是从一个老项目迁移过来的，迁移过程中不小心把主类从com.example.project.ProjectApplication改成了com.example.ProjectApplication，却忘了修改IDE的包结构。更糟糕的是， Maven的source根目录配置也跟着乱了。
解决方案
有两个选择：
方案A：把主类放回正确的包路径
package com.example.project; // 改回正确的包路径
@SpringBootApplication
public class ProjectApplication {
public static void main(String[] args) {
SpringApplication.run(ProjectApplication.class, args);
}
}
方案B：在@SpringBootApplication上显式指定扫描路径
package com.example;
@SpringBootApplication(scanBasePackages = "com.example.project")
public class ProjectApplication {
public static void main(String[] args) {
SpringApplication.run(ProjectApplication.class, args);
}
}
我推荐方案B，因为它更明确，不容易因为文件迁移而忘记调整包路径。而且，当你有多个模块时，这种显式声明能让你一眼看出Spring到底在扫什么。
教训
包路径问题往往是最容易被忽视的。建议在项目初始化时就确定好包命名规范，并且在CI/CD流水线中加入一个简单的检查——验证主类所在包是否能覆盖所有需要扫描的组件。
案例二：MyBatis Mapper代理”失联”的真相
问题现场
Service注入没问题了，但Service里的Mapper却注入失败了：
@Service
public class UserService {
@Autowired
private UserMapper userMapper; // 这里又报红了！
public User findById(Long id) {
return userMapper.selectById(id);
}
}
报错信息：No qualifying bean of type 'com.example.project.mapper.UserMapper' available
Mapper接口上明明加了@Mapper注解，启动类也加了@MapperScan，为什么还是找不到？
@Mapper // 加在接口上
public interface UserMapper {
User selectById(Long id);
}
启动类：
@MapperScan("com.example.project.mapper")
@SpringBootApplication
public class ProjectApplication {
// ...
}
根本原因
这里有一个常见的误区：@Mapper和@MapperScan是两种不同的注册方式，混用会导致冲突或遗漏。
更关键的是，我们的项目使用了多数据源配置。在MyBatisConfig中，我们手动注册了SqlSessionFactory，却没有正确配置Mapper的扫描：
@Configuration
public class MyBatisConfig {
@Bean
@Primary
public SqlSessionFactory sqlSessionFactory(@Qualifier("primaryDataSource") DataSource dataSource) throws Exception {
SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
factoryBean.setDataSource(dataSource);
// 这里漏掉了setMapperLocations！
return factoryBean.getObject();
}
}
当手动创建SqlSessionFactory时，Spring Boot的自动配置会被部分禁用。这意味着@MapperScan注解虽然存在，但可能不会按照预期工作，因为自动配置的MapperScannerConfigurer被跳过了。
另一个更隐蔽的问题：我们的Mapper接口位于一个独立的Maven模块中，而这个模块没有被主项目的@ComponentScan覆盖到。包扫描路径看起来是对的，但由于模块化设计，实际扫描范围被缩小了。
解决方案
第一步：确保Mapper接口能被扫描到
在多模块项目中，需要显式指定扫描路径：
@SpringBootApplication
@ComponentScan(basePackages = {
"com.example.project", // 主模块
"com.example.project.mapper" // Mapper模块，显式声明
})
@MapperScan("com.example.project.mapper")
public class ProjectApplication {
// ...
}
第二步：正确配置SqlSessionFactory
@Configuration
public class MyBatisConfig {
@Bean
@Primary
public SqlSessionFactory sqlSessionFactory(
@Qualifier("primaryDataSource") DataSource dataSource) throws Exception {
SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
factoryBean.setDataSource(dataSource);
// 关键：显式指定Mapper XML位置
factoryBean.setMapperLocations(
new PathMatchingResourcePatternResolver()
.getResources("classpath:mapper/**/*.xml")
);
// 关键：设置类型别名包，避免XML中类名找不到
factoryBean.setTypeAliasesPackage("com.example.project.entity");
return factoryBean.getObject();
}
}
第三步：移除多余的@Mapper注解
既然已经用了@MapperScan，就不需要在每个Mapper接口上加@Mapper了。保留一个就够了，避免混乱：
// 不要这样
@Mapper
public interface UserMapper { ... }
// 要这样
public interface UserMapper { ... }
或者，如果你更喜欢在每个Mapper上标记，那就不要用@MapperScan，让每个Mapper自己”说话”：
@Mapper
public interface UserMapper { ... }
@Mapper
public interface OrderMapper { ... }
这两种方式选一种，不要混用。
调试技巧
如果还是找不到Mapper，可以在启动类加一行调试代码，看看Spring容器里到底有哪些Bean：
public static void main(String[] args) {
ConfigurableApplicationContext context = SpringApplication.run(ProjectApplication.class, args);
// 调试：打印所有包含"Mapper"的Bean
String[] mapperBeans = context.getBeanNamesForAnnotation(Mapper.class);
System.out.println("Found Mapper beans: " + Arrays.toString(mapperBeans));
// 或者查看所有Bean
String[] allBeans = context.getBeanDefinitionNames();
Arrays.stream(allBeans)
.filter(name -> name.toLowerCase().contains("mapper"))
.forEach(System.out::println);
}
这行代码能立刻告诉你，你的Mapper到底有没有被注册到Spring容器中。如果没有输出，说明扫描根本没生效；如果有输出但名字奇怪，说明包路径有问题。
案例三：事务注解与AOP代理的”爱恨情仇”
问题现场
这个案例最刁钻。Service和Mapper都注入成功了，代码也能跑，但在调用Service方法时，抛出了：
org.springframework.beans.factory.BeanCreationException:
Error creating bean with name 'userService':
Invocation of init method failed;
nested exception is java.lang.IllegalStateException:
Failed to introspect annotated methods
更诡异的是，同样的代码在开发环境能跑，在测试环境就挂了。
根本原因
让我们看看UserService的代码：
@Service
public class UserService {
@Autowired
private UserMapper userMapper;
@Transactional
public User createUser(User user) {
// 业务逻辑...
userMapper.insert(user);
return user;
}
@Transactional(readOnly = true)
public User findById(Long id) {
return userMapper.selectById(id);
}
}
乍看之下，这代码没有问题。@Service、@Autowired、@Transactional都用对了位置。
但问题出在类的可见性和代理机制上。
Spring的@Transactional是通过AOP代理实现的。默认情况下，Spring使用JDK动态代理（当目标类实现了接口时）或CGLIB代理（当目标类没有实现接口时）。代理对象和原始对象不是同一个东西。
在我们的案例中，UserService没有实现任何接口，所以Spring会使用CGLIB生成代理。但CGLIB代理有一个前提：目标类必须是可被子类化的。也就是说，它不能是final的，也不能有final方法。
检查代码，发现UserService本身不是final，但有一个依赖的类UserMapperImpl是final的（因为我们用了MyBatis的默认实现）。这不是直接原因，但提示我们往这个方向思考。
真正的罪魁祸首是包私有构造函数和Spring的初始化顺序。
我们的UserService有一个自定义的初始化方法：
@Service
public class UserService {
@Autowired
private UserMapper userMapper;
// 这个@PostConstruct在代理创建之前执行，但此时userMapper可能还是null
@PostConstruct
public void init() {
if (userMapper == null) {
throw new IllegalStateException("UserMapper not injected!");
}
}
@Transactional
public User createUser(User user) {
return userMapper.insert(user);
}
}
问题是：@PostConstruct在Spring Bean的初始化阶段执行，但此时AOP代理可能还没有完全创建好。如果@PostConstruct方法里访问了需要代理的方法，或者依赖了代理状态，就会出问题。
另一个更常见的原因：循环依赖。
@Service
public class UserService {
@Autowired
private OrderService orderService; // 注入了OrderService
}
@Service
public class OrderService {
@Autowired
private UserService userService; // 又注入了UserService
}
Spring默认不允许循环依赖（除非开启allow-circular-references）。当Spring尝试创建UserService时，发现它需要OrderService；创建OrderService时，发现它需要UserService… 死锁。
解决方案
方案A：打破循环依赖
使用@Lazy注解延迟加载其中一个依赖：
@Service
public class UserService {
@Autowired
@Lazy // 延迟注入，打破循环
private OrderService orderService;
}
或者，重构代码，把共同依赖抽取到一个新的Service中：
@Service
public class UserOrderService {
// 把UserService和OrderService共用的逻辑放在这里
}
方案B：避免在@PostConstruct中做依赖检查
@PostConstruct应该只做纯粹的初始化工作，不要依赖其他Bean的状态：
@PostConstruct
public void init() {
// 只做纯初始化，比如设置默认值
this.someDefault = "default";
// 不要检查依赖是否注入！
}
如果确实需要检查依赖，用构造函数注入代替：
@Service
public class UserService {
private final UserMapper userMapper;
// 构造函数注入，Spring会在创建Bean时确保依赖已就绪
public UserService(UserMapper userMapper) {
this.userMapper = userMapper;
}
}
方案C：检查类是否被错误地标记为final
用IDE全局搜索final class UserService，如果有，去掉final关键字。CGLIB代理无法代理final类。
方案D：显式启用CGLIB代理
在application.yml中：
spring:
aop:
proxy-target-class: true
这强制Spring使用CGLIB而不是JDK动态代理，确保所有Bean都能被正确代理。
调试技巧
如果怀疑是循环依赖，启动时加上这个参数：
java -jar app.jar --debug
Spring会打印详细的Bean创建顺序和依赖图。你都能看到哪个Bean在等待哪个Bean，一目了然。
另一个实用的技巧：临时注释掉所有@Transactional注解，看看问题是否消失。如果消失，说明问题出在AOP代理上；如果还在，说明问题出在Bean注入本身。
总结：构建可维护的注入架构
这三个案例虽然表现不同，但核心问题都指向同一个方向：Spring的Bean生命周期和代理机制没有完全理解。
以下是一些实用的最佳实践，帮助你在项目初期就避免这些问题：
1. 包结构清晰化
com.company.project
├── ProjectApplication.java # 主类，放在根包
├── config # 配置类
├── controller # 控制器
├── service # 服务层
│ └── impl # 服务实现（如果有）
├── mapper # MyBatis Mapper接口
├── entity # 实体类
└── dto # 数据传输对象
主类放在根包下，确保它能扫描到所有子包。
2. 依赖注入风格统一
推荐使用构造函数注入而不是字段注入：
// 推荐：构造函数注入
@Service
public class UserService {
private final UserMapper userMapper;
private final OrderMapper orderMapper;
public UserService(UserMapper userMapper, OrderMapper orderMapper) {
this.userMapper = userMapper;
this.orderMapper = orderMapper;
}
}
// 不推荐：字段注入（隐藏依赖，难以测试）
@Service
public class UserService {
@Autowired
private UserMapper userMapper;
}
构造函数注入的好处是：依赖关系一目了然，而且Spring会在创建Bean时就验证所有依赖是否可用，而不是等到方法调用时才报错。
3. MyBatis配置规范
@Configuration
@MapperScan(basePackages = "com.company.project.mapper",
sqlSessionFactoryRef = "sqlSessionFactory")
public class MyBatisConfig {
@Bean
public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
factory.setDataSource(dataSource);
factory.setMapperLocations(
new PathMatchingResourcePatternResolver()
.getResources("classpath:mapper/**/*.xml")
);
factory.setTypeAliasesPackage("com.company.project.entity");
return factory.getObject();
}
}
4. 单元测试验证注入
写一个简单的测试，验证所有关键的Bean都能被注入：
@SpringBootTest
class InjectionTest {
@Autowired
private UserService userService;
@Autowired
private UserMapper userMapper;
@Test
void contextLoads() {
// 如果这里不抛异常，说明基本注入没问题
assertThat(userService).isNotNull();
assertThat(userMapper).isNotNull();
}
}
这个测试虽然简单，但能catch住80%的注入问题。
5. 使用IDE插件辅助
IntelliJ IDEA的”Spring Boot Support”插件会在你创建Spring项目时自动生成正确的包结构和配置。如果遇到问题，可以检查插件是否生成了正确的application.properties或application.yml。
最后的话
依赖注入问题之所以让人头疼，是因为它们往往发生在”看起来没问题”的代码里。包路径差一级、注解放错位置、循环依赖悄悄形成——这些问题的共同特点是：编译能通过，但运行时炸锅。
我的建议是：在项目初期就把包结构和依赖关系理清楚，用构造函数注入代替字段注入，写几个简单的集成测试来验证Bean的可用性。这样，当问题真正出现时，你至少有线索可循，而不是在一片红海中盲目搜索。
记住，Spring是一个强大的框架，但它不会替你思考。理解它的底层机制——Bean生命周期、AOP代理、包扫描规则——比记住一百个注解更有用。
下次再遇到注入失败，先别急着改代码。问自己三个问题：
- 这个Bean到底有没有被Spring扫描到？
- 它的依赖有没有循环？
- 代理机制有没有干扰到我的代码？
这三个问题能帮你定位90%的注入问题。剩下10%，再去查日志、看文档、问同事。
希望这些案例能帮到你。如果还有其他的坑，欢迎在评论区分享，我们一起避坑。