🧩 背景说明

在 Spring Boot 中，MyBatis 默认要求 Mapper 接口和 XML 文件位于相同包路径。
但在实际项目中，为了模块化或结构清晰，常将 XML 放在 resources/mybatis/... 下，这种做法就必须进行额外配置。

---

📁 示例目录结构

src/main/java
└── com/example/mapper└── UserMapper.javasrc/main/resources
└── mybatis/mappers└── UserMapper.xml  ← ❗ 不在同包下

---

✅ 解决方案

方式一：application.yml 配置

mybatis:mapper-locations: classpath:mybatis/mappers/*.xmltype-aliases-package: com.example.pojo  # 实体类包路径（可选）

方式二：application.properties 配置

mybatis.mapper-locations=classpath:mybatis/mappers/*.xml
mybatis.type-aliases-package=com.example.pojo

---

💡 通配符说明

配置路径	含义说明
classpath:mybatis/mappers/*.xml	匹配 mappers/ 下所有 XML 文件
classpath:mybatis/**/*.xml	匹配多级子目录中的所有 XML 文件

⚠️ classpath: 起始路径是 resources/。

---

🧠 注意事项

• mapper-locations 是必须配置的（当 XML 和接口不在一起时）。

• type-aliases-package 建议配置，可省略 XML 中类的全限定名。

• 如果你使用的是多模块项目，建议使用 classpath*: 前缀来全局扫描。

---

🔍 @MapperScan 配置

在启动类中加上：

@MapperScan("com.example.mapper")  // Mapper 接口所在包
@SpringBootApplication
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}
}

---

⚠️ 常见报错与原因

报错信息	原因说明
Invalid bound statement (not found)	XML 文件未被扫描
BindingException: Invalid bound statement	同上
类路径很长不易读	没配 type-aliases-package

---

✅ 总结一句话

当 Mapper 接口和 XML 文件不在同一包时，必须在配置文件中手动指定 XML 路径 mapper-locations，否则无法绑定 SQL 语句。