前两天在群里看到有人贴报错:启动类能跑,但Service一注入Mapper的时候就挂,提示Consider defining a bean of type xxx.xxx.UserMapper in your configuration.点开代码,明明每个Mapper接口上都写了Mapper,标题也搜的“mybaties扫描不到mapper”。这个问题在Spring Boot MyBatis项目里出现频率极高,很多人第一反应是去改MapperScan,但该加的加了,该改的改了,重启还是报一样的错。这篇文章我把扫描机制、常见解法、隐藏原因、排查手段一次性讲透。不管你是刚接触Spring Boot的小白,还是被这个bug折磨过的老手,按我下面的顺序检查,基本两轮内能定位问题。1. 先搞懂Mapper扫不到的根本原因我习惯先讲原理再给方案,因为不懂原理的时候,解决方案全靠猜,换一个包结构又懵了。1.1 两个注解的“身世”差异Mapper是MyBatis提供的注解,不是Spring自带的。它的全限定名是org.apache.ibatis.annotations.Mapper,作用是把一个接口标记为MyBatis的Mapper接口。Spring容器本身不认识这个注解,必须由MyBatis和Spring整合的扫描器去发现它,然后为每个接口生成一个代理对象并注册到容器里。如果你只是引入了mybatis的jar包,而没有引入mybatis-spring-boot-starter,那Mapper注解写了也白写,因为根本没有对应的扫描逻辑被Spring加载。这一条看着基础,实际项目里碰到过好几次:有人为了少带依赖,手动引入了mybatis和mybatis-spring的包,结果启动一切正常,注入Mapper的时候立刻报找不到bean。所以在怀疑扫描路径之前,先确认依赖里有没有:dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.2/version /dependency如果你用的是Spring Boot 3.x,需要换成3.x的starter版本,不要继续用2.x。依赖都没上齐,后面所有排查都是白费工夫。1.2 默认扫描路径到底是谁决定的引入starter之后,自动配置会生效。核心类是org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration,它里面内嵌了一个扫描器注册器AutoConfiguredMapperScannerRegistrar,这个注册器会往容器里注册一个MapperScannerConfigurer。关键点来了:MapperScannerConfigurer的扫描起点,是启动类所在的包以及它的所有子包。举个最简单的例子,启动类在:com.example.demo.DemoApplication那么自动扫描的范围就是com.example.demo这个包往下。如果你的Mapper接口在:com.example.demo.mapper.UserMapper com.example.demo.dao.UserMapper那没问题,能扫到。但如果Mapper接口在:com.example.common.mapper.UserMapper那就不在默认扫描范围里,就算接口上写了100个Mapper,也一样不会被注册到Spring容器。很多人觉得“我明明加了注解”,实际上对MyBatis-Spring的自动配置来说,注解只是标记,扫描器不扫到这个包,注解就不起作用。这就是为什么报错信息里会提示Consider defining a bean of type ...,因为容器压根没有这个类型的bean。1.3 MapperScan是“定点扫描”,不受主包限制MapperScan的工作方式不同,它是通过Import(MapperScannerRegistrar.class)主动注册一个扫描器,并且明确指定扫描哪个包。SpringBootApplication MapperScan(basePackages com.example.project.mapper) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }扫描器拿到basePackages之后,会精确地扫描这个包以及它的子包,不管这个包和启动类所在包有没有关系。所以当遇到跨模块、跨目录结构时,MapperScan是比Mapper更直接、更可控的手段。MapperScan还可以写在配置类上,不一定非要写在启动类上。比如你把MyBatis相关配置拆到了单独的MyBatisConfig类,那MapperScan写在这个配置类上效果是一样的,因为它本质是往容器里注册同一个扫描器。2. 实战解决方案:先复现,再对症下药原理清楚了,接下来就是动手环节。我一般不建议上来就直接改代码,而是先确认到底卡在哪个环节。下面这套排查顺序,我自己用了好几年,基本能覆盖90%的情况。2.1 排查第一步:确认Mapper接口的真实包路径打开你的项目结构,先问自己一个问题:启动类在哪个包,Mapper接口在哪个包。如果Mapper接口不在启动类所在包的子包下面,而且你也没有使用MapperScan,那不用继续查了,这就是根因。可以写一段临时代码,把Spring Boot自动配置包打印出来,这样更直观:SpringBootApplication public class DemoApplication implements ApplicationRunner { private final ApplicationContext context; public DemoApplication(ApplicationContext context) { this.context context; } Override public void run(ApplicationArguments args) { ListString packages AutoConfigurationPackages.get(context.getBeanFactory()); packages.forEach(p - System.out.println(自动扫描包: p)); } public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }启动之后看控制台输出。如果输出的包路径确实不含Mapper接口所在的包,那问题就锁定在“扫描范围覆盖不到”。这里说一个非常常见的坑:很多项目的Controller、Service、Mapper是散在不同业务模块里的,比如接口定义在xxx-common模块,实现类写在xxx-admin模块。如果没有统一规划包路径,一旦启动类只落在某个模块的包下,其他模块的Mapper就是扫描盲区。2.2 方案A:把包结构调整到启动类管辖范围既然自动扫描范围是启动类所在包和它的子包,最符合直觉的解法就是把Mapper接口挪进去。比如启动类是com.example.demo.DemoApplication,那你就在com.example.demo下面建一个mapper子包,所有Mapper接口放进去。这种方式有什么好处?不需要额外写MapperScan,每个接口加Mapper之后自动扫描就能发现,项目结构简单,新成员接手也容易理解。适合单体项目、项目结构比较收敛的场景。但它有个致命缺点:如果项目是多模块,或者Mapper接口分散在多个公共模块里,硬把所有Mapper挪到一个包下会破坏原有的分层结构。我见过有人为了解这个报错,把一堆Mapper都复制到启动类所在模块里,结果生产环境SQL和旧代码维护混乱,新同事根本分不清哪个Mapper才是真正生效的。所以这个方案更适合小项目,不适合需要长期演进的工程。2.3 方案B:启动类上显式声明MapperScan如果不想大动干戈挪文件,在启动类上加MapperScan是最快的止血方式。SpringBootApplication MapperScan(basePackages { com.example.project.mapper, com.example.common.mapper }) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }basePackages接收的是一个字符串数组,多个包之间用逗号分隔。扫描的包一定是Mapper接口所在的包,不是XML文件所在的包。XML文件的路径由另外一个配置项mybatis.mapper-locations控制,两者不要混为一谈。用MapperScan之后,接口上写不写Mapper都无所谓。因为扫描器认得是“接口”,扫描到之后统一注册,Mapper更多是作为一个显式标记存在。不过为了团队阅读代码方便,我建议两个都保留:接口上写Mapper表示“这是一个Mapper”,启动类上的MapperScan负责真正扫进来。2.4 方案C:依赖与starter检查有时候问题不在扫描路径,而在依赖根本没接好。你打开pom看一遍,确认是不是用了mybatis-spring-boot-starter,而不是只有mybatis和mybatis-spring两个裸依赖。如果是多模块工程,还要确认starter是否传递到了启动模块。我遇到过一个项目,Mapper模块单独引用了starter,但启动模块没有引用,依赖隔离导致启动模块的容器里没有任何MyBatis自动配置,自然扫不到任何Mapper。解决方式很简单:把starter依赖放到启动模块,或者调整依赖传递策略。另外,如果你用的是mybatis-plus-boot-starter,它的扫描机制类似,但包名不同。报错和排查思路基本一致,只是自动配置类换成了MybatisPlusAutoConfiguration。3. 加了注解仍不生效的隐藏原因前面说的是主路径,下面几种情况更隐蔽。它们不是单纯“扫描不到”,而是扫描机制被其他配置干扰了,导致Mapper的作用被跳过。3.1 多模块工程最典型的“跨模块漏扫”跨模块场景单独拿出来说,因为它太常见了。项目结构类似这样:xxx-common:存放公共Mapper接口,包名com.team.common.mapperxxx-web:存放启动类,包名com.team.web启动类在com.team.web下,自动扫描范围是com.team.web,那com.team.common.mapper里的接口自然扫不到。你可以给接口加一万个Mapper,也进不了容器。解法就是在启动类上写MapperScan扫公共包:SpringBootApplication MapperScan(basePackages com.team) public class WebApplication { ... }我通常建议扫业务根包,而不是一个个Mapper包去罗列。比如所有业务代码都在com.team下,直接扫com.team,这样后续新增任意子包的Mapper都能被覆盖,不用每次加新模块都回来改注解。但这里有一个前提:你的业务模块的包名必须有一个共同的根,否则扫根包会把不想管的接口也扫进来。团队在定包名规范的时候,最好提前预留统一的业务根包。3.2 ComponentScan手动指定把“主包”带偏有些项目为了做组件扫描隔离,会在启动类上额外写ComponentScan(basePackages xxx)。这一步很容易把Spring Boot的自动配置包给“带偏”。原因是自动配置包从AutoConfigurationPackages这个注册器里读取,而这个注册器的值受SpringBootApplication或ComponentScan的扫描包影响。如果你手动指定了ComponentScan的包,Spring Boot默认包可能就不是你原来以为的那个路径,当Mapper接口落在另一个包下时就扫不到。这种情况下,最好的做法是不要手动写ComponentScan去覆盖配置。如果确实需要指定扫描包,优先用SpringBootApplication(scanBasePackages com.team),这样组件扫描包和自动配置包能保持统一。3.3 多数据源场景下的MapperScanner失效配置多个数据源时,你一般会手动创建多个SqlSessionFactory。一旦手动定义这些Bean,MyBatis自动配置的扫描器就不会按默认方式工作,因为自动配置的判断条件是容器里缺少这些Bean时才会生效。此时只靠Mapper大概率是不行的,需要为每个数据源单独指定扫描包和工厂:Configuration MapperScan( basePackages com.team.mapper.primary, sqlSessionFactoryRef primarySqlSessionFactory ) public class PrimaryDataSourceConfig { ... } Configuration MapperScan( basePackages com.team.mapper.secondary, sqlSessionFactoryRef secondarySqlSessionFactory ) public class SecondaryDataSourceConfig { ... }这种场景报错往往不是“找不到Mapper”,而是“有两个SqlSessionFactory不知道用哪个”,或者“扫描到了同一个Mapper但绑定到了错误的工厂”。如果你确认自己的项目是双数据源,别再纠结Mapper为什么不生效,先检查每个MapperScan是否都指定了对应的sqlSessionFactoryRef。3.4 接口成功注册了,但调用时报XML绑定错误还有一种看似“扫描不到”的假象:接口能注入,Controller层也没报错,但一调用方法就抛异常Invalid bound statement (not found): com.team.mapper.UserMapper.selectById。这其实不是扫描问题,而是接口和XML没有正确绑定。检查下面几个点:mybatis.mapper-locations是否配置了XML所在路径,比如classpath:mapper/**/*.xmlXML文件里的namespace是否和接口全限定名一致XML文件里的 statement id 是否和接口方法名一致即使Mapper接口被成功扫描注册,如果MyBatis在启动时没有加载对应XML,运行期调用同样会失败。很多人把这个也归到“Mapper没扫到”里,其实是两个问题,但排查时要一起看,省得来回折腾。4. 定位问题的日志与验证技巧光靠肉眼翻代码效率太低,下面分享几个能快速确认“到底有没有扫到”的手段。4.1 让MyBatis把扫描过程打在日志上先把日志级别打开:logging: level: org.mybatis: debug org.mybatis.spring: debug重启项目,重点看启动日志里有没有出现类似Creating MapperFactoryBean for interface ...的条目。如果你能看到目标Mapper被创建,说明扫描已经完成,问题出在后面;如果完全看不到,说明扫描器根本就没扫到你的Mapper包,继续检查路径和MapperScan。需要注意的是,生产环境不要长期开debug日志,信息量太大。我是只在本地排查时开,排完立刻关掉。4.2 用ApplicationContext验证Mapper是否进了容器如果对日志不放心,可以直接在启动类里临时写一段代码,把指定类型的bean名称列出来:Autowired private ApplicationContext context; // 在某个方法里执行 String[] beanNames context.getBeanNamesForType(UserMapper.class); System.out.println(UserMapper bean: Arrays.toString(beanNames));如果输出为空,说明没有这个bean,扫描环节确实失败了。如果输出了类似userMapper这样的名称,说明bean已经在容器里,那你的问题要从XML绑定、SqlSessionFactory角度找,而不是继续纠结扫描。我通常还会顺手打印所有Mapper类型的bean:MapString, Object mapperBeans context.getBeansWithAnnotation(org.apache.ibatis.annotations.Mapper.class); mapperBeans.forEach((name, bean) - System.out.println(name - bean));这样能一眼看到项目里到底有哪些Mapper注册成功了。是删还是留,按自己习惯来,但定位效率确实高。4.3 常见错误场景速查表现象根本原因解决方式Consider defining a bean of type xxx.UserMapper扫描路径未覆盖Mapper接口调整包结构或加MapperScanNo qualifying bean of type ...同上,但发生在多模块显式扫描公共Mapper包Invalid bound statement (not found)接口已注册,XML未绑定检查mapper-locations和namespace同时出现多个SqlSessionFactory相关冲突多数据源扫描器未指定工厂MapperScan加sqlSessionFactoryRef启动后没有任何MappedStatement日志且接口注入失败starter依赖缺失或未传递检查mybatis-spring-boot-starter依赖这张表我贴在项目文档里,新来的同事遇到类似问题先查表,基本不用反复问我。5. 工程上的长期建议排查方法都讲完了,最后聊点项目规范层面的东西,这些是我在实际项目里吃过亏之后总结出来的。5.1 统一使用一种扫描策略,不要混搭一个项目里可以同时存在Mapper和MapperScan,这没问题,但团队内部最好定一个统一策略。如果项目结构简单、所有Mapper都在启动类所在包的子包下,就统一用Mapper,简单直观。如果项目是多模块、Mapper分散,就统一靠MapperScan扫描根包,并且让启动类使用scanBasePackages保持配置一致。最忌讳的是有的人在启动类加MapperScan,有的人在自己的模块里又写MapperScan,多个扫描器叠加,注册逻辑变得很难预测,后面排查成本直线上升。5.2 MapperScan该扫到哪一层我给两个真实场景参考。场景一:一个小型单体项目,Mapper全部在com.team.user.mapper、com.team.order.mapper这种子包下面。可以直接:MapperScan(basePackages com.team)好处是新加任何业务模块的Mapper都不用改启动类,坏处是如果哪天有非Mapper接口与Mapper接口混在同一包,也会被扫进去。虽然问题不大,但不够干净。场景二:项目里Mapper包路径特别乱,有的在com.a.mapper,有的在com.b.dao,没有公共根包。这时候我不建议硬扫一个太高的根包,而是把共用的几层结构整理一下,或者用逗号把需要扫的包列出来:MapperScan(basePackages { com.team.order.mapper, com.team.user.mapper, com.team.common.mapper })不推荐在MapperScan里写通配符写法,Spring Boot不会解析com.team.**这种形式,写上去往往直接启动报错或静默不生效。老老实实列包名,或者把包结构收敛,比啥都强。5.3 我最终的检查习惯我现在遇到项目启动报“找不到Mapper”,心里已经有了一个固定动作顺序。第一步看启动类包和Mapper包的关系,第二步查MapperScan,第三步确认starter依赖,第四步开debug日志验证扫描结果。整个过程五分钟以内。如果以上全部正常但调用还是报错,我再检查XML绑定和SqlSessionFactory。有一次帮同事排查,项目里报“扫描不到UserMapper”,我看了一眼启动类,发现它根本没有引入MyBatis的starter,只是公共模块引了,启动模块看不到这个依赖。同事之前花了一整天在调MapperScan的路径,怎么调都没用。所以每次遇到这种问题,我都会先问一句:这个starter到底有没有进到当前启动模块的依赖里。依赖都没进来,注解和路径再怎么折腾都不会生效。最后再分享一个特别容易忽略的小技巧:报错日志第一行不要跳过。很多人只盯着一句 “could not be found”,却忽略了前面的Field userMapper in com.xxx.controller.UserController required a single bean...。其实日志里已经告诉你是哪个类、哪个字段、需要什么类型的bean,顺着这个信息往回找,定位速度能快很多。说白了,Spring Boot报错虽然英文看着唬人,但每一条信息都有实际用途,耐心看完整,比盲目改配置靠谱得多。
前两天在群里看到有人贴报错:启动类能跑,但Service一注入Mapper的时候就挂,提示Consider defining a bean of type xxx.xxx.UserMapper in your configuration.点开代码,明明每个Mapper接口上都写了Mapper,标题也搜的“mybaties扫描不到mapper”。这个问题在Spring Boot MyBatis项目里出现频率极高,很多人第一反应是去改MapperScan,但该加的加了,该改的改了,重启还是报一样的错。这篇文章我把扫描机制、常见解法、隐藏原因、排查手段一次性讲透。不管你是刚接触Spring Boot的小白,还是被这个bug折磨过的老手,按我下面的顺序检查,基本两轮内能定位问题。1. 先搞懂Mapper扫不到的根本原因我习惯先讲原理再给方案,因为不懂原理的时候,解决方案全靠猜,换一个包结构又懵了。1.1 两个注解的“身世”差异Mapper是MyBatis提供的注解,不是Spring自带的。它的全限定名是org.apache.ibatis.annotations.Mapper,作用是把一个接口标记为MyBatis的Mapper接口。Spring容器本身不认识这个注解,必须由MyBatis和Spring整合的扫描器去发现它,然后为每个接口生成一个代理对象并注册到容器里。如果你只是引入了mybatis的jar包,而没有引入mybatis-spring-boot-starter,那Mapper注解写了也白写,因为根本没有对应的扫描逻辑被Spring加载。这一条看着基础,实际项目里碰到过好几次:有人为了少带依赖,手动引入了mybatis和mybatis-spring的包,结果启动一切正常,注入Mapper的时候立刻报找不到bean。所以在怀疑扫描路径之前,先确认依赖里有没有:dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.2/version /dependency如果你用的是Spring Boot 3.x,需要换成3.x的starter版本,不要继续用2.x。依赖都没上齐,后面所有排查都是白费工夫。1.2 默认扫描路径到底是谁决定的引入starter之后,自动配置会生效。核心类是org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration,它里面内嵌了一个扫描器注册器AutoConfiguredMapperScannerRegistrar,这个注册器会往容器里注册一个MapperScannerConfigurer。关键点来了:MapperScannerConfigurer的扫描起点,是启动类所在的包以及它的所有子包。举个最简单的例子,启动类在:com.example.demo.DemoApplication那么自动扫描的范围就是com.example.demo这个包往下。如果你的Mapper接口在:com.example.demo.mapper.UserMapper com.example.demo.dao.UserMapper那没问题,能扫到。但如果Mapper接口在:com.example.common.mapper.UserMapper那就不在默认扫描范围里,就算接口上写了100个Mapper,也一样不会被注册到Spring容器。很多人觉得“我明明加了注解”,实际上对MyBatis-Spring的自动配置来说,注解只是标记,扫描器不扫到这个包,注解就不起作用。这就是为什么报错信息里会提示Consider defining a bean of type ...,因为容器压根没有这个类型的bean。1.3 MapperScan是“定点扫描”,不受主包限制MapperScan的工作方式不同,它是通过Import(MapperScannerRegistrar.class)主动注册一个扫描器,并且明确指定扫描哪个包。SpringBootApplication MapperScan(basePackages com.example.project.mapper) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }扫描器拿到basePackages之后,会精确地扫描这个包以及它的子包,不管这个包和启动类所在包有没有关系。所以当遇到跨模块、跨目录结构时,MapperScan是比Mapper更直接、更可控的手段。MapperScan还可以写在配置类上,不一定非要写在启动类上。比如你把MyBatis相关配置拆到了单独的MyBatisConfig类,那MapperScan写在这个配置类上效果是一样的,因为它本质是往容器里注册同一个扫描器。2. 实战解决方案:先复现,再对症下药原理清楚了,接下来就是动手环节。我一般不建议上来就直接改代码,而是先确认到底卡在哪个环节。下面这套排查顺序,我自己用了好几年,基本能覆盖90%的情况。2.1 排查第一步:确认Mapper接口的真实包路径打开你的项目结构,先问自己一个问题:启动类在哪个包,Mapper接口在哪个包。如果Mapper接口不在启动类所在包的子包下面,而且你也没有使用MapperScan,那不用继续查了,这就是根因。可以写一段临时代码,把Spring Boot自动配置包打印出来,这样更直观:SpringBootApplication public class DemoApplication implements ApplicationRunner { private final ApplicationContext context; public DemoApplication(ApplicationContext context) { this.context context; } Override public void run(ApplicationArguments args) { ListString packages AutoConfigurationPackages.get(context.getBeanFactory()); packages.forEach(p - System.out.println(自动扫描包: p)); } public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }启动之后看控制台输出。如果输出的包路径确实不含Mapper接口所在的包,那问题就锁定在“扫描范围覆盖不到”。这里说一个非常常见的坑:很多项目的Controller、Service、Mapper是散在不同业务模块里的,比如接口定义在xxx-common模块,实现类写在xxx-admin模块。如果没有统一规划包路径,一旦启动类只落在某个模块的包下,其他模块的Mapper就是扫描盲区。2.2 方案A:把包结构调整到启动类管辖范围既然自动扫描范围是启动类所在包和它的子包,最符合直觉的解法就是把Mapper接口挪进去。比如启动类是com.example.demo.DemoApplication,那你就在com.example.demo下面建一个mapper子包,所有Mapper接口放进去。这种方式有什么好处?不需要额外写MapperScan,每个接口加Mapper之后自动扫描就能发现,项目结构简单,新成员接手也容易理解。适合单体项目、项目结构比较收敛的场景。但它有个致命缺点:如果项目是多模块,或者Mapper接口分散在多个公共模块里,硬把所有Mapper挪到一个包下会破坏原有的分层结构。我见过有人为了解这个报错,把一堆Mapper都复制到启动类所在模块里,结果生产环境SQL和旧代码维护混乱,新同事根本分不清哪个Mapper才是真正生效的。所以这个方案更适合小项目,不适合需要长期演进的工程。2.3 方案B:启动类上显式声明MapperScan如果不想大动干戈挪文件,在启动类上加MapperScan是最快的止血方式。SpringBootApplication MapperScan(basePackages { com.example.project.mapper, com.example.common.mapper }) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }basePackages接收的是一个字符串数组,多个包之间用逗号分隔。扫描的包一定是Mapper接口所在的包,不是XML文件所在的包。XML文件的路径由另外一个配置项mybatis.mapper-locations控制,两者不要混为一谈。用MapperScan之后,接口上写不写Mapper都无所谓。因为扫描器认得是“接口”,扫描到之后统一注册,Mapper更多是作为一个显式标记存在。不过为了团队阅读代码方便,我建议两个都保留:接口上写Mapper表示“这是一个Mapper”,启动类上的MapperScan负责真正扫进来。2.4 方案C:依赖与starter检查有时候问题不在扫描路径,而在依赖根本没接好。你打开pom看一遍,确认是不是用了mybatis-spring-boot-starter,而不是只有mybatis和mybatis-spring两个裸依赖。如果是多模块工程,还要确认starter是否传递到了启动模块。我遇到过一个项目,Mapper模块单独引用了starter,但启动模块没有引用,依赖隔离导致启动模块的容器里没有任何MyBatis自动配置,自然扫不到任何Mapper。解决方式很简单:把starter依赖放到启动模块,或者调整依赖传递策略。另外,如果你用的是mybatis-plus-boot-starter,它的扫描机制类似,但包名不同。报错和排查思路基本一致,只是自动配置类换成了MybatisPlusAutoConfiguration。3. 加了注解仍不生效的隐藏原因前面说的是主路径,下面几种情况更隐蔽。它们不是单纯“扫描不到”,而是扫描机制被其他配置干扰了,导致Mapper的作用被跳过。3.1 多模块工程最典型的“跨模块漏扫”跨模块场景单独拿出来说,因为它太常见了。项目结构类似这样:xxx-common:存放公共Mapper接口,包名com.team.common.mapperxxx-web:存放启动类,包名com.team.web启动类在com.team.web下,自动扫描范围是com.team.web,那com.team.common.mapper里的接口自然扫不到。你可以给接口加一万个Mapper,也进不了容器。解法就是在启动类上写MapperScan扫公共包:SpringBootApplication MapperScan(basePackages com.team) public class WebApplication { ... }我通常建议扫业务根包,而不是一个个Mapper包去罗列。比如所有业务代码都在com.team下,直接扫com.team,这样后续新增任意子包的Mapper都能被覆盖,不用每次加新模块都回来改注解。但这里有一个前提:你的业务模块的包名必须有一个共同的根,否则扫根包会把不想管的接口也扫进来。团队在定包名规范的时候,最好提前预留统一的业务根包。3.2 ComponentScan手动指定把“主包”带偏有些项目为了做组件扫描隔离,会在启动类上额外写ComponentScan(basePackages xxx)。这一步很容易把Spring Boot的自动配置包给“带偏”。原因是自动配置包从AutoConfigurationPackages这个注册器里读取,而这个注册器的值受SpringBootApplication或ComponentScan的扫描包影响。如果你手动指定了ComponentScan的包,Spring Boot默认包可能就不是你原来以为的那个路径,当Mapper接口落在另一个包下时就扫不到。这种情况下,最好的做法是不要手动写ComponentScan去覆盖配置。如果确实需要指定扫描包,优先用SpringBootApplication(scanBasePackages com.team),这样组件扫描包和自动配置包能保持统一。3.3 多数据源场景下的MapperScanner失效配置多个数据源时,你一般会手动创建多个SqlSessionFactory。一旦手动定义这些Bean,MyBatis自动配置的扫描器就不会按默认方式工作,因为自动配置的判断条件是容器里缺少这些Bean时才会生效。此时只靠Mapper大概率是不行的,需要为每个数据源单独指定扫描包和工厂:Configuration MapperScan( basePackages com.team.mapper.primary, sqlSessionFactoryRef primarySqlSessionFactory ) public class PrimaryDataSourceConfig { ... } Configuration MapperScan( basePackages com.team.mapper.secondary, sqlSessionFactoryRef secondarySqlSessionFactory ) public class SecondaryDataSourceConfig { ... }这种场景报错往往不是“找不到Mapper”,而是“有两个SqlSessionFactory不知道用哪个”,或者“扫描到了同一个Mapper但绑定到了错误的工厂”。如果你确认自己的项目是双数据源,别再纠结Mapper为什么不生效,先检查每个MapperScan是否都指定了对应的sqlSessionFactoryRef。3.4 接口成功注册了,但调用时报XML绑定错误还有一种看似“扫描不到”的假象:接口能注入,Controller层也没报错,但一调用方法就抛异常Invalid bound statement (not found): com.team.mapper.UserMapper.selectById。这其实不是扫描问题,而是接口和XML没有正确绑定。检查下面几个点:mybatis.mapper-locations是否配置了XML所在路径,比如classpath:mapper/**/*.xmlXML文件里的namespace是否和接口全限定名一致XML文件里的 statement id 是否和接口方法名一致即使Mapper接口被成功扫描注册,如果MyBatis在启动时没有加载对应XML,运行期调用同样会失败。很多人把这个也归到“Mapper没扫到”里,其实是两个问题,但排查时要一起看,省得来回折腾。4. 定位问题的日志与验证技巧光靠肉眼翻代码效率太低,下面分享几个能快速确认“到底有没有扫到”的手段。4.1 让MyBatis把扫描过程打在日志上先把日志级别打开:logging: level: org.mybatis: debug org.mybatis.spring: debug重启项目,重点看启动日志里有没有出现类似Creating MapperFactoryBean for interface ...的条目。如果你能看到目标Mapper被创建,说明扫描已经完成,问题出在后面;如果完全看不到,说明扫描器根本就没扫到你的Mapper包,继续检查路径和MapperScan。需要注意的是,生产环境不要长期开debug日志,信息量太大。我是只在本地排查时开,排完立刻关掉。4.2 用ApplicationContext验证Mapper是否进了容器如果对日志不放心,可以直接在启动类里临时写一段代码,把指定类型的bean名称列出来:Autowired private ApplicationContext context; // 在某个方法里执行 String[] beanNames context.getBeanNamesForType(UserMapper.class); System.out.println(UserMapper bean: Arrays.toString(beanNames));如果输出为空,说明没有这个bean,扫描环节确实失败了。如果输出了类似userMapper这样的名称,说明bean已经在容器里,那你的问题要从XML绑定、SqlSessionFactory角度找,而不是继续纠结扫描。我通常还会顺手打印所有Mapper类型的bean:MapString, Object mapperBeans context.getBeansWithAnnotation(org.apache.ibatis.annotations.Mapper.class); mapperBeans.forEach((name, bean) - System.out.println(name - bean));这样能一眼看到项目里到底有哪些Mapper注册成功了。是删还是留,按自己习惯来,但定位效率确实高。4.3 常见错误场景速查表现象根本原因解决方式Consider defining a bean of type xxx.UserMapper扫描路径未覆盖Mapper接口调整包结构或加MapperScanNo qualifying bean of type ...同上,但发生在多模块显式扫描公共Mapper包Invalid bound statement (not found)接口已注册,XML未绑定检查mapper-locations和namespace同时出现多个SqlSessionFactory相关冲突多数据源扫描器未指定工厂MapperScan加sqlSessionFactoryRef启动后没有任何MappedStatement日志且接口注入失败starter依赖缺失或未传递检查mybatis-spring-boot-starter依赖这张表我贴在项目文档里,新来的同事遇到类似问题先查表,基本不用反复问我。5. 工程上的长期建议排查方法都讲完了,最后聊点项目规范层面的东西,这些是我在实际项目里吃过亏之后总结出来的。5.1 统一使用一种扫描策略,不要混搭一个项目里可以同时存在Mapper和MapperScan,这没问题,但团队内部最好定一个统一策略。如果项目结构简单、所有Mapper都在启动类所在包的子包下,就统一用Mapper,简单直观。如果项目是多模块、Mapper分散,就统一靠MapperScan扫描根包,并且让启动类使用scanBasePackages保持配置一致。最忌讳的是有的人在启动类加MapperScan,有的人在自己的模块里又写MapperScan,多个扫描器叠加,注册逻辑变得很难预测,后面排查成本直线上升。5.2 MapperScan该扫到哪一层我给两个真实场景参考。场景一:一个小型单体项目,Mapper全部在com.team.user.mapper、com.team.order.mapper这种子包下面。可以直接:MapperScan(basePackages com.team)好处是新加任何业务模块的Mapper都不用改启动类,坏处是如果哪天有非Mapper接口与Mapper接口混在同一包,也会被扫进去。虽然问题不大,但不够干净。场景二:项目里Mapper包路径特别乱,有的在com.a.mapper,有的在com.b.dao,没有公共根包。这时候我不建议硬扫一个太高的根包,而是把共用的几层结构整理一下,或者用逗号把需要扫的包列出来:MapperScan(basePackages { com.team.order.mapper, com.team.user.mapper, com.team.common.mapper })不推荐在MapperScan里写通配符写法,Spring Boot不会解析com.team.**这种形式,写上去往往直接启动报错或静默不生效。老老实实列包名,或者把包结构收敛,比啥都强。5.3 我最终的检查习惯我现在遇到项目启动报“找不到Mapper”,心里已经有了一个固定动作顺序。第一步看启动类包和Mapper包的关系,第二步查MapperScan,第三步确认starter依赖,第四步开debug日志验证扫描结果。整个过程五分钟以内。如果以上全部正常但调用还是报错,我再检查XML绑定和SqlSessionFactory。有一次帮同事排查,项目里报“扫描不到UserMapper”,我看了一眼启动类,发现它根本没有引入MyBatis的starter,只是公共模块引了,启动模块看不到这个依赖。同事之前花了一整天在调MapperScan的路径,怎么调都没用。所以每次遇到这种问题,我都会先问一句:这个starter到底有没有进到当前启动模块的依赖里。依赖都没进来,注解和路径再怎么折腾都不会生效。最后再分享一个特别容易忽略的小技巧:报错日志第一行不要跳过。很多人只盯着一句 “could not be found”,却忽略了前面的Field userMapper in com.xxx.controller.UserController required a single bean...。其实日志里已经告诉你是哪个类、哪个字段、需要什么类型的bean,顺着这个信息往回找,定位速度能快很多。说白了,Spring Boot报错虽然英文看着唬人,但每一条信息都有实际用途,耐心看完整,比盲目改配置靠谱得多。
