MyBatis 扫不到 @Mapper？Bean 找不到的 5 种原因与 3 种解法

做Spring Boot集成MyBatis的项目，十有八九会遇到这样一个场景：代码写得没问题，SQL也没错，一启动却抛出一堆红字，核心就一句话——“Consider defining a bean of type 'xxxMapper' in your configuration”。明明Mapper接口上写了@Mapper注解，Spring容器里就是找不到这个Bean。我当年第一次遇到这个问题，愣是折腾了小半天，最后发现不过是启动类的位置放错了。这篇文章就把这类问题掰开揉碎讲清楚，包括为什么会扫不到、报错信息怎么定位、以及真正可以落地的几种解决方案。

1. 先搞明白：@Mapper 注解到底做了什么

1.1 一个“找不到Bean”的启动报错

先看一个典型的报错完整样子。Spring Boot 启动阶段抛出：

*************************** APPLICATION FAILED TO START *************************** Description: Field userMapper in com.example.service.UserServiceImpl required a bean of type 'com.example.mapper.UserMapper' that could not be found. The injection point has the following annotations: - @Autowired(required=true) Action: Consider defining a bean of type 'com.example.mapper.UserMapper' in your configuration.

这个报错的含义很明确：项目里某个Service通过@Autowired往自己内部注入UserMapper，但Spring容器在启动完成时，没有发现任何类型为UserMapper的Bean。Spring不知道UserMapper的存在，自然没法把它注入到Service里。

很多人看到这个提示的第一反应是：我明明在UserMapper接口上写了@Mapper，怎么可能找不到？这里要厘清一个概念：@Mapper只是MyBatis框架自己识别接口的一个标记，它并不会像@Component那样被Spring默认的组件扫描机制直接处理。Spring默认扫描器只认@Component、@Service、@Repository这类注解，不认@Mapper。最终要让@Mapper生效，必须由MyBatis自己的扫描逻辑介入，而这个逻辑的扫描范围一旦没覆盖到接口，那注解就相当于白写。

1.2 MyBatis 的 Mapper 注册机制

Spring Boot + MyBatis的底层注册过程，可以拆成三块理解：

1. Spring Boot启动时，通过自动配置类加载MyBatis的核心组件，比如SqlSessionFactory、SqlSessionTemplate。
2. MyBatis根据配置的basePackage扫描路径，去找所有接口，判断哪些是Mapper。判断依据包括：接口上有没有@Mapper注解、有没有继承特定接口、有没有被@MapperScan指定。
3. 对于判定为Mapper的接口，MyBatis会生成一个MapperFactoryBean，再把动态代理对象注册成Spring的Bean。

问题就出在第2步的“扫描路径”上。如果MyBatis的扫描范围没有覆盖到你的Mapper接口所在的包，那它就永远不会去读那个接口上的@Mapper，最后自然什么都注册不到。

这里有一个关键点要理解：Spring Boot启动类上的@SpringBootApplication本身组合了组件扫描功能，默认扫描范围是“启动类所在包及其子包”。假如Mapper接口在com.example.mapper，启动类在com.example，那默认扫描路径其实能覆盖到。但前面说了，Spring默认扫描器不认@Mapper，所以哪怕接口和启动类在同一包下，也必须靠MyBatis自己的扫描器介入才能生成Bean。

1.3 两种注册姿势：@Mapper 和 @MapperScan

理解两种注册方式的区别，是解决问题的前提。

方式一：每个Mapper接口上写@Mapper注解。这是“点对点”的注册方式，MyBatis扫描器在扫描时，发现某个接口带有@Mapper标记，就把它注册为Bean。优点是直观，每个接口上都能看到；缺点是如果项目里Mapper特别多，每个接口都要写，容易漏，而且扫描器本身依然要有正确的扫描路径。

