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

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

refactor 重構指引

重構指引(Refactoring Guide) 企業標準技術白皮書|版本 v2.0|2026-10-08 適用範圍:以 Java(Java 25 LTS,相容 Java 21)/Spring Boot 4 為後端、以 Vue 3/TypeScript 為前端、以關聯式資料庫為儲存,並使用 GitHub 或 GitLab 管理原始碼的企業應用系統。本指引規範「在不改變外部行為的前提下改善程式結構」的方法、時機、流程、工具與驗證方式:每一條規則都說明要做到什麼、附有正確與錯誤的範例,並說明審查者要用什麼工具或方法確認。 v2.0 全面改寫 v1.0:以 Martin Fowler《Refactoring》第二版的重構目錄、Michael Feathers《Working Effectively with Legacy Code》、Kent Beck《Tidy First?》與 Fowler 的演進式設計模式(Strangler Fig、Branch by Abstraction、Parallel Change)為方法基礎;以 ISO/IEC 25010:2023、ISO/IEC/IEEE 14764:2022、ISO/IEC 5055:2021、ISO/IEC/IEEE 12207:2017 與 DORA 2025 報告為治理基礎重新組織內容。新增 Java 現代化、前端 TypeScript/Vue、架構層、資料庫與 API 演進、OpenRewrite 大規模自動化與「AI 輔助重構與審查 AI 產出」等章。每條規則都附有範例與「驗證方式」,每節結尾都有「🔍 審查與驗證」,讓審查者能判斷 AI 或同事產出的重構是否真的「沒有改變行為」。範例均經工具實測(見 附錄 F)。 目錄 0. 文件資訊 0.1 文件目的與讀者 0.2 技術基準版本 0.3 規範等級與規則格式 0.4 與其他指引的關係 0.5 如何閱讀本指引 0.6 例外與豁免流程 1. 重構的定義、目的與國際標準 1.1 什麼是重構 1.2 為什麼要重構:目的與經濟效益 1.3 國際標準與研究對照 1.4 重構的範圍與限制 2. 重構原則 2.1 小步前進,每一步都保持綠燈 2.2 優先使用工具化的重構 2.3 以簡單設計為方向 3. 重構時機與決策 3.1 重構的五種時機 3.2 決定「要不要重構」:紅黃綠燈 3.3 重構、重寫或汰換 4. 程式碼異味:找出需要重構的地方 4.1 異味目錄與偵測工具對照 4.2 門檻與「新程式碼」品質閘門 5. 安全網:重構前的測試 5.1 測試是重構的前提 5.2 特性測試:記錄現在的行為 5.3 黃金主檔與核准測試 5.4 覆蓋率與變異測試:測試夠強嗎 5.5 接縫:讓無法測試的程式碼可以被測試 6. 基本重構手法 6.1 提煉函式與內聯函式(Extract Function/Inline Function) 6.2 改名與提煉變數(Rename/Extract Variable) 6.3 改變函式宣告(Change Function Declaration) 6.4 封裝變數與集合(Encapsulate Variable/Encapsulate Collection) 6.5 拆分階段與合併函式(Split Phase/Combine Functions into Class) 6.6 移除死程式碼(Remove Dead Code) 7. 搬移特性與組織資料 7.1 搬移函式與搬移欄位(Move Function/Move Field) 7.2 提煉類別與內聯類別(Extract Class/Inline Class) 7.3 以物件取代基本型別:值物件(Replace Primitive with Object) 7.4 隱藏委託與移除中間人(Hide Delegate/Remove Middle Man) 8. 簡化條件邏輯 8.1 提早返回與分解條件(Guard Clauses/Decompose Conditional) 8.2 以多型取代條件式(Replace Conditional with Polymorphism) 8.3 引入特例(Introduce Special Case) 8.4 引入斷言與以預先檢查取代例外(Introduce Assertion/Replace Exception with Precheck) 9. API 與繼承重構 9.1 參數物件、保留完整物件與移除旗標參數 9.2 分離查詢與修改、移除設值方法、以工廠函式取代建構子 9.3 處理繼承:上移、下移、提煉父類別與摺疊階層 9.4 以委託取代繼承(Replace Subclass/Superclass with Delegate) 10. Java 現代化重構 10.1 以 record 取代資料類別 10.2 模式比對與 switch 運算式 10.3 Optional 與 null 10.4 以管線取代迴圈(Replace Loop with Pipeline) 10.5 建構子驗證與 Java 25 語言特性 10.6 虛擬執行緒與併發程式的現代化 11. 前端 TypeScript/Vue 重構 11.1 型別強化:讓編譯器幫你重構 11.2 元件重構:Options API 到 Composition API 與 composable 11.3 大規模前端重構:codemod 與未使用程式碼 12. 遺留系統重構 12.1 遺留程式碼的變更步驟 12.2 Sprout 與 Wrap:在無法測試的程式碼旁邊加新功能 12.3 Mikado 方法:處理相依關係不明的大型重構 12.4 Branch by Abstraction:在主幹上替換元件 12.5 Strangler Fig:漸進汰換整個系統 13. 架構層重構 13.1 以架構測試守護重構 13.2 模組化單體:Spring Modulith 13.3 從模組化單體拆分服務 14. 資料庫與 API 的演進式重構 14.1 Parallel Change:擴充—遷移—收縮 14.2 資料庫重構 14.3 REST API 的演進 14.4 事件與訊息格式的演進 15. 大規模自動化重構 15.1 選擇自動化工具 15.2 框架升級與語法現代化 16. 效能與重構 16.1 重構與效能的關係 16.2 資料存取與快取:最容易「重構出」效能問題的地方 17. 安全與重構 17.1 安全控制不得在重構中消失 17.2 查詢、日誌與序列化:重構時常見的安全退化 18. 流程、版本控管與審查 18.1 重構型 PR 的組成 18.2 分支策略與長期重構 18.3 守護測試:重構 PR 不得改變測試的預期值 18.4 如何審查重構型 PR 19. AI 輔助重構與審查 AI 產出 19.1 AI 在重構中的角色與風險 19.2 提示範本:讓 AI 產出可審查的重構 19.3 等價性驗證:證明 AI 的重構沒有改變行為 19.4 AI 代理的重構:指示檔與防護欄 19.5 AI 重構常見錯誤總表 20. 技術債管理與度量 20.1 技術債的分類與登錄 20.2 度量重構的成效 20.3 重構的投資與時間配置 21. 反模式與常見陷阱 21.1 流程與範圍的反模式 21.2 設計與實作的反模式 21.3 v1.0 範例中的反模式更正 22. 案例研究 22.1 遺留計費模組的漸進式重構(Java) 22.2 前端元件現代化(Vue/TypeScript) 23. 導入與培訓 23.1 分階段導入 23.2 培訓:以重構套路(kata)練習 附錄 A 規則總表 A.1 依領域統計 A.2 驗證方式與範例覆蓋 A.3 規則清單 附錄 B 檢核清單與範本 B.1 重構前檢核 B.2 重構中檢核 B.3 合併前檢核(作者) B.4 審查者檢核 B.5 AI 產出重構的審查檢核 B.6 重構提案範本 B.7 重構後追蹤 附錄 C 設定檔與腳本 C.1 Maven 驗證專案設定 C.2 OpenRewrite 設定 C.3 PMD 規則集 C.4 Checkstyle 設定 C.5 架構規則(ArchUnit、Spring Modulith) C.6 CI 工作流程 C.7 commitlint 設定 C.8 熱點分析腳本 C.9 測試守護腳本 C.10 前端設定 C.11 等價性檢查腳本 附錄 D 名詞對照 附錄 E 參考資料 E.1 書籍 E.2 國際標準與規範 E.3 研究報告 E.4 線上資源 附錄 F 修訂紀錄與查證紀錄 F.1 v1.0 章節對照 F.2 v1.0 內容更正紀錄 F.3 查證紀錄 F.4 待確認事項 F.5 技術版本紀錄 0. 文件資訊 0.1 文件目的與讀者 重構(refactoring)是「在不改變軟體可觀察行為的前提下,改善其內部結構」的一系列小步驟。它聽起來簡單,實務上卻最容易出錯:一次改太多、測試不足、把功能變更混在重構裡、或是把「重寫」誤稱為「重構」,都會讓原本可控的整理工作變成難以審查、難以回復的風險。生成式 AI 讓產生「看起來更乾淨」的程式碼變得非常容易,但 AI 產出的重構常常悄悄改變了邊界條件、例外型別或執行順序;判斷一次重構有沒有改變行為,仍然是人的責任。 ...

October 31, 2025 · 104 min · 22027 words · Eric Cheng