MyBatis-Plus中mapper-locations配置无效如何解决？

Question

在使用 MyBatis-Plus 时，开发者常通过 `mapper-locations` 配置项指定 XML 映射文件的位置。然而，有时即使配置了该参数，系统仍无法正确加载 XML 文件，导致出现 `Invalid bound statement not found` 等异常。此类问题通常源于配置路径不正确、通配符使用不当、资源未正确打包至目标目录，或与 Spring Boot 的自动扫描机制冲突。此外，Maven 或 Gradle 构建工具未正确配置资源过滤，也可能导致 XML 文件未被正确识别。本文将深入分析 `mapper-locations` 配置无效的常见原因，并提供解决方案，帮助开发者快速定位并解决问题。

Answer 1

一、引言：MyBatis-Plus 中 mapper-locations 配置无效的常见问题

在使用 MyBatis-Plus 时，开发者常通过 mapper-locations 配置项指定 XML 映射文件的位置。然而，有时即使配置了该参数，系统仍无法正确加载 XML 文件，导致出现 Invalid bound statement (not found) 等异常。本文将深入分析此类问题的常见原因，并提供对应的解决方案。

二、常见配置路径问题

• 路径拼写错误：例如将 classpath:mapper/*.xml 错写为 classpath:mappr/*.xml，导致资源无法加载。
• 路径未使用 classpath 前缀：若未使用 classpath: 前缀，MyBatis-Plus 会尝试从文件系统中查找文件，而非类路径中查找。
• 通配符使用不当：如 classpath:mapper/**/*.xml 表示递归查找所有子目录，而 classpath:mapper/*.xml 仅查找当前目录下的文件。

三、Spring Boot 自动扫描机制冲突

Spring Boot 默认会自动扫描 resources/mapper 路径下的 XML 文件。如果开发者手动配置了 mapper-locations，但路径与默认扫描路径冲突，可能导致部分文件未被加载。

mybatis-plus.mapper-locations=classpath*:mapper/**/*.xml

建议统一配置路径，避免冲突。

四、资源未正确打包至目标目录

在使用 Maven 或 Gradle 构建项目时，XML 文件未正确配置资源过滤可能导致其未被复制到 target/classes 目录下。

构建工具	资源配置示例
Maven	<resources> <resource> <directory>src/main/resources</directory> <includes> <include>mapper/**/*.xml</include> </includes> </resource> </resources>
Gradle	sourceSets { main { resources { srcDirs = ["src/main/resources"] includes = ["mapper/**/*.xml"] } } }

五、MyBatis-Plus 配置流程图

            graph TD
                A[开始配置 mapper-locations] --> B{路径是否正确?}
                B -- 是 --> C{是否使用通配符?}
                C -- 是 --> D[是否与 Spring Boot 默认扫描路径冲突?]
                D -- 是 --> E[调整路径避免冲突]
                D -- 否 --> F[配置成功]
                C -- 否 --> G[确认通配符使用是否合理]
                B -- 否 --> H[修正路径拼写错误]
                H --> B
        

六、构建工具资源过滤配置问题

若构建工具未正确配置资源过滤，XML 文件可能未被正确识别并复制到构建输出目录。

• Maven：确保 pom.xml 中的 <resources> 配置包含 XML 文件路径。
• Gradle：确保 build.gradle 中的 sourceSets 包含正确的资源目录。

七、验证配置是否生效的方法

开发者可以通过以下方式验证 XML 文件是否被正确加载：

• 检查 target/classes 目录下是否存在 XML 文件。
• 启用 MyBatis 日志输出，查看加载的映射文件列表。
• 使用 Spring Boot Actuator 的 /actuator/mappings 接口查看已注册的映射路径。

八、高级调试技巧与日志分析

在日志中搜索 Scanning for mappers 或 Loading XML bean definitions 可以帮助判断 XML 文件是否被正确扫描和加载。

logging.level.org.mybatis.spring.mapper=DEBUG
logging.level.org.apache.ibatis=DEBUG

通过启用调试日志，开发者可以更清晰地看到 MyBatis 的加载流程。