方式二：在配置类或启动类上写@MapperScan(basePackages = "com.example.mapper")。这是“圈地”式的注册方式，把所有Mapper放在同一个包下，只要在启动类上指定这个包，MyBatis扫描器就会把包下的所有接口都当作Mapper处理，接口上不需要再写@Mapper。

在实际项目里，很多团队两种方式混用，这没问题，但有一个隐患：如果启动类上已经加了@MapperScan，同时又要求每个Mapper接口必须写@Mapper，其实是重复劳动。反之，如果完全没有@MapperScan，只靠接口上的@Mapper注解，就必须保证MyBatis扫描器能覆盖到对应包路径。

2. 扫描不到 @Mapper 的五种常见原因

2.1 启动类位置与 Mapper 接口不在同一包路径

这个问题是初学者遇到最多的。启动类通常叫Application，放在com.example.demo下，Mapper接口放在com.example.demo.mapper下，这种情况没问题，因为mapper是启动类包的直接子包，默认扫描路径com.example.demo能覆盖到它。

但有一种项目结构，控制器、服务、Mapper分别以独立模块存在。比如启动类放在com.example.bootstrap包下，Mapper放在com.example.modules.user.mapper包下，扫描路径就出问题了。Spring Boot的默认扫描从启动类所在包开始，只覆盖bootstrap包及其子包，跟modules包毫无关系。

判断方法很简单：把启动类的位置和被扫描包的位置画出来，看是否存在包含关系。不需要什么工具，肉眼就能看出来。我在实战中看到过太多人遇到这个报错后，先怀疑数据库配置、怀疑SQL写法，最后绕了一大圈，才发现是包路径的父子关系根本没对应上。

2.2 只用 @Mapper 没配 @MapperScan，启动类在父包

这种情况要单独拎出来讲。有一个典型的例子，启动类在com.example.application包下，Mapper接口在com.example.infra.mapper包下，两个包是平级关系，甚至没有包含关系。每个Mapper接口上都写了@Mapper，但启动时依然报Bean找不到。

原因在于，MyBatis的自动配置逻辑会以启动类所在包为基准去搜索Mapper，而com.example.infra.mapper根本不在它的搜索范围内。这时候你在接口上写多少遍@Mapper都没用，扫描器根本没走到那个包。

针对这种场景，最简单的办法是启动类向上移动一层，移到com.example下，或直接用@MapperScan指定Mapper包。工程上我更推荐后者，因为移动启动类会影响其他组件扫描的覆盖范围，原来在application包下的一些配置类，移动后可能反而扫不到了，容易引起连锁反应。

2.3 Mapper 接口的包名被 @ComponentScan 排除或类型过滤

这个原因比较隐蔽。有些团队会在启动类上使用@ComponentScan的excludeFilters，目的可能是排除某个模块的自动扫描，避免重复加载，结果过滤规则写得太宽，把mapper包也误伤排除掉了。

比如这样一个配置：

@ComponentScan( basePackages = "com.example", excludeFilters = @ComponentScan.Filter( type = FilterType.REGEX, pattern = "com\\.example\\..*\\.mapper\\..*" ) )

这行代码的本意可能是排除某个实现包，结果把使用MyBatis的mapper包也排除在外。这类问题排查起来很费神，因为启动时不会提示“扫描路径错误”，而是干脆地报“Bean找不到”，容易让人误判成前置条件没满足，去检查数据库、检查注解，走了很多弯路。

2.4 MyBatis 启动器依赖缺失或版本不一致

Spring Boot + MyBatis项目使用的主依赖通常是mybatis-spring-boot-starter。但有些工程会遇到：

• 只引入了mybatis核心包，没引入starter，导致MybatisAutoConfiguration根本没生效。
• 引入了starter，但版本和Spring Boot主版本不兼容，自动配置类被条件注解直接跳过。
• 使用mybatis-plus时，同时又混用了原生mybatis-spring-boot-starter，两套扫描逻辑出现冲突。

