一、MyBatis 的默认 Mapper XML 文件路径

默认情况下，MyBatis 在启动时会扫描：

classpath*:/mapper/**/*.xml

也就是说：

• 默认在 resources 目录下；

• 文件夹名通常叫 mapper；

• 可以有多级子目录；

• 所有 .xml 文件都会被扫描。

---

🧱 举例（默认结构）

标准项目目录（推荐写法）：

src
 └─ main
     ├─ java
     │   └─ com/itheima/mapper/ArticleMapper.java
     └─ resources
         └─ mapper
             ├─ ArticleMapper.xml
             ├─ CategoryMapper.xml
             └─ UserMapper.xml

配置文件（application.yml）中默认就会识别：

mybatis:
  mapper-locations: classpath:/mapper/**/*.xml
  type-aliases-package: com.itheima.pojo

---

1-1、解释一下 classpath

• classpath: 指打包后（target/classes）中的根路径；

• resources 下的所有文件都会自动复制到 target/classes；

• 而 java 下的源码（.java）编译后只有 .class 文件；
  所以如果你把 xml 放在 java 里，MyBatis 默认扫描不到。

---

🔍 验证路径的方法

你可以在启动日志中搜索：

Loading XML resource: 'mapper/ArticleMapper.xml'

如果能看到类似日志，说明加载成功。
如果报错：

Invalid bound statement (not found)

说明 xml 没被扫描到，要么路径不在 classpath，要么 mapper-locations 配置不对。

---

💡对比总结

项目结构	是否能默认识别	原因
✅ resources/mapper/*.xml	是	默认 classpath 路径
✅ resources/com/itheima/mapper/*.xml	是	仍在 classpath 下
⚠️ java/com/itheima/mapper/*.xml	否	不在 classpath，需修改 pom
✅ java/com/itheima/mapper/xml/*.xml	可以	配合 pom + mapper-locations

---

二、一一对应的包路径镜像

问题：不是说resources下的文件路径要和main/java中的一样吗？也就是说com/itheima/mapper/ArticleMapper.java 对应 com/itheima/mapper/ArticleMapper.xml？

你说的这种“一一对应的包路径镜像”是常见约定，但不是硬性要求。

MyBatis 绑定 Mapper 接口 ↔ XML，真正靠的是这两点：

1. XML 的 <mapper namespace> 必须等于接口的全限定名

   <mapper namespace="com.itheima.mapper.ArticleMapper">
       <select id="list">...</select>
   </mapper>
   

2. XML 要能被 MyBatis 扫描到（在 classpath 且被 mapper-locations 匹配）

因此，XML 放哪里都行，只要满足上面两点。

之所以很多项目把 XML 放成与 Java 包路径镜像，是为了好找、IDE 插件（如 MyBatisX）能跳转、避免多人协作混乱。

---

1、两种常见放置方式

方式 A（默认/推荐）：resources/mapper/**.xml

• 目录：

  src/main/resources/mapper/ArticleMapper.xml
  

• Spring Boot Starter 默认就会扫：classpath*:/mapper/**/*.xml
  一般 不用额外配置。

---

方式 B（镜像 Java 包路径）：resources/com/itheima/mapper/**.xml

• 目录：

  src/main/java/com/itheima/mapper/ArticleMapper.java
  src/main/resources/com/itheima/mapper/ArticleMapper.xml
  

• 需要显式指定扫描路径，否则默认的 /mapper/**/*.xml 匹配不到：

  mybatis:
    mapper-locations: classpath*:com/itheima/mapper/*.xml
    type-aliases-package: com.itheima.pojo
  

• 仍需保证 <mapper namespace="com.itheima.mapper.ArticleMapper">。

---

2、常见误区澄清

• ❌ “必须放 resources 下而且路径必须和 Java 完全一致”
  → 不必须，一致只是约定。关键是 namespace 匹配 + mapper-locations 能扫到。

• ❌ “只要在 java 目录里和接口放一起就行”
  → 直接放 src/main/java 下的 XML 不会自动进入 classpath。
  如果一定要放在 java 目录里，需在 pom.xml 里把 **/*.xml 当资源打包。

