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,物件關聯對映)的技術白皮書與實作規範。目標有三個: ...

October 31, 2025 · 89 min · 18894 words · Eric Cheng

Onion Architecture 設計教學

Onion Architecture 設計教學手冊 版本:1.0 日期:2025年9月20日 適用對象:Java 開發新進同仁 目標:學習 Onion Architecture 設計與認證準備 📚 目錄 第 1 章:緒論 1.1 教學手冊的目的與對象 1.2 為什麼需要 Onion Architecture 1.3 與傳統分層架構、Hexagonal Architecture、Clean Architecture 的比較 1.4 如何透過本手冊準備 Onion Architecture 認證 第 2 章:Onion Architecture 基礎概念 2.1 Onion Architecture 的核心理念 2.2 各層級設計原則 2.3 依賴反轉原則 (Dependency Inversion Principle) 2.4 Onion Architecture 的優點與限制 第 3 章:分層解析 3.1 Domain Layer - 實體與商業規則 3.2 Application Layer - 用例與服務 3.3 Infrastructure Layer - 技術支援與外部資源 3.4 Presentation Layer - 使用者介面與 API 3.5 層與層之間的互動與依賴管理 第 4 章:實作指南 ...

October 31, 2025 · 77 min · 16380 words · Eric Cheng

Podman Desktop使用教學

Podman Desktop 使用教學手冊 項目 內容 文件版本 3.0 最後更新 2026 年 11 月 6 日 適用版本 Podman Desktop 1.30.x(主要基準,穩定版 1.30.5,2026-10-13);🔭 標示 1.31 開發版(main 分支 1.31.0-next)已出現在官方文件、尚未正式發布的內容 內建引擎 Podman 6.1.4(Windows x64/ARM64、Apple Silicon Mac)、Podman 5.8.9(Intel Mac) 擴充功能 Kubernetes Extension Pack 0.6.0、Podman AI Lab 1.9.3、Podman Quadlet 0.13.0 企業版 Red Hat build of Podman Desktop(2026-02 GA);商業支援版 Red Hat Desktop(2026-05-12 GA) 圖例 🆕 本版新增 ⚠️ 更正或注意事項 🔭 預覽(1.31 開發版文件已出現、尚未正式發布) ✅ 審查與驗證清單 適用對象 後端與前端工程師、系統架構師、平台工程、DevOps、桌面管理(IT)與資安人員 文件定位 企業標準技術白皮書/內部標準教材 使用情境 大型企業、金融業(銀行、證券、保險)的開發者桌面容器環境 文件維護 內部技術團隊 Created by Eric Cheng 🆕 v3.0 改版說明:v3.0 把基準從 1.29.3 更新到 1.30.5(內建 Podman 6.1.4/5.8.9),並逐章對照官方文件在 1.29.3 → 1.30.5 之間的變動,以及 1.31 開發版文件。重點如下: ...

October 31, 2025 · 72 min · 15293 words · Eric Cheng

Podman使用教學

Podman 使用教學手冊 項目 內容 文件版本 3.0 最後更新 2026 年 11 月 6 日 適用版本 Podman 6.1.4(主要基準);6.2.0-rc1 預覽(標示 🔭);兼述 Podman 5.8.9 維護線與 RHEL 9.8/10.2 隨附的 5.8.2 周邊元件 Buildah 1.45.2(隨 Podman 6.1.4;獨立版 1.46.0)、Skopeo 1.24.1、Netavark/Aardvark-dns 2.1.0、crun 1.30.1、Podman Desktop 1.30.5、podman-compose 1.6.0 適用對象 後端與前端工程師、系統架構師、SRE/平台工程、DevOps、資安與稽核人員 文件定位 企業標準技術白皮書/內部標準教材 使用情境 大型企業、金融業(銀行、證券、保險)內部開發環境與 Linux 主機上的容器化服務 文件維護 內部技術團隊 Created by Eric Cheng 🆕 v3.0 改版說明(2026-11-06):本版以 2026-10-12 發布的 Podman 6.1.4/5.8.9 為基準逐章查證,並預覽 2026-10-26 發布的 6.2.0-rc1。重點如下: 安全修補基準:新增 6.1.1~6.1.4 的 CVE 對照與「最低可接受版本」檢查腳本(10.9)。 checkpoint 映像檔:6.1.3/5.8.8 起,podman run 不能再直接執行 checkpoint 映像檔(13.6)。 6.2 預覽:新功能有 kube play --validate/--multiple-pods/--label、Quadlet SetMountsDependency=/Umask=、auto-update --filter、push --platform。 RHEL 對照表:補上 RHEL 9.7/10.1 → 5.6.0、9.8/10.2 → 5.8.2。 Windows MSI:補上 MSI 靜默安裝的參數。 Podman Desktop:更新到 1.30.5。 審查與驗證清單:每章結尾新增「✅ 本章審查與驗證清單」,讓讀者能自行 review 與驗證。 完整更正請見 D.4,查證來源請見 E.2。 ...