这些情况表面看都是“扫不到@Mapper”，但本质是MyBatis的自动装配没有启动。区分方法也简单：如果项目启动日志中，根本没有出现任何关于SqlSessionFactory或MyBatis初始化信息的记录，那大概率是依赖或自动配置出了问题。

检查依赖最简单的方式是看pom.xml：

<dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>2.3.2</version> </dependency>

如果项目用的是mybatis-plus，则是：

<dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> </dependency>

特别提醒一句：不要在同一项目里混用两套MyBatis体系的starter，否则扫描逻辑互相覆盖，报错会让你怀疑人生。

2.5 XML 文件路径与 namespace 不匹配（附带的坑）

严格来说，XML文件路径不对不会直接导致@Mapper扫不到，但它会在扫描到Mapper之后引发第二波报错，很多人误以为“还是没扫到”。报错一般是这样的：

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.findById

这个报错的含义是：Mapper接口已经成功注册成Bean了，但MyBatis根据接口全限定名去找对应的SQL映射语句时没找到。常见原因有：

• XML文件没有放在正确的资源路径下。
• application.yml里没配置mapper-locations。
• XML文件的namespace写错，和接口全限定名不一致。
• 方法id和接口方法名不对应。

这个问题会被误判成“扫不到@Mapper”，是因为很多开发者看到Invalid bound statement之后，第一反应是去检查接口上的注解，但注解其实没问题，问题出在SQL映射文件上。

3. 实战解决：从报错日志到最终修复

3.1 先定位到底是不是扫不到

解决一切问题的第一步，是确认故障类型。我通常会做三个动作。

第一，查看启动日志，搜索MapperScan、ClassPathMapperScanner这类字样。如果日志里有，说明MyBatis扫描器确实启动过。

第二，查看报错异常类型。如果是UnsatisfiedDependencyException并提示Bean找不到，问题基本在“扫描注册”环节；如果是BindingException或Invalid bound statement，问题在“SQL绑定”环节。

第三，临时加一个Bean打印器，把所有Mapper类型的Bean名称打出来看看。可以用一个简单的ApplicationRunner，也可以通过调试工具在启动后查看ApplicationContext里的BeanDefinitionNames。如果打印结果里没有任何Mapper相关Bean，那就是扫描注册的问题，就直接往扫描方案方向走。

3.2 推荐方案一：@MapperScan 指定包路径

这是我最推荐的方案，也是实战中解决这类问题最稳的招。在启动类上加上注解：

@SpringBootApplication @MapperScan("com.example.mapper") public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }

这段代码做的事情，本质上是在容器里注册了一个MapperScannerConfigurer，它会专门扫描你指定的包，把包下所有接口都注册为Mapper。它的优势在于扫描路径完全由你控制，不再依赖启动类的位置和包路径的包含关系。

如果Mapper接口分布在多个包里，可以写成：

@MapperScan({"com.example.mapper", "com.example.modules.user.mapper"})

如果你已经使用多数据源，需要给不同的数据源指定不同的Mapper包，@MapperScan还可以配合sqlSessionTemplateRef、sqlSessionFactoryRef使用。不过多数据源场景属于进阶话题，这里不展开，但你要知道@MapperScan并不是只能解决“包扫描不到”这一个问题，它也能解决“不同数据源对应不同Mapper包”的问题。

3.3 推荐方案二：每个 Mapper 接口单独加 @Mapper

在Mapper接口上单独加@Mapper注解，这个方案适合Mapper数量少、包路径简单的小项目。比如：

@Mapper public interface UserMapper { User findById(@Param("id") Long id); }

但要注意，@Mapper注解要真正生效，仍然需要MyBatis扫描器的作用范围覆盖到这个接口。如果你的启动类在父包、Mapper在子包，接口上写了@Mapper而不配置任何扫描路径，很多时候依然不行。

