spring中的@MapperScan注解详解

一、核心功能与作用

@MapperScan是Spring与MyBatis框架集成时用于批量扫描Mapper接口的核心注解，其主要功能包括：

自动注册Mapper接口
通过指定包路径，Spring会自动扫描该路径下的所有Mapper接口，并将其注册为Spring Bean，无需手动为每个接口添加@Mapper注解。
简化配置
替代传统XML配置或逐个接口声明，支持通过通配符或数组指定多个包路径，提升开发效率。
支持多数据源
结合sqlSessionTemplateRef和sqlSessionFactoryRef属性，可为不同数据源指定独立的SQL会话工厂或模板。

前些天发现了一个巨牛的人工智能学习网站，通俗易懂，风趣幽默，忍不住分享一下给大家。点击跳转到网站

二、注解属性解析

@MapperScan提供多种属性用于灵活控制扫描行为：

基础扫描路径
- value / basePackages：指定要扫描的包路径（支持数组形式），例如：
  java 复制代码
```
@MapperScan(basePackages = {"com.example.mapper", "com.example.dao"})
```
- basePackageClasses：通过类的包路径定位扫描范围（类型安全），例如：
  java 复制代码
```
@MapperScan(basePackageClasses = {UserMapper.class})
```
过滤条件
- annotationClass：仅扫描带有指定注解的接口（默认扫描所有接口）。
- markerInterface：仅扫描继承指定父接口的接口。
多数据源支持
- sqlSessionFactoryRef：指定使用的SqlSessionFactory Bean名称（多数据源场景）。
- sqlSessionTemplateRef：指定使用的SqlSessionTemplate Bean名称。
其他高级属性
- nameGenerator：自定义Bean名称生成器。
- lazyInitialization：延迟初始化Mapper Bean，优化启动性能。

三、底层实现原理

动态代理与Bean注册
- 扫描阶段：Spring通过ClassPathMapperScanner扫描指定包路径下的接口，生成BeanDefinition。
- 代理生成：将扫描到的接口的BeanClass设置为MapperFactoryBean，利用MyBatis动态代理技术生成实现类。
- 注册容器：通过MapperScannerRegistrar将Bean定义注册到Spring容器，完成依赖注入。
条件过滤机制

自动排除非接口类，仅处理符合条件（如带有@Mapper注解或满足markerInterface）的接口。

四、使用场景与最佳实践

Spring Boot项目启动类

在启动类上直接使用@MapperScan，简化全局配置：

java 复制代码

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

多模块项目扫描

支持通配符路径匹配多模块：
java 复制代码
```
@MapperScan("com.example.*.mapper")
```

与@Configuration结合

在非Spring Boot项目中，通过配置类显式声明：

java 复制代码

@Configuration
@MapperScan(basePackages = "com.example.dao")
public class MyBatisConfig {
    // 其他数据源配置
}

五、注意事项与常见问题

包路径匹配
- 确保扫描路径包含所有Mapper接口，否则导致Bean未注入错误。
- 避免不同模块中同名接口导致冲突。
注解优先级
- 若同时使用@Mapper和@MapperScan，@Mapper优先级更高，仅注册显式标记的接口。
多数据源配置

需为每个数据源单独指定sqlSessionFactoryRef，并配合@Primary注解解决Bean冲突。
代理限制

Mapper接口不支持方法重载，因XML映射的ID需唯一。

六、总结

@MapperScan通过自动化扫描与动态代理机制，极大简化了MyBatis Mapper接口的集成流程。合理使用其属性（如多路径扫描、多数据源支持）可应对复杂项目需求，而理解其底层原理（如MapperScannerRegistrar的作用）有助于排查配置错误。在大型项目中，建议结合basePackageClasses提高路径安全性，并通过lazyInitialization优化启动性能。