---

3、对比理解

放置方案	目录例子	mapper-locations 写法	需改 pom？
默认方案	resources/mapper/ArticleMapper.xml	默认即可（classpath*:/mapper/**/*.xml）	否
镜像 Java 包	resources/com/itheima/mapper/ArticleMapper.xml	classpath*:com/itheima/mapper/*.xml	否
放到 java 目录	java/com/itheima/mapper/xml/ArticleMapper.xml	取决于你想扫哪里	✅ 需要把 **/*.xml 打进资源

---

三、项目结构优化

问题：我的xml文件不想写在resources里面，想和mapper类放在一起，比如放在mapper文件夹下的xml文件夹中，我要做什么配置吗？

---

1、为什么默认要求放在 resources？

因为：

• MyBatis 默认只会从 classpath（即 resources）中加载 XML；

• 而 src/main/java 目录下的 .java 文件会被编译为 .class，不会自动包含 XML 文件；

• 所以如果你直接把 .xml 放在 java 目录下，它在运行时会被忽略。

👉 换句话说：

不是 MyBatis 不支持放一起，而是默认编译时没有把这些 XML 打包进 classpath。

---

2、解决方案（推荐方式）

方式一：修改 pom.xml，让 Java 下的 XML 一并打包

这是最推荐的做法，简单、安全。

在 pom.xml 中加入如下配置，让 src/main/java 目录下的 XML 文件也被编译进 classpath：

<build>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.xml</include>
            </includes>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
        </resource>
    </resources>
</build>

📌 效果：

• 你可以把 ArticleMapper.xml 放在：

  src/main/java/com/itheima/mapper/xml/ArticleMapper.xml
  

• 启动项目后，MyBatis 就能正确加载到。

---

方式二：在 application.yml 指定 mapper 路径

不改 pom，只在配置文件中修改路径：

mybatis:
  mapper-locations: classpath*:com/itheima/mapper/xml/*.xml
  type-aliases-package: com.itheima.pojo

📌 注意：

• 前缀要写成 classpath*:；

• 路径分隔符 /；

• 路径要对应 编译后的包路径；

• 但仍需保证你的 XML 能被打包（否则这配置找不到文件）。所以通常还是要配合上面第 1 种做法。

---

方式三：Spring Boot + MyBatis-Plus 写法（如果用 MP）

如果你使用的是 MyBatis-Plus Starter（mybatis-plus-boot-starter），可以这样：

mybatis-plus:
  mapper-locations: classpath*:com/itheima/mapper/xml/*.xml

逻辑一样，只是 key 名不同。

---

3、常见错误（排坑）

错误现象	可能原因	解决办法
启动报错：Invalid bound statement (not found)	XML 没被加载进 classpath	用方式①或②修复
XML 改名后没生效	Maven 缓存未更新	执行 mvn clean compile
配置路径写成反斜杠 \	Windows 特有问题	改成 /
多模块项目中找不到 XML	子模块没配置资源打包	子模块也加上 <resources>

 

---

4、举个最终成品例子

结构：

src
 └─ main
     ├─ java
     │   └─ com/itheima/mapper/
     │       ├─ ArticleMapper.java
     │       └─ xml/
     │           └─ ArticleMapper.xml
     └─ resources
         └─ application.yml

application.yml：

mybatis:
  mapper-locations: classpath*:com/itheima/mapper/xml/*.xml
  type-aliases-package: com.itheima.pojo

pom.xml：

<build>
  <resources>
    <resource>
      <directory>src/main/java</directory>
      <includes>
        <include>**/*.xml</include>
      </includes>
    </resource>
    <resource>
      <directory>src/main/resources</directory>
    </resource>
  </resources>
</build>

这样运行时，XML 会和 class 文件一起被打包，MyBatis 就能自动扫描加载。