更准确的理解是：@Mapper是MyBatis扫描器识别接口时的“准入标记”，但扫描器本身的搜索范围由@MapperScan或自动配置决定。在大多数需要修复的项目里，单独加@Mapper并不能解决问题，必须配合扫描路径的调整。

如果你的项目确实很适合只用@Mapper方案，那请确保：启动类在模块根包下，Mapper接口在启动类所在包或更深的子包内，而且MyBatis的自动配置模块正常工作。这种情况下，@Mapper注解才会被正确识别。

3.4 推荐方案三：通过配置类手动扫描

这种方案适合不想在启动类上堆注解的场景。可以新建一个单独的配置类：

@Configuration @MapperScan(basePackages = "com.example.mapper") public class MybatisConfig { // 这里可以继续补充 SqlSessionFactory、transactionManager 的定制 }

用配置类的优势有几个。一是把扫描逻辑和业务启动逻辑分开，后期维护定位更清晰。二是可以在同一个配置类里叠加其他MyBatis配置项，比如分页插件、自定义拦截器。三是当项目里存在多个数据源时，可以通过多个配置类分别配置各自的MapperScan。

需要注意，如果项目里同时存在多个@MapperScan，不要让它们扫描到同一个Mapper包，否则同一个接口会被注册两次，出现BeanDefinition冲突。虽然最终可能不会导致启动失败，但动态代理对象会混乱，排查起来非常费劲。

3.5 XML 文件导致的“扫描到了但启动仍失败”

如果经过排查，确认Mapper Bean本身已经注册成功，但调用某个Mapper方法时抛出Invalid bound statement，那要检查XML映射文件。

标准做法如下。

第一步，把XML文件放到src/main/resources目录下的mapper子目录中：

src/main/resources/mapper/UserMapper.xml

第二步，在application.yml中配置：

mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.entity

第三步，确认XML的namespace是Mapper接口的全限定名：

<mapper namespace="com.example.mapper.UserMapper"> <select id="findById" resultType="com.example.entity.User"> select * from user where id = #{id} </select> </mapper>

一个特别容易踩的细节：如果XML文件放在resources目录下的包路径中，例如src/main/resources/com/example/mapper/UserMapper.xml，那mapper-locations要写成classpath:com/example/mapper/.xml，而不是classpath:mapper/.xml。目录结构相似并不代表配置一致，这一点总是有人弄混。

4. 排查思路与避坑指南

4.1 常见问题速查表

4.2 从报错日志判断问题类型

一个成熟的开发者在遇到报错时，第一件事不是改代码，而是读日志。针对扫描不到Mapper的问题，日志的不同形态对应不同的问题。

形态一：UnsatisfiedDependencyException，内部有that could not be found字样。这类是真正的Bean缺失，最典型的就是@Autowired注入Mapper时，容器里没有任何候选Bean。处理方向以扫描路径配置为主。

形态二：MapperFactoryBean相关的BeanDefinitionStoreException。这类是Mapper接口被扫描到了，但构建MapperFactoryBean时出了问题，比如接口上有不支持的返回类型、泛型不匹配。这种问题不要急着加@MapperScan，而是看具体异常信息，通常是接口定义本身写得不对。

形态三：一切启动看起来正常，但调用任何Mapper方法都报Invalid bound statement。这类是XML映射文件没加载，和@Mapper扫描没有直接关系，但容易被误判成“扫描不到”。还有一种是项目里存在两个同名Mapper接口，分布在不同的包下，MyBatis根据简单类名去找XML时找错了位置，也会出现类似的问题。

4.3 一些容易被忽略的细节

细节一，包名拼写问题。这种错误看着低级，但真实项目里发生率很高。比如Mapper包名称是com.example.modules.user.mapper，你在@MapperScan里写成了com.example.module.user.mapper，漏了一个s，启动时不会有任何报错提示，MyBatis只是默默扫了个空目录，然后你对着“Bean找不到”的报错发呆很久。这种问题排查起来只能靠肉眼逐字符对照，我最常用的小技巧是直接把包名复制粘贴到@MapperScan里，而不是手动敲。

细节二，@MapperScan写在自定义组合注解上可能失效。有些项目把@MapperScan和@SpringBootApplication组合到一个自定义注解里，开发时可能遇到注解元数据被丢失或者加载顺序不对的问题。遇到这种奇怪的失效情况，可以试试把@MapperScan直接写在主启动类上，排除自定义注解的干扰。

细节三，IDEA编译产物的问题。如果你改了Mapper接口的包路径，但IDEA没有重新编译，target目录下的classes还是旧路径，启动时MyBatis扫描的是target/classes里的旧类，自然对不上号。遇到这种情况，先执行mvn clean compile，或者手动清理target目录后再重新构建，再排查代码逻辑。

细节四，多模块项目中的依赖版本问题。如果你的user-service模块引用了common-mapper模块，但common-mapper模块没有重新install到本地仓库，user-service拿到的本地仓库里还是旧版本的jar包，里面根本没有你新增的Mapper接口。这类多模块问题表面上是“扫不到”，实际上是“依赖包版本过期”，检查其他模块前，先确认你引用的jar包确实是最新的。

4.4 我的实操心得

说一个我自己经历过的案例。某次接手一个老项目，模块结构很乱，启动类和Mapper接口完全不在一个包路径下，而且历史代码里每个Mapper都写了@Mapper，但没有任何@MapperScan。一开始我也在接口注解上做文章，加注解、改注解，折腾半天没有效果。后来把项目结构画在纸上，才看清楚启动类在com.xxx.application包下，Mapper在com.xxx.domain.mapper包下，两个包的公共祖先是com.xxx，但启动类所在的application包路径跟domain包没有包含关系。MyBatis默认扫描从启动类所在包开始，压根扫不到domain包。

解决方案其实特别简单，在启动类上加一行@MapperScan("com.xxx.domain.mapper")就解决了。但这件事给我的教训是：排查这类问题，先画包路径覆盖关系图，比盯着报错瞎猜高效太多。从那以后，我写Spring Boot项目，启动类和配置类一定放在根包下，Mapper也尽量统一放在同一个包路径里，并且启动类上一律用@MapperScan显式声明。这套习惯帮我少踩了很多坑。

还有一个细节：如果项目里同时又@Mapper注解又加@MapperScan，记得检查扫描目标是否重复。有些团队两套机制都上了，运行很久没出过事，是因为扫描目标恰好不冲突，但这种设计很脆弱，一旦接口路径变动，就会冒出各种莫名其妙的代理异常。

关于XML文件，我强烈建议把XML和Mapper接口分开放置，XML统一放在resources/mapper下，跟接口不要混在同一个资源目录。因为混在一起时，Maven打包很容易出现资源过滤问题，尤其某些pom配置会把resources目录指定类型过滤掉，导致XML没有被打进jar包。检查时可以执行jar tf命令查看jar包内容，确认XML文件是否真的在里面。

最后再分享一个小技巧。如果项目的多模块、多数据源结构特别复杂，排查@Mapper扫描不到的问题时，可以先搭一个最简单的Demo工程做对照实验。把同样结构的Mapper接口和启动类搬到一个干净工程里，如果干净工程能启动，说明主项目里一定存在某段配置破坏了扫描逻辑，再逐项对比配置差异，就能快速定位。这个方法我在复杂项目里用了很多次，基本都能在十分钟内锁定问题。

如果你下次再遇到Spring Boot + MyBatis项目扫描不到@Mapper的报错，别急着动手改代码，先按文章里的思路确认故障类型，再对照速查表选择对应方案。大部分情况下，加一行@MapperScan指定正确的包路径就能解决问题；如果还不行，就按依赖、XML、编译产物这几个方向逐一排查，总能找到根源。