pureQuery 註解方法風格深度解析：靜態/動態 SQL 統一、代碼生成與多目標部署

pureQuery 兩大編程風格對比

註解方法風格核心工作流

1. 定義 pureQuery 接口：方法簽名 + 註解 SQL + 返回類型 + 參數類型。
2. Data Studio 代碼生成器預處理接口，生成實現類 (InterfaceImpl)。
3. 編譯生成的代碼，打包部署。
4. 運行時通過 DataFactory.getData(Interface.class, connection) 獲取實例調用。

接口定義範例：SilverCastles 客戶數據訪問

package com.ibm.db2.pureQuery;
import java.util.Iterator;
import com.ibm.pdq.annotation.Select;

public interface CustomerData {
  @Select(sql="SELECT CID, NAME, COUNTRY, STREET, CITY, PROVINCE, ZIP, PHONE, INFO FROM PDQ_SC.CUSTOMER")
  Iterator getCustomers();

  @Select(sql="SELECT CID, NAME, COUNTRY, STREET, CITY, PROVINCE, ZIP, PHONE, INFO FROM PDQ_SC.CUSTOMER WHERE CID = ?")
  Customer getCustomer(int cid);
  // @Update/@Call 類似
}

生成代碼結構解析

• 實現類命名：CustomerDataImpl，實現用戶接口，繼承內部 BaseData (實現 Data 接口)。
• 每方法生成元素：方法體、StatementDescriptor (SQL 元數據)、RowHandler/ResultHandler (結果映射)、ParameterHandler (參數綁定)。
• 開發者無需維護生成代碼，僅作為檢查參考。

運行時調用示例

Connection con = ...;
CustomerData cd = DataFactory.getData(CustomerData.class, con);
Iterator customers = cd.getCustomers(); // 自動執行 SQL、映射結果、返回 Iterator
Customer c = cd.getCustomer(123);

進階特性詳解

1. Hook 機制：橫切關注點無侵入織入

public class TrackingHook implements Hook {
  public void pre(String methodName, Data instance, SqlStatementType sqlType, Object... params) {
    System.out.println(methodName + " **Customer data accessed**");
  }
  public void post(String methodName, Data instance, Object returnValue, SqlStatementType sqlType, Object... params) {
    // 後處理：日誌、審計、緩存失效等
  }
}

// 註冊
CustomerData cd = DataFactory.getData(CustomerData.class, con, new TrackingHook());

參數提供上下文感知：方法名、SQL 類型、運行時參數、返回值，支持靈活的 AOP 風格擴展。

2. 批量更新：集合參數自動展開

在 @Update 方法聲明集合類型參數，pureQuery 引擎自動識別並生成批量執行邏輯，單條 SQL 多參數集執行，大幅提升吞吐。

3. 生成鍵自動回填：@GeneratedKey 註解

Bean 字段標註 @GeneratedKey，插入/更新後數據庫生成的主鍵/序列值自動回填至 Bean 對象，省去手工查詢。

4. XML 配置文件：多目標數據庫 SQL 隔離

場景：同一應用部署至不同 Schema 的遺留數據庫 (列名差異：CID vs CUSTID、PROVINCE vs PROV)。

生成器讀取 XML 產出差異化實現，Java 接口與 Bean 完全復用，實現「一次開發、多庫部署」。

最佳實踐建議

• 接口粒度：按業務領域劃分 (如 CustomerData、OrderData)，單一職責。
• SQL 可讀性：註解中 SQL 格式化換行，便於評審與維護。
• 靜態 SQL 決策：生產環境核心高頻查詢啟用靜態綁定 (安全、性能、鎖定訪問路徑)，邊緣查詢保持動態。
• 版本控制：將生成的 Impl 類納入版本庫，確保構建可重現。
• 測試策略：單元測試針對接口 Mock，集成測試驗證生成代碼與數據庫交互正確性。

總結

pureQuery 註解方法風格以「接口即契約、註解即 SQL、生成即實現」的模式，將數據訪問層提升至領域建模層面。靜態/動態 SQL 部署時決策、Hook 橫切擴展、XML 多目標隔離等特性，精準解決企業級應用在安全合規、異構遷移、性能調優中的長期痛點，是 JDBC 之上的現代化數據訪問最佳實踐之一。