MyBatis BindingException 完整排查指南：Invalid bound statement (not found)

錯誤現象

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)

核心原因：**Mapper 介面與 XML 映射檔的對應關係斷裂**。

標準排查清單（按優先序）

1. 套件名稱一致性

XML 檔案所在套件路徑必須與 Mapper 介面完全一致。

// 介面
package com.example.mapper;
public interface UserMapper { ... }


src/main/resources/com/example/mapper/UserMapper.xml

2. Namespace 精確匹配

<mapper namespace="com.example.mapper.UserMapper">

Namespace 必須是 Mapper 介面的**完整限定名**，區分大小寫。

3. 方法名稱與 ID 一致

// 介面
User selectById(@Param("id") Long id);


<select id="selectById" resultType="User">
    SELECT * FROM user WHERE id = #{id}
</select>

id 屬性必須與介面方法名**完全相同**。

4. 參數類型與 #{ } 占位符對應

• 單一參數：#{paramName} 或 #{ }
• 多參數：介面需加 @Param("name")，XML 使用 #{name}
• POJO 參數：直接使用屬性名 #{username}

5. XML 內容乾淨度

• 移除 XML 中的中文註釋（部分解析器不支援）
• 確保無隱形字元、BOM 頭
• 嘗試在 XML 中加入空行或空格後重新儲存（強制 IDE 重新識別）

IDEA / Maven 專案常見坑：資源檔未複製到 target

現象：原始碼目錄有 XML，但 target/classes 下沒有對應的 Mapper XML。

解決：在 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 統一放置於 src/main/resources 目錄結構中（推薦）。

進階排查技巧

1. 啟用 MyBatis 日誌：logging.level.com.example.mapper=DEBUG，觀察實際執行的 SQL 與綁定情況
2. 檢查別名配置：typeAliasesPackage 是否涵蓋實體類別
3. 驗證 Mapper 掃描路徑：@MapperScan("com.example.mapper") 或 XML <package> 配置
4. 清理重建：mvn clean compile 或 IDE Invalidate Caches / Restart

快速自檢表單

總結

90% 的 BindingException 歸因於 **Namespace、方法名、參數綁定、資源輸出** 四大類問題。建立標準化的 Mapper 開發規範（套件結構、命名慣例、資源配置），可從源頭杜絕此類錯誤。