NStarfaiNet 採用類似 iBATIS.NET 的 SQL XML 映射機制，將 SQL 陳述式外部化至 XML 檔案，支援動態條件組裝、參數綁定與多語句管理。語法簡潔易懂，採用 $var$ 統一變數符號 (不支援 #, ? 等)，適合輕量級專案快速開發。
XML 基礎結構
<?xml version="1.0" encoding="utf-8"?>
<statements>
<select id="SelectTest">
SELECT * FROM bsi_test WHERE 1=1
<dynamics>
<dynamic prepend="and" property="test_name"
value="upper(test_name)=upper('$test_name$')" />
</dynamics>
ORDER BY test_id
</select>
</statements>
核心元素說明
| 元素/屬性 | 用途 | 範例 |
|---|
<statements> | 根元素，包含多個 SQL 定義 | — |
<select|insert|update|delete> | 定義四類 SQL，id 為呼叫鍵值 | id="GetUserById" |
<dynamics> | 動態 SQL 容器，包含一或多個 <dynamic> | — |
<dynamic> | 單一動態條件片段 | 見下表屬性 |
<dynamic> 關鍵屬性
| 屬性 | 說明 | 範例值 |
|---|
prepend | 條件前綴關鍵字，自動處理首條件無 AND/WHERE 問題 | and, or, where |
property | 對應參數物件屬性名稱 (判斷是否為 null/空字串) | test_name |
value | SQL 片段模板，$prop$ 會被參數值取代 | upper(test_name)=upper('$test_name$') |
動態條件運作邏輯
- 若參數物件中
test_name 非 null 且非空字串 → 產生 AND upper(test_name)=upper('實際值')。
- 若參數為 null 或空字串 → **整個
<dynamic> 片段被忽略**，不產生任何 SQL 片段。
- 多個
<dynamic> 依序組合，prepend 自動銜接。
進階範例：多條件動態查詢
<select id="SearchOrders">
SELECT o.*, c.name AS cust_name
FROM orders o JOIN customers c ON o.cust_id=c.id
WHERE 1=1
<dynamics>
<dynamic prepend="and" property="cust_id" value="o.cust_id = $cust_id$" />
<dynamic prepend="and" property="status" value="o.status = $status$" />
<dynamic prepend="and" property="date_from" value="o.order_date >= '$date_from$'" />
<dynamic prepend="and" property="date_to" value="o.order_date <= '$date_to$'" />
</dynamics>
ORDER BY o.order_date DESC
</select>
與 iBATIS.NET 差異比較
| 特性 | NStarfaiNet | iBATIS.NET |
|---|
| 變數符號 | $var$ (單一) | #var# (值), $var$ (字串替換) |
| 動態標籤 | <dynamic> | <isNotNull>, <isGreaterThan> 等豐富標籤 |
| 參數映射 | 依 property 名稱直接對應 | parameterMap 獨立定義 |
| 複雜度 | 極簡，學習曲線平緩 | 功能完整，支援複雜關聯、緩存、事務 |
使用建議
- 僅適用於 **簡單 CRUD 與動態 WHERE 組裝** 場景。
- 複雜報表、多表關聯、批次操作、存儲程序調用建議改用 Dapper / EF Core / 原生 ADO.NET。
- 參數值直接字串替換，**注意 SQL 注入風險**，確保輸入經過驗證或僅用於內部可信呼叫。
