Query Builder / Row Mapper 實作前確認
1. 文件目的
本文件整理進入 MySqlSchemaInspector Query Builder / Row Mapper 第一版實作前的確認項目，目標是把可實作範圍、預計新增類別、方法、測試檔、影響範圍與停止線先列清楚。
本節點仍不導入 MySqlConnector、不修改 .csproj、不連線 MySQL、不讀取真實 information_schema、不執行 DDL，也不調整 ConsoleHost 啟動方式。
2. 實作目標
本批建議只做「不依賴真實 DB 的純程式元件」。
| 目標 | 說明 |
|---|---|
| Query Builder | 產生 table / column / index metadata 查詢字串與參數名稱 |
| Metadata Row Model | 表示 information_schema 查詢結果的 table / column / index row |
| Row Mapper | 將 metadata row 轉成 schema model 可使用的中間結構 |
| Snapshot Assembler | 將 table / column / index metadata 組成 schema snapshot |
| 單元測試 | 驗證 SQL 條件、參數化、nullable / unique / primary key / composite index mapping |
3. 明確不做
| 不做項目 | 原因 |
|---|---|
不新增 MySqlConnector | 新增 NuGet package 需使用者確認 |
不修改 .csproj | 避免影響 restore / build |
| 不建立真實 connection string | 避免密碼與環境資訊進入 repo |
| 不連線 MySQL | 外部服務操作需另行確認 |
不讀取真實 information_schema | 真實 DB metadata 存取需另行確認 |
| 不執行 DDL | 會修改資料庫 |
| 不改 ConsoleHost 啟動方式 | 會影響使用流程 |
| 不改 public method 簽章 | 避免破壞既有契約 |
4. 建議新增類別
以下命名為建議，實作時仍需依程式 repo 現有 namespace 與資料夾調整。
| 類別 | 建議用途 | 是否 public |
|---|---|---|
MySqlSchemaInspectorQueryBuilder | 產生 metadata 查詢 | internal 優先 |
MySqlSchemaQuery | 包裝 SQL text 與 parameter names | internal 優先 |
MySqlTableMetadataRow | table metadata row | internal 或測試可見 |
MySqlColumnMetadataRow | column metadata row | internal 或測試可見 |
MySqlIndexMetadataRow | index metadata row | internal 或測試可見 |
MySqlSchemaMetadataMapper | row mapping | internal 優先 |
MySqlSchemaSnapshotAssembler | 組合 schema snapshot | internal 優先 |
若現有專案沒有啟用 InternalsVisibleTo，第一版可以先將測試需要的 helper 設成 public，但需避免進入正式對外契約；若需新增 InternalsVisibleTo，要先確認是否符合專案規則。
5. 建議方法
5.1 Query Builder
BuildTableQuery(SchemaInspectRequest request)
BuildColumnQuery(SchemaInspectRequest request)
BuildIndexQuery(SchemaInspectRequest request)預期：
- 回傳 SQL text 與參數名稱。
- 必含
TABLE_SCHEMA = @DatabaseName。 - table filter 必須使用參數，例如
@TableName0、@TableName1。 - 不產生 DDL。
5.2 Row Mapper
MapTable(MySqlTableMetadataRow row)
MapColumn(MySqlColumnMetadataRow row)
MapIndex(MySqlIndexMetadataRow row)預期：
- 缺少必要欄位時回傳標準錯誤。
- null comment 轉空字串。
IS_NULLABLE = YES轉 nullable。NON_UNIQUE = 0轉 unique。INDEX_NAME = PRIMARY標記為 primary key。
5.3 Snapshot Assembler
Assemble(
IEnumerable<MySqlTableMetadataRow> tables,
IEnumerable<MySqlColumnMetadataRow> columns,
IEnumerable<MySqlIndexMetadataRow> indexes)預期：
- 依 table name 組合 schema snapshot。
- column 依
ORDINAL_POSITION排序。 - index 欄位依
SEQ_IN_INDEX排序。 - column / index 指到不存在 table 時產生 warning。
- 不直接呼叫 DB。
6. 建議測試檔
| 測試檔 | 測試重點 |
|---|---|
MySqlSchemaInspectorQueryBuilderTests | table / column / index query 條件、排序、參數化 |
MySqlSchemaMetadataMapperTests | nullable、unique、primary key、comment、缺欄位錯誤 |
MySqlSchemaSnapshotAssemblerTests | table / column / index 組合、複合 index、warning |
測試專案應優先放在既有 schema / infrastructure 相關測試區。若現有測試專案命名不明確，實作前需先檢查程式 repo 結構再決定。
7. 測試案例清單
| 測試 | 預期 |
|---|---|
Table query 包含 TABLE_SCHEMA = @DatabaseName | 只能讀指定 database |
| Column query 排序穩定 | ORDER BY TABLE_NAME, ORDINAL_POSITION |
| Index query 排序穩定 | ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX |
| Table filter 參數化 | 不直接拼接 table name |
| 空 table filter | 不產生 IN () |
| Nullable mapping | YES / NO 正確轉換 |
| Unique mapping | NON_UNIQUE = 0 為 unique |
| Primary key mapping | PRIMARY 不放入一般 index |
| Composite index assembly | 欄位順序正確 |
| Null comment | 轉空字串 |
| 缺少 table name | 回傳標準錯誤 |
| column 指向不存在 table | 產生 warning |
| index 指向不存在 column | 產生 warning |
8. 影響範圍
預期影響：
- 只新增 schema inspector 周邊純程式 helper。
- 只新增不連 DB 的單元測試。
- 不影響 ConsoleHost。
- 不影響現有 Workflow / Adapter / TaskEngine。
- 不改既有 public method 簽章。
- 不新增外部套件。
9. 實作前檢查
真正進入程式 repo 實作前，需要先檢查：
- 現有 schema model 的 namespace 與資料夾位置。
ISchemaInspector/SchemaInspectResult現有簽章。- 既有測試專案位置與命名。
- 是否已有 internal helper 測試慣例。
- 是否已有 Result / ErrorInfo 標準工廠可沿用。
10. 停止線
實作中若遇到以下情況需停下確認：
| 情況 | 原因 |
|---|---|
| 需要新增 NuGet package | 超出本批不導入套件範圍 |
需要修改 .csproj | 可能影響 build |
| 需要修改 public method 簽章 | 可能影響既有契約 |
| 需要改 schema model 欄位 | 可能影響既有 SQL Generator / Dry Run |
| 需要新增 ConsoleHost CLI 參數 | 影響啟動方式 |
| 需要連真實 DB | 外部服務操作 |
| 需要執行 DDL | 修改資料庫 |
11. 建議下一步
可以進入「Query Builder / Row Mapper 第一版實作」，但第一步應先讀取程式 repo 結構與現有 schema inspector 程式碼，再提出實作範圍。
若實作前發現需要新增套件、修改 public contract 或改 .csproj，必須先停下確認。