先别急着百度“扫描不到Mapper”怎么办这个报错我太熟了。Spring Boot项目启动时控制台甩出一行红色异常提示某个Mapper接口的Bean找不到或者启动很顺利但第一个请求打过来就空指针再要么直接报Parameter xxxMapper not found这类问题在MyBatis整合Spring Boot的项目里简直能排进“一键劝退新手前三名”。我的建议是先别乱改配置理清Spring容器到底是怎么发现Mapper接口的再照着下面几条路子逐个排查基本都能在几分钟内定位解决。这篇文章适合刚起步的Spring Boot新人也适合接手老项目时突然遇到Mapper扫描异常的同学。我会把底层原理、代码结构和实际踩坑经验串在一起讲尽量不堆术语能给你一套可以照抄的解决方案。1. 先理解Spring Boot是怎么“看到”Mapper的1.1 典型报错长什么样扫不到Mapper注解其实不是只有一个错误形态。我见过的至少有这么几种启动时直接失败报Field userMapper in com.xxx.service.UserService required a bean of type com.xxx.mapper.UserMapper that could not be found。启动时不报错但调用Mapper方法时抛NullPointerException因为注入的Mapper对象是空的。方法调用时抛org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)这个严格来说不算扫描不到接口而是接口扫描到了但对应的SQL语句找不到。某个接口被扫描进去了但它不是Mapper启动时抛No MyBatis mapper was found in [com.xxxx] package或类似的扫描范围过大提示。这些情况的根因不完全一样但核心都指向同一个问题Mapper接口没有被正确注册到Spring容器里。1.2 谁在负责把接口变成Bean我们要明白Mapper接口本身是个接口接口是不能直接实例化的。MyBatis干的活是在运行时通过JDK动态代理生成一个代理对象把Mapper接口里的每个方法绑定到一条SQL语句注解SQL或者XML里的SQL然后把这个代理对象注册成Spring容器里的一个Bean让其他类能通过Autowired注入。那这个“生成代理并注册”的动作在Spring Boot里到底是谁触发的如果你用的是Mapper注解它是由MyBatis自动配置机制触发的。MyBatis和Spring Boot集成时核心依赖是mybatis-spring-boot-starter它内部有一个MybatisAutoConfiguration自动配置类里面注册了一个自动扫描器专门扫描类路径下带有Mapper注解的接口然后把它们注册为Bean。如果你用的是MapperScan注解它是由Spring框架处理的。MapperScan标注在启动类或某个配置类上指定一个或多个包路径Spring会创建对应包的Mapper扫描器扫描这些包下所有的接口并把它们注册成Mapper工厂Bean不管接口有没有加Mapper。对MappperScan而言Mapper加不加都无所谓。对Mapper而言前提是它的扫描器能扫描到该接口所在位置。1.3 为什么“包位置”是第一个要查的地方这里有个很多新手容易忽略的关键点MybatisAutoConfiguration里的自动扫描器扫描的包范围是由Spring Boot的AutoConfigurationPackages决定的。这个配置默认取的是SpringBootApplication所在类的包并且扫描它下面所有的子包。举个例子如果启动类是com.example.demo.DemoApplication那么自动扫描器只会去扫描com.example.demo以及com.example.demo.*下面的接口。如果你的Mapper接口放在com.example.mapper或者别的和启动类包路径不并列的位置那即使在接口上写了Mapper启动时也极大概率扫描不到。所以“在接口上加Mapper注解但依然报错”的人十个有七个是因为接口位置和启动类不在同一个根包下。这不是玄学问题是扫描范围没有覆盖到。2. 从项目结构开始排查启动类、包名和Mapper位置2.1 主启动类应该放在哪一层我曾经帮一个同事排查问题他的项目结构是这样的src/main/java ├── com/example/admin │ ├── controller │ ├── service │ ├── mapper │ └── AdminApplication.java └── com/example/common └── mapper启动类放在com.example.admin下面但通用Mapper放在com.example.common.mapper。结果AdminApplication启动时只扫描了com.example.admin下的Mappercommon模块的Mapper全部没注册进去注入时直接报找不到Bean。正确做法有两种把启动类往上提一层放在com.example下面让它能扫描到com.example.admin和com.example.common两个子包。保持启动类不动在启动类上加SpringBootApplication(scanBasePackages com.example)把扫描范围扩大。不过scanBasePackages只能解决Spring组件扫描范围的问题对MyBatis的自动Mapper扫描来说更稳妥的办法还是结合第三节的MapperScan来指定Mapper接口所在的包。因为scanBasePackages影响的是Component、Service这些Spring注解的扫描而MyBatis的Mapper扫描机制是独立的。2.2 包路径写错了最爱报哪类错MapperScan(com.example.mapper)写错成com.exmaple.mapper这种大小写或者拼写错误是最多见的。我建议写完MapperScan后直接看IDE里的类文件图标如果扫到的Mapper接口上方出现一个类似小鸟的图标说明已经被识别到了如果图标是灰色或者没有变化多半是路径没对上。还有一种情况是MapperScan的包路径比实际Mapper包路径大了一级。比如Mapper在com.example.mapper.user你写了MapperScan(com.example.mapper)这没问题但如果你写了MapperScan(com.example)范围变宽扫描器会把com.example下所有接口都当成Mapper尝试注册如果某些接口根本不是Mapper启动时反而会报错。2.3 多模块工程里的坑多模块的坑本质上也是扫描范围问题。假设你的工程分为api模块、dao模块、service模块启动类在service模块下dao模块里放着Mapper接口那启动类的默认扫描范围很可能覆盖不到dao模块的包。这种场景下一个比较标准的做法是在dao模块的Mapper接口上加Mapper同时在启动类或全局配置类上加MapperScan(com.example.dao.mapper)。既保留注解作为兜底又通过MapperScan指定明确的扫描包路径双保险。3. 三种让Mapper接口进容器的方式一次讲透3.1 方式一在接口上一个个加Mapper这是最直接的方式。package com.example.mapper; import org.apache.ibatis.annotations.Mapper; Mapper public interface UserMapper { User selectById(Long id); }Mapper标签会告诉MyBatis自动扫描器这个接口是一个Mapper映射器。只要接口位置在自动扫描器的覆盖范围内它就会被注册成Bean。优点是小项目一眼就能看出哪些接口是Mapper缺点是接口一多要么忘了加要么漏加代码也很冗余。而且如果接口不在自动扫描器覆盖范围内这个注解并没有用。所以它适合接口数量少、包结构和启动类处于同一根包下的简单项目。3.2 方式二启动类或配置类上加MapperScan这是用得最多也最推荐的方式因为它把“扫描哪些包”这件事集中到了一处。package com.example; import org.mybatis.spring.annotation.MapperScan; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication MapperScan(com.example.mapper) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }需要注意的是MapperScan只认包路径不认具体的接口名单。它会扫描该包下所有接口并把它们当作Mapper来处理。如果某个包下混着不是Mapper的接口启动时很可能报错所以包路径尽量精确一点。如果你有多个包需要扫描可以在注解里传一个数组MapperScan({com.example.mapper, com.example.common.mapper})或者分开写两个MapperScan也行Spring是允许重复标注的。3.3 方式三手动注册MapperScannerConfigurer有些老项目不习惯用注解更喜欢在XML配置文件里配置扫描器。如果你维护的是Spring Boot项目但依然保留了大量XML配置可以通过配置方式实现Configuration public class MyBatisConfig { Bean public MapperScannerConfigurer mapperScannerConfigurer() { MapperScannerConfigurer configurer new MapperScannerConfigurer(); configurer.setBasePackage(com.example.mapper); configurer.setSqlSessionFactoryBeanName(sqlSessionFactory); return configurer; } }这种方式更底层也更灵活。MapperScannerConfigurer是MyBatis-Spring提供的一个后置处理器它会在Spring容器启动的早期阶段扫描指定包下的接口并把它们注册成Mapper工厂Bean。我平时不怎么推荐大家自己写这段配置因为MapperScan内部本来就是这个套路除非你有自定义SqlSessionFactory或其他特殊需求否则没必要重复造轮子。3.4 Mapper和MapperScan能不能同时用可以。实际项目里经常两个一起上接口上加了Mapper启动类上也加了MapperScan。这样不会冲突最多出现一个接口被扫描两次的情况但Spring容器注册时发现是同一个Bean定义通常不会报错。我个人的建议是如果项目规模不大二选一就够了。如果团队协作项目我倾向于用MapperScan包扫描来控制粒度把扫描范围限定在具体的包下避免自动扫描器在SpringBootApplication根包下把所有接口一网打尽。4. 引入依赖与版本对齐少了这一步啥都白搭4.1 依赖坐标别引错了很多人会遇到这种情况代码结构没问题扫描路径也对启动类位置也没毛病但就是扫不到Mapper。这时候先看一眼pom.xml很可能你引入的是mybatis而不是mybatis-spring-boot-starter。只引入MyBatis核心依赖只能拿到MyBatis本身的功能并不会和Spring Boot自动配置挂钩。必须要有自动配置的starterMyBatis才能在Spring Boot启动时自动注册Mapper扫描器。正确的依赖是这样的dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.2/version /dependencySpring Boot 3.x的项目要特别注意需要引入3.x版本的starter因为Spring Boot 3基于Jakarta规范老的2.x starter可能兼容不了。4.2 mybatis-spring-boot-starter版本与Spring Boot版本对照我把常见的对应关系整理了一下方便你快速对照Starter版本适用Spring Boot版本备注1.3.21.x老项目基本没人用了2.1.x2.1.x配Spring Boot 2.12.2.x2.2.x配Spring Boot 2.22.3.x2.3.x ~ 2.7.x市面上用得最多的版本段3.0.x3.0.x适配Spring Boot 3.03.1.x3.1.x较新注意看官方发布日志版本不匹配不一定会报错但很可能导致自动配置不生效。如果你发现依赖引入了接口上也有Mapper启动时却没有扫描到Mapper先确认一下Spring Boot版本和starter版本是否匹配。Spring Boot 2.7项目配了一个3.0的MyBatis Starter我见过不止一次这种低级但隐蔽的问题。4.3 多数据源场景下的SqlSessionFactory与MapperScan还有一个进阶的坑多数据源时Mapper扫描往往会失效或者扫描到了但Mapper用的SqlSessionFactory不对导致启动后查询报错。单数据源场景下MapperScan什么都不用管直接用就行。但多数据源场景中如果你有两个数据源启动类上的MapperScan只能扫描到默认的SqlSessionFactory另一套数据源对应的Mapper如果也想被扫描就需要在配置类上再写一个MapperScan并且指定sqlSessionTemplateRef和sqlSessionFactoryRef。Configuration public class SecondDataSourceConfig { Bean(name secondSqlSessionFactory) public SqlSessionFactory secondSqlSessionFactory( Qualifier(secondDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(classpath*:mapper2/*.xml)); return factoryBean.getObject(); } Bean(name secondSqlSessionTemplate) public SqlSessionTemplate secondSqlSessionTemplate( Qualifier(secondSqlSessionFactory) SqlSessionFactory sqlSessionFactory) { return new SqlSessionTemplate(sqlSessionFactory); } }在另一个配置类或者启动类上写MapperScan(basePackages com.example.mapper.second, sqlSessionTemplateRef secondSqlSessionTemplate)这个场景如果你用不上可以跳过。但如果你正好卡在多数据源排查时就要注意MapperScan到底绑的是哪一套会话工厂。5. 接口能扫描到但SQL语句找不到mapper-locations配置5.1 Invalid bound statement (not found)到底是想告诉你什么Mapper接口能被扫描到说明Bean已经注入了。但调用方法时抛Invalid bound statement (not found)通常是接口方法没有绑定到对应的SQL语句。很多人会把这类报错一起归类到“扫描不到Mapper”里我恳请你把这两件事区分开。为什么会出现这种问题SQL定义有两种方式注解SQL和XML SQL。如果接口方法上没写Select、Insert这类注解SQL大概率写在XML文件里。XML文件需要被MyBatis加载到配置中而加载XML文件靠的是mapper-locations配置。如果配置路径和实际XML文件位置不匹配MyBatis自然找不到SQL。5.2 配置mapper-locations的三个写法在application.yml里配置是最常见的mybatis: mapper-locations: classpath:mapper/*.xml有时候你的XML文件不只在resources/mapper下还可能分散在多个模块的jar包里这时候就要注意路径写法mybatis: mapper-locations: classpath*:mapper/**/*.xmlclasspath*:前缀的意思是扫描所有jar包和类路径下的资源**表示任意多层目录。如果你的XML文件放在Java包下面虽然我不推荐这么干但确实有人这么放比如com.example.mapper包下直接放了UserMapper.xml那需要写mybatis: mapper-locations: classpath*:com/example/mapper/*.xml需要提醒的是虽然MyBatis默认会去和Mapper接口同包路径下找同名XML但Spring Boot环境下的自动配置并不会默认这么做。所以强烈建议在application.yml里显式配置mapper-locations。5.3 XML里的namespace约束XML文件的namespace必须写Mapper接口的全限定名。假设你的接口是package com.example.mapper; public interface UserMapper { User selectById(Long id); }那么UserMapper.xml的开头就应该是mapper namespacecom.example.mapper.UserMapper如果namespace写成了com.example.mapper.UserMapper1或者少了包名即使XML被加载了接口方法依然绑定不到SQL。IDEA里有时候会提示Cannot resolve namespace或者方法名变成红色但有时候啥提示都没有启动也正常直到运行时才炸。这种问题最难查建议拿到就检查namespace。6. 实操排查流程从报错到解决的快速定位法6.1 根据异常信息判断问题所处层级遇到扫描问题第一步不是改配置而是看一眼异常文本自己心里有个定位。如果是启动阶段就失败异常信息里明确提到required a bean of type com.xxx.mapper.UserMapper that could not be found那说明是注入器在创建Service Bean时找不到Mapper的Bean。这种问题的根因大概率是Mapper没有被注册成Bean。如果启动成功但调用Mapper时抛NullPointerException说明注入时拿到的Mapper为null。很多时候和上一条是同样的根因只是报错晚了一步。如果抛的是Invalid bound statement (not found)说明Mapper Bean已经存在了是SQL绑定出了问题走第五节的排查思路。如果抛的是No MyBatis mapper was found in ...说明扫描器启动了但扫出来的类不符合条件多半是MapperScan范围设置得过大或者包路径里根本没有Mapper接口。6.2 一套可以照抄的检查清单我给自己整理过一套排查清单每次遇到Mapper扫描问题按顺序过一遍基本五分钟内能定位第一步检查pom.xml是否引入了mybatis-spring-boot-starter并且版本和Spring Boot对应。第二步检查启动类位置。确认Mapper接口所在的父包是否在SpringBootApplication根包下。第三步检查启动类或配置类上是否加了MapperScan。如果没加且Mapper接口位置又不在启动类根包下大方向就已经错了。第四步检查MapperScan的包路径是否精确、拼写是否正确。只见启动类直接看路径。第五步如果Mapper用XML方式定义SQL检查mybatis.mapper-locations是否配置以及路径是否匹配。第六步如果项目是多模块检查Mapper所在模块是否被主启动模块依赖并且包路径是否在扫描范围里。第七步检查XML文件的namespace和接口全限定名是否一致方法id和接口方法名是否一致。这套顺序我实际用了很长时间每一步都是低成本检查但能覆盖九成以上的扫描问题。6.3 常见问题速查表我把平时群里问得最多的情况、根因和解决办法整理成了表格方便你直接对照现象根因解决办法启动报错Bean not found接口上有Mapper但没用接口不在自动扫描器的包范围内在启动类上添加MapperScan(具体包路径)接口加了Mapper仍报错路径检查过没问题Mapper接口的jar包没有扫描到确认启动类scanBasePackages或ComponentScan是否覆盖启动时报No MyBatis mapper was foundMapperScan包下面没有Mapper接口缩小包路径到包含Mapper的实际包Mapper注入成功方法调用报Invalid bound statementXML文件没加载或namespace不对配置mybatis.mapper-locations且检查namespace启动时自动配置没生效starter版本与Spring Boot版本不匹配查版本对照表换成匹配版本引入自定义SqlSessionFactory后Mapper扫不到SqlSessionFactory被覆盖扫描器绑定错误在MapperScan上指定sqlSessionFactoryRef或sqlSessionTemplateRefMapper在Controller里注入成功但Service里注入失败Spring包扫描覆盖不一致统一配置MapperScan或scanBasePackages6.4 实测小技巧用依赖日志验证扫描结果如果你实在不确定Mapper到底有没有被注册可以在启动时开启MyBatis的调试日志。在application.yml里加logging: level: org.mybatis: debug启动后在日志里搜索“Creating MapperFactoryBean”或者“Found Mapper”之类的关键字。MyBatis-Spring在不同版本里的日志格式不完全一样但只要能看到Mapper接口名说明它已经进入扫描和注册流程了剩下的就是SQL绑定问题。我建议把日志级别放在org.mybatis.spring这个package上而不是全量org.mybatis不然日志太多关键信息反而被淹没。另外一个技巧在启动类上加MapperScan后可以直接在IDE的Structure视图里看Mapper接口图标。IntelliJ IDEA对识别到的Spring Bean会给接口做特殊标记如果Mapper接口图标的左下角出现一根小羽毛或者类似标记说明扫描器已经识别到了。这个特性在不同版本IDE里表现不一样但值得一试。7. 再补充几个真实项目里遇到的特殊情况有些问题没法完全归到前几节但它们同样折磨人。第一个是Maven多模块打包时Mapper接口被重复扫描或漏扫描。某个模块的Mapper在开发环境能正常启动打包成jar后启动就报找不到Mapper。这种情况通常是MapperScan的包路径没错但mapper-locations里的通配符只在开发环境有效打包后资源路径变了。解决办法是用classpath*:而不是classpath:因为多模块打成一个fat jar后多个jar里的XML需要交给classpath*去全局搜索。第二个是使用了自定义的Interface或者做了切面代理导致Mapper代理对象类型判断出错。这类问题比较少见一般出现在老版本MyBatis和某些字节码增强框架冲突时。如果你加了类似MyBatis-Plus的依赖要注意它本身有自己的Mapper扫描机制可能和原生MapperScan产生交互影响。MyBatis-Plus官方给出的建议也是用MapperScan扫描但它的MapperScan扫描路径必须包含实际Mapper包而且它可能在MyBatis上面再包一层逻辑。如果同时使用原生Mybatis的和MyBatis-Plus的注解启动时也可能出现冲突建议先统一到一套扫描方式上。第三个是测试类扫描不到Mapper的问题。单元测试里如果SpringBootTest标注的测试类位置和主启动类不在同一个包下测试环境里也可能出现Mapper扫描不到的情况。解决办法要么把测试类放到和启动类平级的包下要么在测试类上单独加MapperScan。这个坑网上的讨论不多但一旦踩到报错信息和启动时一模一样不带上下文根本想不通。第四个是启动类和MapperScan在同一个类上但Mapper接口在一个尚未被Spring加载的自动配置类所在的包里。这种情况多发生于自行封装了一套基础框架、通过spring.factories注册自动配置的场景。排查方向和前面说的多模块问题一致最终还是回到扫描包路径对齐上。最后补充一个问得很频繁的细节如果整个项目里一个Mapper注解都没加且没有MapperScan那么项目启动时会不会报错答案是如果你不注入任何Mapper项目可以正常启动但一旦某个Service类里Autowired了一个Mapper接口启动必报Bean找不到的错。所以“扫描不到Mapper”这个问题本质上不是“注解消失了”而是“接口没有被注册进Spring容器”理解这点之后你的排查思路就不会乱。我个人在实际操作中的体会是大多数扫描问题都不是单一原因造成的而是多个小问题叠加。比如依赖没引对加包路径写错再比如接口不在扫描范围但同时又漏配了mapper-locations。冷静下来按照检查清单逐条过一遍比焦虑地反复重启项目管用得多。记住MyBatis和Spring Boot的这套整合机制已经非常成熟绝大多数问题都是“配置没对上”或者“位置没放对”没有什么玄学问题静下心来一点一点查就行。