October 31, 2025 · 74 min · 15590 words · Eric Cheng

PowerShell使用教學

PowerShell 使用教學手冊 目錄 第 1 部分:基礎入門 認識 PowerShell 1.1 PowerShell 的歷史與用途 1.2 與 CMD、Bash 的差異 1.3 PowerShell Core vs Windows PowerShell 安裝與環境設定 2.1 在 Windows 安裝 PowerShell 2.2 跨平台安裝 2.3 PowerShell ISE 與 VS Code 整合 2.4 基本環境變數設定 基本操作 3.1 常用指令(Get-Help、Get-Command、Get-Member) 3.2 管道 (Pipeline) 與物件導向特性 3.3 輸出與重新導向 第 2 部分:核心語法 變數與資料型態 4.1 宣告與使用變數 4.2 常見資料型別 4.3 型態轉換與檢查 運算子與流程控制 5.1 比較運算子與邏輯運算子 5.2 條件判斷(if, switch) 5.3 迴圈語法(for, foreach, while, do-while) 函數與模組 6.1 定義與呼叫函數 6.2 參數與回傳值 6.3 匯入與建立模組 第 3 部分:進階技巧 物件與管道操作 ...

October 31, 2025 · 134 min · 28499 words · Eric Cheng

PrimeNG使用教學

PrimeNG 使用教學手冊 文件資訊 版本: 1.0.0 更新日期: 2025年9月5日 目標對象: 從未學過 PrimeNG 的新進開發同仁 適用 PrimeNG 版本: 17.x+ 適用 Angular 版本: 17.x+ 目錄 第 1 部分:基礎入門 PrimeNG 簡介 1.1 什麼是 PrimeNG 1.2 為什麼選擇 PrimeNG 1.3 在企業專案中的角色 1.4 實務案例 1.5 注意事項與最佳實務 環境安裝與設定 2.1 前置需求 2.2 建立 Angular 專案 2.3 安裝 PrimeNG 與相關套件 2.4 基礎設定 2.5 主題選擇與設定 2.6 設定 PrimeFlex(CSS 工具庫) 2.7 開發工具設定 2.8 實務案例:企業專案設定 2.9 注意事項與疑難排解 2.10 環境設定檢查清單 PrimeNG 基本使用流程 3.1 理解 Angular 與 PrimeNG 的關係 3.2 模組匯入策略 3.3 建立第一個 PrimeNG 頁面 3.4 PrimeNG 服務的使用 3.5 響應式設計與 PrimeFlex 3.6 實務開發流程 3.7 注意事項與最佳實務 3.8 第一個專案檢查清單 第 2 部分:核心元件應用 按鈕與圖示 ...

October 31, 2025 · 173 min · 36639 words · Eric Cheng

PrimeVue使用教學

