iBATIS.NET API 核心架構與 SqlMapper 深度解析

外觀模式簡化資料存取

iBATIS.NET 採用外觀模式封裝複雜的內部物件圖，SqlMapper 類成為開發者唯一的進入點。它內部處理：

• 會話 (IDalSession) 的建立與連線管理
• 映射陳述式 (IMappedStatement) 的查找與執行
• 異常轉換與資源清理

QueryForList 內部實現剖析

public IList QueryForList(string statementName, object parameterObject)
{
    IList list1;
    bool flag1 = false;
    IDalSession session1 = this._sessionHolder.LocalSession;

    // 1. 取得或建立 Session
    if (session1 == null)
    {
        session1 = new SqlMapSession(this.DataSource);
        session1.OpenConnection();
        flag1 = true; // 標記需自行關閉
    }

    // 2. 取得映射陳述式
    IMappedStatement statement1 = this.GetMappedStatement(statementName);

    try
    {
        // 3. 執行查詢
        list1 = statement1.ExecuteQueryForList(session1, parameterObject);
    }
    catch
    {
        throw; // 保留堆疊追踪
    }
    finally
    {
        // 4. 僅當自己建立 Session 時才關閉
        if (flag1)
        {
            session1.CloseConnection();
        }
    }
    return list1;
}

設計亮點

• Session 複用：透過 _sessionHolder.LocalSession 支援巢狀呼叫或同一事務內多次操作共用連線。
• 責任鏈：IMappedStatement 針對不同 SQL 類型（Select/Insert/Update/Delete）提供專屬執行方法，編譯期保證型別安全。

SqlMapper 實例化：單例與多實例

預設單例模式

public static SqlMapper Instance()
{
    if (Mapper._mapper == null)
    {
        lock (typeof(SqlMapper))
        {
            if (Mapper._mapper == null)
            {
                Mapper.InitMapper(); // 載入所有映射檔，初始化較重
            }
        }
    }
    return Mapper._mapper;
}

雙重檢查鎖定確保執行緒安全。首次呼叫會解析所有 SQL Map 檔案，後續複用極快。

自訂實例（多資料庫場景）

使用 DomSqlMapBuilder 手動建構：

// 方式 1：從預設路徑載入
SqlMapper mapper1 = DomSqlMapBuilder.Configure();

// 方式 2：指定設定檔
SqlMapper mapper2 = DomSqlMapBuilder.Configure("sqlmap.config");

// 方式 3：啟用檔案監視，熱重載映射檔
SqlMapper mapper3 = DomSqlMapBuilder.ConfigureAndWatch("sqlmap.config");

適用於：多資料庫、多租戶、動態修改 SQL 等進階場景。

Statement 類型安全機制

每種 SQL 標籤對應專屬 MappedStatement 子類：

• <select> → SelectMappedStatement
• <insert> → InsertMappedStatement

若呼叫錯誤方法（如對 select 陳述式呼叫 ExecuteInsert），框架拋出明確異常：

public override object ExecuteInsert(IDalSession session, object parameterObject)
{
    throw new DataMapperException("Update statements cannot be executed as a query insert.");
}

這在編譯期無法檢查（statementName 為字串），但在執行期快速失效，避免資料損壞。

使用建議

1. 簡單專案直接用 Mapper.Instance() 單例。
2. 需隔離資料庫連線時，建立多個 SqlMapper 實例並註冊到 DI 容器。
3. 嚴格對應 statement 類型與呼叫方法，善用單元測試驗證映射檔正確性。

理解 SqlMapper 內部運作，有助於排查連線洩漏、效能瓶頸及映射錯誤等疑難雜症。