MyBatis Invalid bound statement 錯誤排查指南：常見原因與 WAR 包遺漏 XML 解決方案

MyBatis Invalid bound statement 錯誤排查指南

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found) 是 MyBatis 開發中常見錯誤，通常因 Mapper 介面與 XML 對應不一致導致。本文提供系統排查步驟與一個實戰案例（WAR 包遺漏 XML）。

常規解決步驟

1. 檢查 XML 檔案所在 package 名稱是否與 Mapper 介面 package 一致。
2. 檢查 XML 的 namespace 是否等於 Mapper 介面全限定名。
3. 檢查方法名稱（id 屬性）是否完全對應。
4. 移除 XML 中的中文註釋（某些版本解析器不支援）。
5. 在 XML 中任意新增空格/空行並儲存（強制 IDE 重新識別）。

執行上述步驟通常能解決 90% 的情況。

實戰案例：本地正常、發布到伺服器失敗

錯誤現象

Should roll back transaction but cannot - no transaction available
org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)

根本原因

WAR 包中找不到 MyBatis 的 *Mapper.xml 檔案。Maven 打包時預設只包含 src/main/resources 下的資源，若 XML 放在 src/main/java 需額外配置。

解決方案：修改 pom.xml 資源配置

<resources>
    <resource>
        <directory>src/main/java</directory>
        <includes>
            <include>**/*.xml</include> <!-- 關鍵：包含 java 目錄下的 XML -->
        </includes>
    </resource>
    <resource>
        <directory>src/main/resources</directory>
    </resource>
</resources>

重新打包部署即可解決。

總結

開發時嚴格對應 namespace、package、方法名；打包時確保資源檔案被納入 WAR/JAR。建議統一將 Mapper XML 放置於 src/main/resources 對應 package 下，避免額外配置。