Object-Relational Mapping (ORM) 物件關聯對映教學
Object-Relational Mapping (ORM) 物件關聯對映教學手冊 作者:應用架構與資料存取團隊 更新日期:2026 年 10 月 13 日 版本:v2.0 適用對象:後端工程師、技術主管、架構師、程式碼審查者、測試工程師 技術基準:Jakarta Persistence 3.2、Hibernate ORM 7.4.5、Spring Boot 4.1.1(Spring Data JPA 2026.0.1)、Java 25;SQLAlchemy 2.1.4、Alembic 1.20.0、Python 3.14;PostgreSQL 18.6、Oracle AI Database 26ai(23.26.3)、SQL Server 2025、Db2 12.1.5 目錄 0. 文件資訊與閱讀指引 0.1 文件目的與範圍 0.2 適用讀者與學習路徑 0.3 技術基準與版本 0.4 規則格式與等級 0.5 本手冊範例如何被驗證 0.6 與其他手冊的關係 1. ORM 核心概念 1.1 什麼是 ORM 1.2 物件與關聯的阻抗不匹配 1.3 企業應用架構模式(PoEAA) 1.4 ORM 適用與不適用的情境 1.5 ORM 與 SQL 的關係 1.6 小結 2. 標準與規格 2.1 Jakarta Persistence 3.2 2.2 Jakarta Persistence 4.0 動向 2.3 Hibernate ORM 7 2.4 Python:PEP 249 與 SQLAlchemy 2.5 SQL 標準與交易隔離 2.6 標準 API 使用規則 ORM-STD-001 服務層只依賴 Jakarta Persistence 標準 API,Hibernate 專屬功能集中在持久層 3. ORM 框架與選型 3.1 Java 生態系 3.2 Python 生態系 3.3 其他語言概覽(未於本手冊執行) 3.4 框架比較 3.5 選型考量因素 3.6 選型規則 ORM-SEL-001 ORM 與 SQL-first 並用:交易性存取用 ORM,報表與彙總用 SQL-first 4. 環境建置與設定 4.1 Java:Spring Boot 4.1 + Hibernate 7.4 4.2 建議的 application.yml 4.3 Python:SQLAlchemy 2.1 4.4 環境規則 ORM-ENV-001 不手動指定 Hibernate 方言,移除過時的方言類別 ORM-ENV-002 正式環境的 schema 只驗證、不修改(ddl-auto: validate 或 none) ORM-ENV-003 關閉 Open Session in View(spring.jpa.open-in-view: false) ORM-ENV-004 明確設定連線池大小與逾時,且使用正確的單位 ORM-ENV-005 SQL 日誌以標準 logger 控制,綁定值只在開發環境輸出 ORM-ENV-006 每個行程只建立一個 EntityManagerFactory / Engine 4.5 小結 5. 實體與基本對映 5.1 Entity 的基本結構 5.2 主鍵 ORM-MAP-001 主鍵優先使用 SEQUENCE(pooled),保留 JDBC 批次寫入能力 ORM-MAP-002 對外公開或分散產生的識別碼使用 UUIDv7,不使用隨機 UUIDv4 作為主鍵 5.3 識別與相等 ORM-MAP-003 equals/hashCode 不可依賴會改變的產生式主鍵 5.4 基本型別 ORM-MAP-004 列舉以名稱或穩定代碼儲存,不可使用序數(ORDINAL) ORM-MAP-005 時間點使用 Instant / OffsetDateTime(或 UTC 正規化),不使用 LocalDateTime 與 java.util.Date ORM-MAP-006 字串欄位明確長度;可能含非 ASCII 字元的欄位明確指定 Unicode 型別 ORM-MAP-007 金額與精確數值使用 BigDecimal / Decimal,並明確 precision 與 scale 5.5 值物件、JSON 與命名 ORM-MAP-008 值物件以 Embeddable(record)建模,並在建構時檢查不變條件 ORM-MAP-009 JSON 欄位只存半結構化、不作查詢條件的屬性,並確保變更可被追蹤 ORM-MAP-010 表名與欄位名避開 SQL 保留字 ORM-MAP-011 明確指定命名策略或欄位名稱,確保各執行環境產生相同的 schema ORM-MAP-012 Python 使用 SQLAlchemy 2.x 型別化宣告(DeclarativeBase、Mapped、mapped_column) 5.6 小結 6. Persistence Context 與 Session 生命週期 6.1 實體的狀態 6.2 Flush 的時機 6.3 Persistence Context 規則 ORM-CTX-001 了解自動髒檢查:交易內修改 managed 物件就會寫回,唯讀情境使用 DTO 或唯讀查詢 ORM-CTX-002 新物件用 persist,分離物件用 merge 並使用其回傳值 ORM-CTX-003 一個 EntityManager / Session 對應一個工作單元,不跨請求、不跨執行緒共用 ORM-CTX-004 大量處理時定期 flush + clear,避免 Persistence Context 無限成長 ORM-CTX-005 Python:commit 後屬性會過期,回傳給外部前先轉成 DTO 6.4 小結 7. 關聯對映 7.1 關聯類型與擁有端 7.2 雙向關聯與擁有端 ORM-REL-001 雙向關聯必須同時維護兩端,並以擁有端寫入外鍵 ORM-REL-002 @ManyToOne 與 @OneToOne 一律明確宣告 FetchType.LAZY 7.3 Cascade 與孤兒刪除 ORM-REL-003 Cascade 只用在聚合內的組合關係,不對共用的參照物件 cascade ORM-REL-004 組合關係啟用 orphanRemoval / delete-orphan 7.4 多對多 ORM-REL-005 @ManyToMany 使用 Set,不使用 List ORM-REL-006 關聯本身有屬性時,升格為中介實體 7.5 一對一 ORM-REL-007 一對一優先使用單向 + 共用主鍵(@MapsId),避免雙向一對一的反向端 7.6 小結 8. 繼承對映 8.1 三種策略比較 8.2 繼承規則 ORM-INH-001 依查詢型態選擇繼承策略,預設 SINGLE_TABLE 或 JOINED,避免 TABLE_PER_CLASS ORM-INH-002 只為共用欄位而繼承時,使用 @MappedSuperclass ORM-INH-003 SINGLE_TABLE 的子類別欄位不可宣告 NOT NULL,依類型必填的規則改用 CHECK 約束 8.3 小結 9. 查詢 9.1 查詢方式總覽 9.2 查詢規則 ORM-QRY-001 唯讀與列表查詢使用投影(DTO / 介面 / Row),不載入整個實體 ORM-QRY-002 分頁查詢必須有決定性的排序(最後加上唯一鍵) ORM-QRY-003 集合 fetch join 搭配分頁時,必須確認分頁發生在資料庫(依 Hibernate 版本處理) ORM-QRY-004 深分頁與無限捲動使用 keyset(seek)分頁 ORM-QRY-005 批次 UPDATE / DELETE 之後,Persistence Context 必須同步 ORM-QRY-006 篩選、排序、彙總在資料庫完成;動態條件以 Criteria / Specification 組合 9.3 小結 10. 載入策略與 N+1 問題 10.1 Lazy 與 Eager 10.2 N+1 問題 10.3 載入規則 ORM-FET-001 依使用情境以 fetch join、Entity Graph 或 selectinload 一次載入所需關聯 ORM-FET-002 以 batch fetch(Java)與 raiseload(Python)作為 N+1 的安全網 ORM-FET-003 不可同時 fetch join 兩個以上的 List(bag)集合 ORM-FET-004 不以 enable_lazy_load_no_trans 或 EAGER「解決」LazyInitializationException 10.4 小結 11. 交易與並行控制 11.1 交易邊界 11.2 交易規則 ORM-TX-001 交易邊界放在服務層,查詢方法使用 readOnly ORM-TX-002 不在同一個類別內自我呼叫 @Transactional 方法 ORM-TX-003 會被並行修改的實體使用樂觀鎖(@Version / version_id_col) ORM-TX-004 悲觀鎖必須設定逾時,並了解各資料庫的實際行為 ORM-TX-005 只重試可重試的錯誤,重試整個交易並設上限 ORM-TX-006 依資料庫實際的隔離等級語意設計並行邏輯 11.3 小結 12. Schema 演進與遷移 12.1 遷移流程 12.2 遷移規則 ORM-MIG-001 Schema 變更一律以版本化遷移腳本管理,DDL 草稿須人工審查後才納入 ORM-MIG-002 自動產生的遷移必須人工審查,特別是「改名」 ORM-MIG-003 不停機部署採 Expand / Contract:先擴充、後收斂,同一版不刪除或改名舊欄位 ORM-MIG-004 已套用的遷移腳本不可修改,修正一律以新版本進行 12.3 小結 13. 效能 13.1 效能問題的來源 13.2 效能規則 ORM-PERF-001 開啟 JDBC 批次寫入並排序 INSERT / UPDATE ORM-PERF-002 大量修改使用批次 UPDATE / DELETE,不逐筆載入 ORM-PERF-003 大量讀寫使用 StatelessSession / 串流,並設定 fetch size ORM-PERF-004 二級快取只用於讀多寫極少、且只由本應用程式修改的參考資料 13.3 小結 14. 安全 14.1 ORM 相關的安全風險 14.2 安全規則 ORM-SEC-001 JPQL / HQL / 原生 SQL / text() 一律參數綁定,不串接使用者輸入 ORM-SEC-002 排序欄位、表名等識別字以白名單對應,不可直接使用使用者輸入 ORM-SEC-003 請求資料先綁定到 DTO,不直接綁定成 Entity(防止大量指派) ORM-SEC-004 日誌與錯誤訊息不得洩漏資料值(綁定參數、約束錯誤詳細內容) ORM-SEC-005 多租戶資料隔離由 ORM / 資料庫層強制,而不是靠每個查詢記得加條件 ORM-SEC-006 應用程式的資料庫帳號只授予 DML 權限,DDL 由遷移帳號執行 14.3 小結 15. 測試策略 15.1 ORM 程式的測試層次 15.2 測試規則 ORM-TST-001 持久層測試使用與正式環境相同的資料庫引擎與主要版本,不以 H2 代替 ORM-TST-002 以查詢次數斷言防止 N+1 與效能回歸 ORM-TST-003 驗證資料庫約束的測試必須明確 flush ORM-TST-004 Python 持久層測試以外層交易 + SAVEPOINT 隔離,結束時 rollback 15.3 小結 16. 架構整合 16.1 ORM 在分層架構中的位置 16.2 架構規則 ORM-ARC-001 Entity 不直接作為 API 請求或回應,於交易內轉為 DTO ORM-ARC-002 聚合之間以 ID 參照,不以物件關聯跨越聚合邊界 ORM-ARC-003 軟刪除使用框架機制(Hibernate @SoftDelete),不要手寫刪除旗標 ORM-ARC-004 稽核欄位由框架自動填寫 ORM-ARC-005 複雜讀取以唯讀的讀模型對映(@Immutable、檢視表、投影),不使用可寫的 Entity 16.3 小結 17. 錯誤處理與排錯 17.1 例外的層次 17.2 錯誤處理規則 ORM-ERR-001 把資料存取例外轉譯為領域例外,不依賴驅動專屬類別與原始訊息 ORM-ERR-002 例外發生後丟棄該交易與 EntityManager / Session,不可吞掉例外繼續使用 17.3 常見錯誤速查 17.4 小結 18. AI 輔助 ORM 開發 18.1 AI 產生 ORM 程式碼的常見問題 18.2 AI 使用規則 ORM-AI-001 AI 產生的 ORM 程式碼必須通過與人工程式碼相同的自動化檢查,才可合併 ORM-AI-002 提供給 AI 的上下文只包含結構,不包含真實資料、連線字串與密碼 18.3 AI 審查提示詞範本 18.4 小結 19. 能力認證與自我評量 19.1 認證現況(2026-10 查證) 19.2 能力等級 19.3 自我評量題 19.4 實作練習 19.5 學習計畫(8 週參考) 20. 檢查清單 20.1 新專案啟動 20.2 實體設計審查 20.3 Pull Request 審查(程式碼) 20.4 上線前 20.5 維運 20.6 故障排除 21. 參考資料 21.1 規格與標準 21.2 官方文件 21.3 書籍 21.4 本手冊的姊妹文件 附錄 A 規則總表 附錄 B 四種資料庫差異對照(實測) B.1 型別對映 B.2 識別字與保留字 B.3 悲觀鎖與鎖定逾時 B.4 交易隔離 B.5 唯一約束與 NULL B.6 Schema 變更 B.7 Python 驅動與方言的已知限制(實測) 附錄 C v1.0 → v2.0 章節對照 附錄 D 勘誤與修正紀錄 D.1 v1.0 內容修正 D.2 撰寫 v2.0 時自行發現並修正的錯誤 附錄 E 驗證紀錄 E.1 驗證環境 E.2 程式範例驗證結果 E.3 文件驗證結果 E.4 驗證過程中的主要發現 E.5 重現方式 附錄 F 待確認事項 附錄 G 版本歷史 0. 文件資訊與閱讀指引 0.1 文件目的與範圍 本手冊是企業內部使用 ORM(Object-Relational Mapping,物件關聯對映)的技術白皮書與實作規範。目標有三個: ...