🧩 背景說明

在 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 語句。