IBM pureQuery 內聯方法風格實戰：簡化 JDBC、動態 SQL 與結果映射

為什麼選擇內聯風格？

pureQuery 提供兩種編程風格：內聯方法 與 帶註解方法。內聯風格將 SQL 字串直接寫在 Java 代碼中，透過 Data 介面執行，優點在於：

• SQL 可見、易除錯、支援運行時動態組裝。
• API 簡潔，自動處理 PreparedStatement、資源關閉、結果集映射。
• 內建批次更新、自動生成鍵值回傳、可插入式 RowHandler/ResultHandler。

核心 API 速覽

參數綁定風格

• JDBC 風格：VALUES(?, ?, ?) + 位置參數
• 命名參數：VALUES(:name, :country) + pureQuery Bean / Map 自動對應屬性

結果映射三種模式

1. 預設映射：依欄位名與 Bean 屬性名對應 (大小寫不敏感)，支援 @Column、@Id、@GeneratedKey 註解微調。
2. RowHandler：自訂單列映射邏輯，實作 handle(ResultSet, T)，適用複雜轉換或省略欄位。
3. ResultHandler：處理整個結果集，可輸出 XML/JSON/串流至其他系統。

自動生成鍵值回傳

// 1. 使用 Bean，@GeneratedKey 欄位自動回填
Customer c = new Customer(...);
data.update(insertSql, c);
System.out.println(c.getCid()); // 自動生成的主鍵

// 2. 不用 Bean，指定回傳類型與欄位名
int key = data.update(insertSql, int.class, new String[]{"cid"}, params...);
Object[] arr = data.update(insertSql, Object[].class, new String[]{"cid"}, params...);
// arr[0] = generated key, arr[1] = update count

Hook 可插入式攔截器

實作 Hook 介面，於建立 Data 時註冊：

Data db = DataFactory.getData(conn, new Hook() {
    public void pre(String method, Data d, SqlStatementType type, Object... params) {
        if (type == SqlStatementType.INSERT) {
            Customer c = (Customer) params[0];
            if (!allowedCountries.contains(c.getCountry()))
                throw new DataRuntimeException("Country not allowed: " + c.getCountry());
        }
    }
    public void post(String method, Data d, Object ret, SqlStatementType type, Object... params) {
        // 記錄審計日誌、效能監控等
    }
});

Silver Castle 完整範例流程

1. 建立 Customer Bean (含 @Id @GeneratedKey)。
2. Data data = DataFactory.getData(conn);
3. data.update("delete from customer"); 清空資料。
4. 單筆/批次插入測試資料。
5. List<Customer> list = data.queryList("select * from customer where country=?", Customer.class, "US");
6. 驗證自動生成鍵值、Hook 攔截非法國家插入。