PrimeVue 使用教學手冊 📋 目錄 第一章:基礎入門 1.1 PrimeVue 簡介 1.2 PrimeVue 與 Vue.js 的關係 1.3 安裝與設定 1.4 建立第一個 PrimeVue 專案 1.5 Hello World 範例 第二章:核心元件介紹 2.1 按鈕(Button)與圖示(IconButton) 2.2 表單元件(InputText、Password、Dropdown、Checkbox、RadioButton、Calendar、Slider) 2.3 資料顯示元件(DataTable、Listbox、Card、Panel、TabView、Accordion) 2.4 對話框與通知(Dialog、Toast、ConfirmDialog) 2.5 版面配置元件(Panel、Card、Divider、Splitter) 第三章:專案應用實戰 3.1 建立完整的使用者管理系統 3.2 第三章總結與學習重點 第四章:進階功能與效能優化 4.1 效能優化策略 4.1.1 Vue 3 的效能優化特性 4.1.2 PrimeVue 元件效能優化 4.1.3 記憶體管理與清理 4.2 國際化 (i18n) 實作 4.2.1 Vue I18n 設定 4.2.2 在元件中使用國際化 4.2.3 PrimeVue 元件的本地化 4.3 主題系統與自訂樣式 4.3.1 PrimeVue 主題系統 4.3.2 自訂 CSS 變數系統 4.4 測試策略 4.4.1 單元測試設定 4.4.2 整合測試 4.4.3 E2E 測試 4.5 第四章總結 第五章:實務案例與最佳實務 ...

October 31, 2025 · 114 min · 24154 words · Eric Cheng

Python程式語言教學

Python 程式語言教學手冊 版本:2.0 最後更新:2026 年 9 月(內容查核基準日 2026-09-21) 適用於:Python 3.13 / 3.14(現行穩定版)~ 3.15(2026-10-01 發布) 適用對象:初學者至企業級開發人員、PCEP/PCAP 認證考生 目標:語言基礎 + 企業工程實務(工具鏈、非同步、安全供應鏈)+ 認證準備 目錄 Python 基礎入門 ...

October 31, 2025 · 84 min · 17776 words · Eric Cheng

Python程式語言教學

Python 程式語言教學手冊 版本:2.0 最後更新:2026 年 9 月(內容查核基準日 2026-09-21) 適用於:Python 3.13 / 3.14(現行穩定版)~ 3.15(2026-10-01 發布) 適用對象:初學者至企業級開發人員、PCEP/PCAP 認證考生 目標:語言基礎 + 企業工程實務(工具鏈、非同步、安全供應鏈)+ 認證準備 目錄 Python 基礎入門 ...

October 31, 2025 · 84 min · 17776 words · Eric Cheng

React前端framework教學

React 前端 Framework 教學手冊 📚 目錄 基礎概念 1.1 React 簡介與核心原理 1.2 JSX 語法 1.3 Component 元件 1.4 Props 屬性 1.5 State 狀態 1.6 Hooks 鉤子 專案實務 2.0 專案建立與環境設定 2.1 專案架構與元件拆分 2.2 狀態管理策略 2.3 API 呼叫方式 2.4 UI/UX 開發流程 進階主題 3.1 React Router 路由管理 3.2 Context API 3.3 狀態管理工具 3.4 效能最佳化 測試與品質 4.1 React 測試框架 4.2 程式碼規範 4.3 Lint 與 Formatter 實戰演練 5.1 表單處理 5.2 API 資料綁定 5.3 前後端整合 認證準備指南 6.1 React 認證概述 6.2 常見考點 6.3 練習題範例 6.4 學習資源 檢查清單 1. 基礎概念 1.1 React 簡介與核心原理 什麼是 React? React 是由 Facebook(現在的 Meta)開發的開源 JavaScript 函式庫,專門用來建立使用者介面(UI)。它採用元件化的開發方式,讓開發者能夠建立可重複使用的 UI 元件。 React 核心原理 graph TB A[Virtual DOM] --> B[實際 DOM] C[Component] --> D[JSX] D --> A E[State] --> C F[Props] --> C G[Hooks] --> E subgraph "React 生態系統" A C E F G end 1. Virtual DOM(虛擬 DOM) ...

October 31, 2025 · 69 min · 14674 words · Eric Cheng