1. 当SpringBoot遇上MyBatis为什么你的Mapper接口突然消失了刚接触SpringBoot整合MyBatis的开发者十有八九都遇到过这个让人抓狂的报错Consider defining a bean of type xxx.mapper.UserMapper in your configuration。我第一次看到这个错误时盯着屏幕足足愣了五分钟——明明UserMapper接口就好好地躺在项目里为什么Spring却说找不到这个bean这个报错的本质是Spring的依赖注入机制在闹脾气。当你在Controller中用Autowired注入Mapper接口时Spring会在容器里寻找对应的bean实例。如果找不到就会抛出这个错误。而问题的根源往往出在Mapper接口的扫描配置上。我见过最常见的三种翻车姿势用了MapperScan但路径写错比如把com.example写成com.exapmle同时使用Mapper和MapperScan导致冲突忘记配置MyBatis的mapper-locations导致XML映射文件没被加载2. Mapper vs MapperScan两种配置方式的深度对比2.1 Mapper注解的利与弊在接口上直接添加Mapper注解是最简单直白的方式Mapper public interface UserMapper { Select(SELECT * FROM user WHERE id#{id}) User findById(Long id); }优点简单明了每个Mapper自己声明身份适合小型项目Mapper数量较少的情况缺点每个Mapper接口都要加注解麻烦当Mapper分散在不同包时难以统一管理我曾经在一个老项目里看到过开发者为了省事直接在基础Mapper接口上加Mapper然后让其他Mapper继承它。这看似聪明实则埋下了隐患——Spring最终会创建多个相同类型的bean导致冲突。2.2 MapperScan的配置艺术MapperScan就像是MyBatis的雷达扫描仪可以批量注册指定包下的所有Mapper接口SpringBootApplication MapperScan(com.example.mapper) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }关键配置要点路径要精确到Mapper接口所在包支持通配符和多包扫描用数组形式可以和Configuration配合使用我推荐在application.properties中增加这个配置让扫描过程更透明mybatis.configuration.log-implorg.apache.ibatis.logging.stdout.StdOutImpl3. 那些年我们踩过的配置陷阱3.1 路径拼写错误最愚蠢也最常见上周还帮同事解决过一个典型caseMapperScan(com.exmple.mapper) // 注意是example不是exmple这种错误IDE不会报错项目能正常编译但运行时就会爆炸。我的排查建议是检查控制台输出的扫描日志用IDE的Find in Path确认包名拼写在测试类中尝试手动获取Mapper bean3.2 注解冲突双重注册的隐患理论上Mapper和MapperScan可以共存但实际项目中我强烈建议二选一。曾经遇到过这样的情况Mapper // 接口上 public interface UserMapper {...} SpringBootApplication MapperScan(com.example.mapper) // 又扫描一次 public class Application {...}这会导致相同接口被注册两次可能引起事务管理异常增加不必要的性能开销3.3 XML映射文件失踪事件即使接口扫描正确如果对应的XML文件没被加载同样会报错。正确的配置姿势mybatis.mapper-locationsclasspath*:mapper/**/*.xml特别注意classpath后面的*号表示包含所有jar包**表示任意子目录建议把XML放在resources/mapper目录下4. 从报错日志到解决方案实战排错指南4.1 解读错误日志的隐藏信息当看到这样的报错时Description: Field userMapper in com.example.controller.UserController required a bean of type com.example.mapper.UserMapper that could not be found.应该按这个顺序排查确认UserMapper接口是否存在检查扫描配置注解或XML验证数据源配置是否正确查看MyBatis是否加载了对应XML4.2 我的排错工具箱开启DEBUG日志logging.level.org.mybatisDEBUG logging.level.org.springframework.jdbcDEBUG验证Bean是否存在SpringBootTest class MybatisTest { Autowired private ApplicationContext context; Test void checkMapperBean() { assertNotNull(context.getBean(UserMapper.class)); } }检查SQL会话工厂Autowired private SqlSessionFactory sqlSessionFactory; Test void checkMappedStatements() { assertTrue(sqlSessionFactory.getConfiguration() .hasMapper(UserMapper.class)); }4.3 多模块项目的特殊处理对于多模块项目建议在主模块这样配置SpringBootApplication MapperScan({ com.module1.mapper, com.module2.mapper }) public class Application {...}或者在每个模块的配置类上单独声明Configuration MapperScan(com.module1.mapper) public class Module1Config {...}5. 最佳实践来自老司机的配置建议经过多个项目的实战我总结出这些经验单一配置原则整个项目统一使用Mapper或MapperScan不要混用包结构规范化src/main/java └── com.example ├── config ├── controller ├── service └── mapper // 所有Mapper接口放这里 src/main/resources └── mapper └── UserMapper.xml // XML文件对应存放测试先行在单元测试中验证Mapper是否可用MybatisTest AutoConfigureTestDatabase(replace NONE) class UserMapperTest { Autowired private UserMapper userMapper; Test void testSelect() { assertNotNull(userMapper.findById(1L)); } }版本兼容性检查确保SpringBoot、MyBatis和MyBatis-Spring版本匹配遇到诡异问题时尝试清理IDE的缓存并重新构建项目有时候只是IDE抽风了