如何设置MyBatis配置文件mybatis-config.xml中的typeAliasesPackage包扫描？

本文共计951个文字，预计阅读时间需要4分钟。

MyBatis中的`typeAliasesPackage`配置不是魔法般生效的，它依赖于类路径扫描来识别和加载相应的类。具体来说，它依赖于类加载器和类路径扫描器来找到指定包路径下的所有类。

常见现象是配置了`com.example.model`，但MyBatis没有找到对应的类。这可能是因为：

原因通常是：

• 实际 class 文件没被编译到 target/classes 对应路径下（比如 IDE 没自动编译，或 Maven 编译跳过）
• 包名拼写错误，尤其大小写敏感（model ≠ Model）
• 该包在多个 module 中存在，但 MyBatis 加载的是另一个 classloader 下的副本
• Spring Boot 场景下，若用 @MapperScan + 自动配置，mybatis-config.xml 中的 typeAliasesPackage 可能被忽略（Spring Boot 默认不读这个文件）

Spring Boot 中 typeAliasesPackage 失效？优先用 @MapperScan 或 mybatis.type-aliases-package

Spring Boot 整合 MyBatis 时，mybatis-config.xml 默认不被加载——除非你显式配置了 SqlSessionFactoryBean.configLocation。所以直接在 XML 里写 <typeAliasesPackage name="com.example.domain"/> 基本无效。

正确做法是：

• 删掉 mybatis-config.xml 中的 typeAliasesPackage，改用 Spring Boot 配置项：mybatis.type-aliases-package=com.example.domain
• 或在启动类/配置类上加注解：@MapperScan(basePackages = "com.example.mapper", sqlSessionFactoryRef = "sqlSessionFactory")（注意：这不负责别名，仅扫 Mapper 接口）
• 如果必须用 XML 配置，需手动指定：sqlSessionFactoryBean.setConfigLocation(new ClassPathResource("mybatis-config.xml"))

别名冲突：同名类在不同包下，typeAliasesPackage 会覆盖还是报错？

typeAliasesPackage 扫描时，对每个类取简单类名（如 User）作为默认别名。如果 com.a.User 和 com.b.User 同时被扫到，MyBatis 会静默覆盖——后加载的类覆盖先加载的，且不报错。

后果是：你在 SQL 中写 resultType="User"，实际映射的可能是你完全没预料到的那个 User。

避免方式：

• 禁止跨包使用相同简单类名（团队规范）
• 显式注册别名，用 <typeAlias alias="AUser" type="com.a.User"/> 替代包扫描
• 扫描更窄的包路径，比如只扫 com.example.domain.user，而非整个 com.example.domain

typeAliasesPackage 性能影响小，但别滥用递归扫描

MyBatis 扫描包本质是遍历 classpath 下所有 .class 文件，匹配包前缀。只要包路径明确、不含通配符，开销几乎可忽略。

但要注意：

• 不要写成 typeAliasesPackage="com" —— 这会扫整个 com 下所有 jar 和目录，启动变慢，还可能撞上 JDK 或第三方类（如 com.sun.*）导致异常
• 扫描路径末尾不加 .*，MyBatis 自动处理；写成 com.example.model.* 反而可能失效（部分旧版本不兼容）
• IDE 里如果看到 “Class not found” 提示，别急着改配置，先 mvn clean compile 或刷新项目，确保 class 文件存在

真正容易被忽略的是：别名注册发生在 SqlSessionFactory 构建阶段，一旦构建完成，再改包路径或加新类都无效——必须重启应用。线上排查时，别在日志里翻半天，先确认是不是刚加的类根本没进 classpath。