Refactoring to Patterns 教學手冊

文件版本：1.1 資訊確認日期：2026-09-16 理論基礎：Joshua Kerievsky,《Refactoring to Patterns》（Addison-Wesley Professional，2004-08-05 出版，Addison-Wesley Signature Series (Fowler)，ISBN 978-0-321-21335-8）；Industrial Logic 官方 catalog 的 27 個 pattern-directed refactorings 程式碼版本基準：Before 範例刻意使用 Java 8 + Spring Boot 2.x + javax（貼近企業 Legacy 現況）；After 範例使用 Java 25（LTS）+ Spring Boot 4.1.x + Spring Framework 7.x + Jakarta EE 11 測試框架：JUnit 6 為主（官方當前世代，需 Java 17+／Kotlin 2.1+），並標註 JUnit 5（Jupiter）對照寫法；ArchUnit 1.5.0（archunit-junit6） 前端：Vue 3（Composition API）與 Angular v22（Standalone + Signals + Zoneless）等量並列，TypeScript 7.0 適用對象：PM、SA、Software Architect、Senior Developer、Developer、QA、DevOps、維運人員、AI Coding Agent 使用者、Legacy 系統維護團隊、Framework Upgrade 團隊 篇幅：46 章，分為 11 部，另含 27 個 refactoring 完整條目、21 個 Code Smell、5 個實作 Lab、10 個企業案例、20 組 AI Agent Prompt 與 9 份附錄 版本時效：所有技術版本宣稱的來源 URL 與查證日期，集中列於 附錄 I；該附錄同時提供每季複查的 SOP 文件狀態：catalog 條目清單以 Industrial Logic 官方頁面查證為準。本手冊自行整理的分組、流程與治理設計均明確標示為「本手冊的工程建議」，不冒充原作觀點；查不到的資訊一律標示「原始資料未說明」，不猜測、不補完。

關於本手冊

這份手冊要回答的問題

關於 Design Pattern 的教材，市面上幾乎都在回答同一個問題：「這個 Pattern 的標準寫法長什麼樣子？」

那個問題不難。本 repo 自己就有一份 Design Pattern教學.md（216KB）與 DESIGN_PATTERNS.md 底下 23 個可執行的 Java 範例，把 GoF 的標準結構寫得很完整。

本手冊要回答的是另一個、而且困難得多的問題：

一個同時維護十幾套 Legacy 系統、正在把 Spring Boot 2 升到 4、而且團隊已經大量使用 GitHub Copilot 與 Claude Code 寫程式的企業開發團隊，要怎麼讓「設計改善」這件事，既不退化成「不敢動的技術債」，也不暴衝成「AI 一口氣產出三十個 Interface 的過度設計」？

這個問題底下藏著三件事：

1. 教科書上的 Pattern 範例，永遠是「已經長好的樣子」。 沒有人教你「從一坨 800 行的 if/else 走到 Strategy」中間那十四個步驟長什麼樣、每一步要跑哪些測試、哪一步之後其實就該停下來了。
2. Legacy 系統最大的風險不是醜，而是沒有人知道它到底在做什麼。 一段沒人看得懂的 if (flag == 9 && amt > 0)，可能是十年前某次金管會函釋留下的規則。AI 看到它只會說「這段可以簡化」。
3. AI 產生程式碼的速度，遠超過人類判斷「該不該這樣設計」的速度。 當你對 Copilot 說「重構這段程式碼」，它極大機率會回給你一組 Strategy 介面加三個實作類別——不管你的專案是不是真的只有兩種情況、而且五年沒變過。

本手冊的核心主張是：

Pattern 是「演進之後可能抵達的設計目的地」，不是「一開始就該套上去的設計起點」。 而在 AI Agent 時代，這句話從「資深工程師的品味」變成了「必須寫成規則、寫進 CI、AI 繞不過去的工程紀律」。

一句話說清楚三者的差別

最關鍵的是最後一列。AI 最擅長的正是「直接產生最終結構」，而這恰好是 Refactoring to Patterns 最反對的做法——因為中間步驟才是驗證「這個方向對不對」的地方。

與本 repo 既有教材的定位

本手冊不重複既有教材的內容，而是把它們串起來。閱讀前建議先確認你需要的是哪一份：

本手冊的來源分級標註

企業手冊最怕的事情之一，是把「作者的個人偏好」寫得像「業界公認的鐵律」。本手冊全篇使用四種標記區分主張的來源強度：

📖 Kerievsky 原作觀點 出自《Refactoring to Patterns》一書或 Industrial Logic 公開資料的主張。

🏭 業界常見實務 多個來源都採用、但沒有單一權威出處的做法。

🔧 本手冊的工程建議 本手冊依企業軟體工程實務提出的設計，屬於建議而非定論，團隊可依情境調整。

🤖 AI Agent 使用建議 專門針對 Coding Agent 工作流的指引，人工作業時可視情況放寬。

當不同來源存在分歧時，本手冊並陳差異、不強行統一，並說明各自適用的情境。

怎麼讀這份手冊

目錄

本目錄包含章與小節兩層，每一項均可直接跳轉至內文。依部別摺疊，點擊展開即可瀏覽該部的完整結構。

第一部：觀念基礎

這一部要建立的是「判斷力」，不是「技巧」。

技巧可以查表（第三部就是那張表），但判斷力決定你會不會查錯表。實務上絕大多數的設計災難，不是因為工程師不會寫 Strategy，而是因為他在一個只有兩種情況、而且五年沒變過的地方寫了 Strategy。

第 1 章 Refactoring to Patterns 是什麼

1.1 一句話定義

Refactoring to Patterns 是「用一連串小而安全的重構步驟，讓設計逐步演進到某個 Design Pattern」的工程方法。 它同時也包含相反方向：當某個 Pattern 不再帶來價值時，用同樣的方法把它拆掉。

這句定義裡有四個關鍵字，每一個都值得單獨強調：

📖 Kerievsky 原作觀點 Martin Fowler 在介紹本書時的說法可以當作一句話註解：patterns need not be designed in up front, but evolved to as a system grows（模式不必事先設計，而是隨著系統成長演進而來）。 來源：https://martinfowler.com/books/r2p.html

原書的可查證事實

企業教材引用二手說法時最容易失真。以下是可直接在出版商頁面查證的原書事實，供正式文件（ADR、內訓教材、採購書單）引用：

⚠️ 兩個數字要特別注意

1. 原書的 design smells 是 12 個；本手冊第二部列出 21 個，是「原書 12 個 ＋ Fowler《Refactoring》9 個」的合併清單，詳見 7.1 節的來源對照表。引用時務必說明是哪一份清單。
2. 原書出版於 2004 年，當時 Java 尚無 enum 之外的 sealed、record、pattern matching。本手冊在多處標示「原書做法」與「2026 年 Java 25 做法」的差異，這些差異是時代造成的，不是原書錯誤。

查證日期：2026-09-16。完整來源 URL 見 附錄 F。

1.2 三個最常見的誤解

誤解一：「看到問題就套 Pattern」

這是最普遍、也最危險的誤解。它把 Refactoring to Patterns 讀成了「Pattern 速查手冊」：看到 if/else 就查到 Strategy，看到 new 就查到 Factory。

實際上這套方法的重點在前半段——你怎麼知道這裡真的有問題？

❌ 錯誤讀法
看到 if/else  →  查表  →  套用 Strategy

✅ 正確讀法
這次需求變更改了三個檔案  →  為什麼？
  →  因為新增付款方式要同時改三處 if/else
    →  這是 Shotgun Surgery + Conditional Complexity
      →  未來還會再新增付款方式嗎？（問 PM，不要猜）
        →  會，明年至少三種
          →  那麼把變化點集中是划算的
            →  Extract Method → Extract Class → Introduce Interface
              →  結果長得像 Strategy

注意最後一句話的語氣：不是「我決定要用 Strategy」，而是「走完之後，它長得像 Strategy」。這個差別看起來只是措辭，但它決定了你會不會在第三步就停下來——如果走到 Extract Class 之後痛點已經消失，那就該停了。

誤解二：「這本書是在反對 Design Patterns」

不是。

Kerievsky 的主張不是「Pattern 不好」，而是「脫離實際問題、過早、無目的地使用 Pattern 不好」。這是兩件完全不同的事。

🔧 本手冊的工程建議 反過來說，完全不懂 Pattern 的人，也做不好 Refactoring to Patterns。因為你必須認得出「這串小步驟正在往哪個方向走」，才知道什麼時候該繼續、什麼時候該停。 所以本手冊不取代 Design Pattern教學.md，而是接在它後面讀。

誤解三：「這是資深工程師的品味問題，寫不成規則」

在 AI Agent 出現之前，這個說法有一半是對的。

但當 Copilot 一次產出 800 行程式碼、Claude Code 一次改 20 個檔案時，「靠資深工程師的品味把關」在物理上已經來不及了。品味必須被外顯成規則、寫進 CLAUDE.md、變成 CI 檢查。

這正是本手冊第五部與附錄 B 存在的理由。

1.3 核心演進鏈路

整套方法可以畫成一條鏈路。請特別注意：Pattern 出現在最後面，而且前面有兩個迴圈。

flowchart TD
    A[Business Requirement<br/>業務需求] --> B[Working Code<br/>能動的程式碼]
    B --> C[Observe Actual Change<br/>觀察實際的變更痛點]
    C --> D{有痛點嗎?}
    D -->|沒有| B
    D -->|有| E[Identify Code Smell<br/>指認 Code Smell]
    E --> F[Understand Root Cause<br/>理解根本原因]
    F --> G[Apply Small Safe Refactoring<br/>施作一個小而安全的重構]
    G --> H[Run Tests<br/>執行測試]
    H --> I{測試通過?}
    I -->|否| J[Rollback]
    J --> G
    I -->|是| K{痛點消失了嗎?}
    K -->|是| L[停下來<br/>不需要 Pattern]
    K -->|否| G
    G -.累積多步之後.-> M[Pattern Naturally Emerges<br/>Pattern 自然浮現]
    M --> N[Improved Design<br/>改善後的設計]
    N --> C

    style L fill:#d4edda,stroke:#28a745
    style M fill:#fff3cd,stroke:#ffc107
    style J fill:#f8d7da,stroke:#dc3545

這張圖有三個地方是刻意設計的：

1. 停下來 / 不需要 Pattern 是綠色的正常終點，不是失敗。大部分重構應該在這裡結束。
2. Pattern 自然浮現 是虛線進入的，代表它是累積的結果，不是某一步的目標。
3. 最後回到 觀察痛點，代表這是持續的循環，不是一次性專案。

1.4 這套方法要對抗的兩個極端

企業裡的設計問題，幾乎都落在天平的兩端。Refactoring to Patterns 要做的是把團隊拉回中間。

🤖 AI Agent 使用建議 最後一列是本手冊最重要的觀察之一。LLM 在訓練資料裡看到的「好程式碼」大量來自開源框架與教科書範例，而那些程式碼本來就該高度抽象（因為框架的使用者是未知的）。 但你的內部系統不是框架。當 AI 把框架的設計密度套到一個只有三個使用者的行內批次程式上時，它產生的不是「好設計」，是技術債。

1.5 本章實務案例

情境：某銀行的匯款手續費計算模組，五年來被改過 27 次。

團隊某次 Sprint 決定「重構它」，一位工程師花了三天，把它改成了一組 FeeCalculationStrategy 介面 + 9 個實作類別 + 1 個 FeeStrategyFactory + 1 個 FeeStrategyRegistry。Code Review 時大家覺得「看起來很專業」，就合併了。

半年後的問題：

問題出在哪裡：團隊看到了 Smell（Conditional Complexity），但沒有分析變化的性質。

真正的變化是「費率數字會變」，不是「計算演算法會變」。正確的重構應該是：

Extract Method（把公式抽出來）
  ↓
Replace Magic Number with Named Constant（費率具名）
  ↓
把費率移到設定檔或資料表
  ↓
停。（不需要 Strategy）

三天的工作量可以縮短成半天，而且結果更好維護。

事後補救：這個模組後來在第 18 章描述的「Refactoring Away From Patterns」流程下，被拆回成 1 個類別 + 1 張費率表。

1.6 本章注意事項

⚠️ 不要把「重構」當成 Sprint 裡的獨立任務 「這個 Sprint 我們來重構 XX 模組」這種規劃方式，天然會導向過度設計——因為工程師被指派了「要做出東西」的任務，而最容易做出來的東西就是抽象層。 重構應該附著在真實的需求變更上：「我要加第四種付款方式，而現在加起來很痛，所以我先把它變好改。」

⚠️ 「以後可能會變」不是重構的理由 它是 Speculative Generality（第 8.11 節）的定義。如果你需要一個理由，去問 PM「明年的 roadmap 有沒有這一項」，得到的答案才算證據。

✅ 停下來是正常的，而且應該被記錄 在 PR 描述裡寫「本次只做到 Extract Class，因為痛點已消除，暫不導入 Strategy」是非常好的工程行為。它讓下一個人知道你考慮過了，而不是不懂。

📌 與後續章節的關係 本章講的是心法。從第 6 章開始講「怎麼判斷有沒有問題」，第三部講「有問題之後的具體手法」，第四部講「什麼時候該收手或倒退」。

第 2 章 Refactoring 的基礎

這一章是全書的地基。如果團隊對「什麼算重構」沒有共識，後面所有的流程、Guardrail 與 Quality Gate 都會失效——因為大家會把「順手改了個 bug」「順手調了個效能」都叫做重構，然後在出事時無法判斷是哪一步造成的。

2.1 定義與目的

重構（Refactoring）：在不改變軟體外部可觀察行為的前提下，調整其內部結構，使其更容易被理解與修改。

這個定義來自 Martin Fowler，是業界的共同基準。它有兩個部分，缺一不可：

flowchart LR
    A[重構] --> B[外部行為不變<br/>這是約束]
    A --> C[內部結構改善<br/>這是目的]
    B -.- D["若行為改變了<br/>那不是重構<br/>是「改功能」或「修 bug」"]
    C -.- E["若結構沒變好<br/>那不是重構<br/>是「白做工」"]

    style B fill:#cfe2ff,stroke:#0d6efd
    style C fill:#d4edda,stroke:#28a745

重構要達成的目的，按照企業實務的優先順序排列：

⚠️ 注意：「讓程式碼變漂亮」不在這張表上。 美觀不是重構的目的，它是上述五項達成後的副產品。以「變漂亮」為理由的重構，通常無法通過成本效益檢驗，也最容易被 AI 濫用當成藉口。

2.2 外部行為不變到底指什麼

這是實務上爭議最多的地方，也是 AI 最容易踩雷的地方。「外部行為」的範圍，遠比大多數人想的還要大。

📖 Kerievsky 原作觀點 vs 🏭 業界實務的分歧 學術定義通常說「外部行為不變」只包含功能性行為，不包含效能。 但企業實務（尤其是金融業的批次作業）普遍把效能特性納入不可變更的範圍——一個原本跑 40 分鐘的日結批次，重構後跑 6 小時，即使結果完全正確，在營運上也是重大事故。 本手冊採用後者的嚴格定義，並在第 38 章把 Performance Test 納入重構的驗證項目。

一個真實會出事的例子

// Before：Java 8 + Spring Boot 2.x
public List<Account> findActiveAccounts(String custId) {
    List<Account> result = dao.queryByCustomer(custId);
    if (result == null || result.isEmpty()) {
        return null;            // ← 十年前寫的，呼叫端依賴這個 null
    }
    return result;
}

AI 看到這段，非常可能「順手改善」成：

// AI 的「改善」——這不是重構，這是行為變更
public List<Account> findActiveAccounts(String custId) {
    return Optional.ofNullable(dao.queryByCustomer(custId))
                   .orElseGet(List::of);     // ← 再也不會回傳 null
}

程式碼確實更現代、更安全、更符合最佳實務。但它改變了外部行為。如果呼叫端有這樣的程式碼：

if (findActiveAccounts(id) == null) {
    throw new NoActiveAccountException();    // ← 這行從此永遠不會執行
}

那麼原本應該擋掉的案件會全部放行。這種 bug 不會被單元測試抓到（因為測試多半只測有資料的情況），而且會在生產環境安靜地錯很久。

🤖 AI Agent 使用建議 這是附錄 B 治理規則第 5 條（Preserve external behavior unless explicitly authorized）存在的原因。 正確的做法是：AI 可以提出這個改善建議，但必須把它標示為「行為變更，非重構」，列出所有呼叫端，並要求人類確認。

2.3 重構與重寫、改功能、效能調校的界線

企業裡必須把這四件事分開，因為它們的風險等級、測試策略與核准流程完全不同。

🔧 本手冊的工程建議：一個 commit 只做一件事 這不是潔癖，是風險控制。 當一個 commit 同時包含「Extract Method」與「順手修正的判斷條件」時，一旦生產環境出事，你無法用 git revert 安全地退回——因為退回會同時退掉那個修正。 第 41.4 節提供了可直接採用的 commit 訊息規範。

重寫為什麼是最後手段

flowchart TD
    A[Legacy 程式碼很難維護] --> B{有測試嗎?}
    B -->|沒有| C[先建立 Characterization Test<br/>第 27 章]
    C --> D[逐步重構]
    B -->|有| D
    D --> E{重構後仍無法滿足需求?}
    E -->|否| F[結束]
    E -->|是| G{是架構層級的問題嗎?}
    G -->|否| D
    G -->|是| H[Strangler Fig 漸進替換<br/>第 29 章]
    H --> I{真的完全無法漸進?}
    I -->|否| H
    I -->|是| J[重寫<br/>需經架構決策與風險承擔]

    style J fill:#f8d7da,stroke:#dc3545
    style F fill:#d4edda,stroke:#28a745

重寫的致命問題不是「工作量大」，而是你會把「不知道為什麼存在的行為」全部弄丟。第 26 章會詳細說明，Legacy 程式碼裡最醜的那些 if，往往正是最重要的業務規則。

2.4 為什麼安全性來自小步驟

這是整套方法的物理基礎，值得用數學說明。

假設你做了一次大重構，改動了 50 個地方，跑測試發現失敗了。此時你要在 50 個改動裡找出是哪一個造成的——搜尋空間是 50。

如果你分成 50 次小重構，每次改一個地方就跑測試，那麼測試失敗時，搜尋空間永遠是 1。

大步驟：改動 50 處 → 測試失敗 → 除錯範圍 50 處 → 常見結局是「全部 revert，明天再說」
小步驟：改動  1 處 → 測試失敗 → 除錯範圍  1 處 → 30 秒內修好或 revert，繼續前進

「小步驟」的具體標準：

🏭 業界常見實務 IDE 的自動重構功能（IntelliJ 的 Extract Method、Rename、Move、Change Signature）之所以重要，正是因為它們是機械化的、不會手滑的小步驟。 實務上的原則是：能用 IDE 自動重構完成的，絕不手工改。這也適用於 AI——請 AI 產生一段「等價的新程式碼」，遠比請 IDE 執行一次 Extract Method 危險。

2.5 重構的經濟理由

要說服管理層撥時間，需要的是成本語言，不是設計語言。

這就是重構的經濟模型：

重構成本 = 一次性投入（人天）
重構收益 = 每次變更節省的成本 × 預期變更次數 − 新增的理解成本

當「預期變更次數」= 0 時，收益永遠是負的。
→ 這就是為什麼「不會再改的程式碼，再醜也不該重構」。

🔧 本手冊的工程建議：重構的三個合法時機

1. 變更前重構（Preparatory Refactoring）——「我要加新功能，但現在加很痛，所以先讓它好加。」這是最划算的時機，因為你已經有明確的需求當證據。
2. 變更後重構——「功能做完了，但我留下了重複，趁記憶還熱的時候收斂。」
3. 理解式重構（Comprehension Refactoring）——「我看不懂這段，邊改名邊抽方法來幫助自己理解。」產出是理解，程式碼改善是附帶的。

不在這三個時機裡的重構，請先問「為什麼是現在」。

2.6 本章實務案例

情境：某壽險公司的保費試算 API，回應時間從 200ms 惡化到 3 秒。

團隊分析後發現，問題出在一個 1200 行的 PremiumCalculator.calculate() 方法裡，有一段迴圈重複查詢資料庫。

第一版做法（錯誤）：一位工程師決定「既然要動它，乾脆一起重構」，在同一個 PR 裡：

1. 把 1200 行拆成 23 個方法
2. 抽出 4 個類別
3. 修正了那個 N+1 查詢
4. 順手把日期處理從 Date 換成 LocalDate
5. 順手把幾個 if 簡化了

結果：PR 有 1800 行 diff，Review 了兩週。上線後第三天，發現某種保單的保費少算了 3 元——沒有人能確定是哪一項改動造成的，最後只能整個 revert，效能問題也跟著回去了。

第二版做法（正確）：拆成五個獨立的 PR，依序進行。

第 #4 個 PR 上線後效能就恢復了，總歷時反而比第一版短。而第 #5 個 PR 在 Review 時被擋下——因為 Reviewer 發現原本的 Date 在某個日切邊界上有特殊行為，需要另外處理。

這個案例的三個教訓：

1. 先有測試，再談重構。 PR #1 是整件事成立的前提。
2. 分類決定風險。 #2、#3 是重構（低風險），#4 是調校（中風險），#5 是行為變更（高風險）。混在一起，整包都變成高風險。
3. Characterization Test 要記錄「現況」，不是「正確」。 那 3 元的既有偏差被寫進了測試——因為在確認它是 bug 之前，它就是規格。

2.7 本章注意事項

⚠️ 沒有測試的重構不叫重構，叫「祈禱」 這是全書最硬的一條規則。如果既有程式碼沒有測試，第一步永遠是建立 Characterization Test（第 27 章），而不是開始改。

⚠️ 「順手」是最貴的兩個字 在重構的 commit 裡出現任何「順手改的」東西，都會讓這個 commit 失去「可安全 revert」的性質。看到不對的地方，開 issue，不要順手。

⚠️ AI 特別容易破壞「例外行為」與「null 語意」 因為這兩者在訓練資料裡幾乎都被當成「應該改掉的壞味道」。請在 Guardrail 中明確要求 AI 保留原有的 null 與例外語意（第 22 章）。

✅ 善用 IDE 的自動重構 IntelliJ IDEA 的 Ctrl+Alt+M（Extract Method）、Shift+F6（Rename）、F6（Move）是機械化且可信的。本 repo 的 工具/IntelliJ IDEA Community Edition使用教學.md 有完整操作說明。

📌 延伸閱讀 低階重構手法的完整目錄（Extract Method、Inline、Move Field…）請見 分析與設計/Refactoring重構教學.md。本手冊不重複那些內容，而是專注在「這些手法怎麼組合成 Pattern 的演進路徑」。

第 3 章 Design Pattern 的本質與代價

3.1 Pattern 是什麼

Design Pattern 是「某一類設計問題，在特定情境下，經過多次驗證的解決方案骨架」，加上「採用它要付出的代價」。

多數人只記得前半句，忘了後半句。而後半句才是決定「該不該用」的關鍵。

一個完整的 Pattern 描述至少包含四個部分：

🔧 本手冊的工程建議 當有人（或 AI）提議導入某個 Pattern 時，請他先講 Context 與 Problem，最後才講 Solution。 講不出 Context 與 Problem 的提議，一律退回。這一條規則能擋掉八成的過度設計。

3.2 Pattern 不是什麼

這一節要澄清企業裡最常見的概念混淆。

特別澄清：Pattern 與 Architecture 的關係

flowchart TD
    subgraph ARCH["Architecture 層級 — 第 39 章用 ArchUnit 守住"]
        A1[Layered / Clean / Hexagonal]
        A2[模組邊界與依賴方向]
        A3[部署單元與通訊方式]
    end
    subgraph PAT["Design Pattern 層級 — 本手冊第三部"]
        P1[Strategy / Factory / Adapter]
        P2[類別的職責分配]
        P3[物件之間的協作方式]
    end
    subgraph CODE["程式碼層級 — 第二部的 Code Smell"]
        C1[方法長度、重複、命名]
    end

    ARCH --> PAT --> CODE

    style ARCH fill:#cfe2ff,stroke:#0d6efd
    style PAT fill:#fff3cd,stroke:#ffc107
    style CODE fill:#d4edda,stroke:#28a745

三個層級的問題不能互相取代：

• 你不能用 Strategy 解決「Domain 層依賴了 JPA」的架構問題。
• 你也不能用 ArchUnit 規則解決「這個方法有 400 行」的程式碼問題。

📌 本 repo 的 ArchUnit 手冊 守的是最上層，本手冊守的是中間與下層。第 39 章說明兩者怎麼搭配。

3.3 每個 Pattern 都要付的四種代價

🔧 本手冊的工程建議 任何 Pattern 導入提案，都必須明確回答這四項代價。這是第 40 章 Quality Gate 的檢查項目之一。

代價的量化範例

以第 1.5 節那個手續費案例為例：

這張表清楚顯示：這次重構只有在「新增計算演算法」這個場景下才有價值，而那正是五年來沒發生過的場景。

🏭 業界常見實務 有經驗的團隊會在 PR 描述裡直接放這張表。它讓 Review 從「我覺得這樣比較好」變成「數字顯示哪些場景變好、哪些變差」。

3.4 Pattern 的適用前提

每個 Pattern 都有它的「入場門檻」。門檻沒到就導入，得到的是純粹的代價。

⚠️ 關於 Singleton 的特別提醒 在 Spring 環境下，@Component 預設就是 singleton scope。自己手寫 Singleton（私有建構子 + getInstance()）在 Spring 專案裡幾乎永遠是錯的，因為它繞過了 DI 容器，讓測試無法替換、讓生命週期不受管理。 第 11.6 節的 Inline Singleton 與 11.7 節的 Limit Instantiation with Singleton 會詳細處理這件事。

3.5 本章實務案例

情境：某電商團隊的訂單通知功能。

PM 提出需求：「訂單成立後要發 Email。」

工程師 A 的實作（30 分鐘完成）：

// Java 8 + Spring Boot 2.x
@Service
public class OrderService {
    @Autowired private EmailSender emailSender;

    public void placeOrder(Order order) {
        orderRepository.save(order);
        emailSender.send(order.getCustomerEmail(), "訂單成立", buildBody(order));
    }
}

工程師 B 的實作（2 天完成）：定義 NotificationEvent 介面、NotificationListener 介面、NotificationDispatcher、EmailNotificationListener、NotificationChannelFactory、NotificationTemplateStrategy，外加一組設定類別。

理由是：「以後一定會加簡訊跟 App 推播。」

六個月後的實際狀況：

結論：B 的預測（會加通道）是對的，但他的設計仍然是失敗的——因為他預測的是「通道會增加」，實際的變化卻是「不同通道的錯誤處理語意不同」，而他的 Pattern 恰恰讓這件事變難了。

🔧 這個案例要傳達的是 過度設計的問題不只是「浪費了 2 天」，而是你猜錯了變化的方向，並且把猜錯的方向固化進了結構裡。 正確的做法是 A 的實作 + 在第 4 個月真的要加簡訊時，才走一次第 15.2 節的 Replace Hard-Coded Notifications with Observer——那時你已經知道「兩個通道的錯誤處理不同」，會做出完全不同、而且正確的設計。

3.6 本章注意事項

⚠️ 「以後一定會加」不是前提，是預測 前提是可驗證的事實（已經有兩個變體、PM 的 roadmap 上有這一項）；預測是猜。用預測當作導入 Pattern 的理由，是 Speculative Generality。

⚠️ 不要在 Code Review 用「有沒有用 Pattern」當評分標準 正確的問題是「這段程式碼好不好改、好不好測、好不好懂」。Pattern 只是達成它的可能手段之一。

⚠️ 效能代價在三個地方會真的出事 ① 批次作業的內層迴圈 ② 高頻交易路徑 ③ 大量物件配置的場景。在這三處導入 Pattern 前，必須有實測數據，不能只憑「JIT 會處理掉」的直覺。

✅ 把「代價表」變成 PR 模板的一部分 第 3.3 節那張量化表，建議直接放進 .github/PULL_REQUEST_TEMPLATE.md 的「設計變更」區塊，強制提案者填寫。

📌 Pattern 的標準結構請查既有教材 本章刻意不畫任何 Pattern 的類別圖。需要時請查 分析與設計/Design Pattern教學.md 或 DESIGN_PATTERNS.md。本手冊關心的是「怎麼走到那裡」與「該不該走」。

第 4 章 Toward、To 與 Away From Patterns

這一章是 Refactoring to Patterns 與一般 Pattern 教材最大的差異所在。

一般教材只有一個方向：沒有 Pattern → 有 Pattern。 本方法有三個方向，而且第三個方向和前兩個一樣重要。

4.1 三個方向總覽

flowchart LR
    A[原始設計<br/>Ad-hoc Design] -->|Toward<br/>朝向| B[中間態設計<br/>Partial Structure]
    B -->|To<br/>抵達| C[明確的 Pattern]
    C -->|Away From<br/>離開| B
    B -->|Away From<br/>離開| A

    B -.可以停在這裡.-> D((✓ 合法終點))
    C -.也可以停在這裡.-> E((✓ 合法終點))

    style A fill:#f8d7da,stroke:#dc3545
    style B fill:#fff3cd,stroke:#ffc107
    style C fill:#cfe2ff,stroke:#0d6efd
    style D fill:#d4edda,stroke:#28a745
    style E fill:#d4edda,stroke:#28a745

📖 Kerievsky 原作觀點 原書明確討論了 to / towards / away from 三種方向。這是本方法與「Pattern 速查手冊」最根本的差異：Pattern 不是單向的終點，而是設計空間裡一個可以來回移動的位置。

4.2 Refactoring Toward a Pattern

「朝向」的意思是：我知道這段程式碼在往 Strategy 的方向長，但我這次只走三步，因為三步之後痛點就消失了。

這是最常見、也最被低估的方向。

一個完整的「朝向」過程

起點：一個 200 行的 calculateFee() 方法，裡面有 5 段 if/else

Step 1  Extract Method            → 5 個私有方法，主方法剩 30 行
        ✅ 測試全綠。痛點還在嗎？「新增費率要改 3 處」→ 還在。繼續。

Step 2  把 5 個方法的共同參數整理成 FeeContext（Introduce Parameter Object）
        ✅ 測試全綠。痛點還在嗎？→ 還在。繼續。

Step 3  Extract Class → FeeCalculation 類別，含那 5 個方法
        ✅ 測試全綠。痛點還在嗎？
        →「新增費率」現在只要改 1 處了。痛點消失。

        ⛔ 停。不需要走到 Strategy。

如果三個月後出現了第 6 種、第 7 種計算方式，而且它們真的各自不同，那時再從 Step 3 繼續走：

Step 4  Introduce Interface（FeeCalculator）
Step 5  把 5 個方法拆成 5 個實作類別
Step 6  呼叫端改為依賴介面
        → 現在它是 Strategy 了。

🔧 本手冊的工程建議：每一步之後都要問「痛點消失了嗎？」 這一問是整套方法的節流閥。沒有這一問，所有的重構都會自動滑向「走到 Pattern 為止」。 在第 21 章的 AI Workflow 中，這一問被設計成 AI 必須向人類回報的檢查點。

中間態設計是合法的產物

很多工程師（與絕大多數 AI）有一種焦慮：「這樣改一半，結構不上不下，很奇怪。」

這個焦慮是錯的。 中間態設計有它自己的價值：

每一行都是一個可以長期停留的穩定狀態。

4.3 Refactoring To a Pattern

「抵達」的判斷標準是什麼？本手冊建議三個條件同時成立：

🏭 業界常見實務：用 git log 當證據 這是最被低估的技巧。要判斷「這些分支會不會各自演化」，最可靠的證據不是猜測，是歷史：

# 看這個檔案過去兩年的變更，每次改了哪些行
git log --since="2 years ago" -p --follow -- src/main/java/com/example/fee/FeeService.java

# 更快的方式：看每次 commit 改了幾個檔案（判斷 Shotgun Surgery）
git log --since="2 years ago" --name-only --pretty=format:"%h %s" -- src/main/java/com/example/fee/ \
  | awk 'NF' | sort | uniq -c | sort -rn | head -20

如果 27 次變更裡有 23 次是改同一個常數，那麼 Strategy 不是答案（回到第 1.5 節的案例）。

4.4 Refactoring Away From a Pattern

這是本手冊最強調、也是企業裡最缺乏的能力。

當一個 Pattern 的適用前提已經不存在時，保留它不是「維持架構完整性」，而是持續支付一筆沒有對應收益的成本。

為什麼沒有人做

一個典型的移除流程

現況：PaymentProcessorFactory + PaymentProcessor 介面 + 1 個實作類別

診斷：
  ✓ 只有 1 個實作（三年來都是）
  ✓ Factory 的內容是 `return new CreditCardProcessor();`
  ✓ 介面沒有任何第二個實作，也沒有被 mock（測試用的是真實物件）
  → 這個 Pattern 提供的價值 = 0，成本 = 2 個額外檔案 + 1 層間接

移除步驟：
  Step 1  Inline Factory：呼叫端改為直接 new CreditCardProcessor()
          ✅ 測試全綠
  Step 2  刪除 PaymentProcessorFactory
          ✅ 測試全綠
  Step 3  Inline Interface：把呼叫端的型別從 PaymentProcessor 改成 CreditCardProcessor
          ✅ 測試全綠
  Step 4  刪除 PaymentProcessor 介面
          ✅ 測試全綠

結果：檔案 −2、間接層 −1、行為完全不變

⚠️ 移除前必須確認的三件事

1. 沒有外部模組依賴那個介面（用 IDE 的 Find Usages，範圍設定為整個 workspace；多模組專案要跨模組查）
2. 測試沒有依賴那個介面做 mock（若有，先評估改用真實物件或改用測試替身）
3. 不是框架要求的擴充點（例如 Spring 的 BeanPostProcessor 介面不能刪）

第 18 章會提供完整的移除手法目錄。

4.5 該在哪裡停下來

把三個方向合併成一個可以貼在牆上的判斷流程：

flowchart TD
    A[完成一個小重構步驟] --> B[執行測試]
    B --> C{測試通過?}
    C -->|否| D[Rollback 或修正]
    D --> A
    C -->|是| E{原本的痛點還在嗎?}
    E -->|不在了| F["⛔ 停。Commit。<br/>在 PR 描述說明為何停在這裡"]
    E -->|還在| G{下一步的代價<br/>低於它解決的痛?}
    G -->|否| H["⛔ 停。記錄技術債。<br/>等痛點變大再說"]
    G -->|是| I[執行下一步]
    I --> A

    style F fill:#d4edda,stroke:#28a745
    style H fill:#fff3cd,stroke:#ffc107

🤖 AI Agent 使用建議 這張圖就是 AI Refactoring Workflow 的核心迴圈（第 21 章）。 關鍵在於「E」與「G」兩個菱形必須由人類回答，或至少由人類確認 AI 的回答。 AI 傾向於在這兩處一路回答「還在」「是」，直到走完整個 Pattern。

4.6 本章實務案例

情境：某券商的委託單驗證邏輯，歷經三任團隊。

第一任（2018）：一個 OrderValidator.validate() 方法，600 行，裡面是連續的 if (...) throw new ValidationException(...)。

第二任（2021）：認為這是典型的 Chain of Responsibility 場景，重構為：

• ValidationRule 介面
• 14 個 Rule 實作類別
• ValidationChain 組裝器
• ValidationRuleRegistry + 自訂 annotation @Order
• 一組 YAML 設定檔控制規則的啟用與順序

第三任（2024，接手後的觀察）：

第三任的決策：執行 Refactoring Away。

Step 1  刪除 YAML 設定與 Registry，改為在一個類別中明確列出規則順序
        （順序從「執行期不可見」變成「原始碼裡一眼可見」）
        ✅ 測試全綠

Step 2  把 14 個 Rule 中，7 個只有 3～5 行且從未單獨變動的，
        inline 回一個 BasicOrderChecks 類別
        ✅ 測試全綠

Step 3  保留其餘 7 個 Rule 類別（它們確實各自複雜、且有獨立的測試）
        但把 ValidationChain 簡化為一個明確的 List<ValidationRule>
        ✅ 測試全綠

結果：

注意：這不是「把 Pattern 全部拆光」。 第三任保留了 7 個 Rule 類別——因為那 7 個真的各自複雜、各自有測試、各自演化過。他們拆掉的是「沒有帶來價值的那一半」。

🔧 這個案例最值得學的一點 第二任團隊並不笨，他們的設計在教科書上完全正確。他們的錯誤只有一個：把「規則可能會頻繁增減與重排」當成了事實，但那只是預測，而且預測錯了。 而第三任團隊做對的事，是用三年的 git log 當證據去驗證那個預測，而不是憑感覺。

4.7 本章注意事項

⚠️ 不要在同一個 PR 裡同時做 Toward 與 Away 例如「把 A 模組導入 Strategy，順便把 B 模組的 Factory 拆掉」。這兩件事的風險性質不同，應該分開 Review。

⚠️ Away From 之前一定要先確認測試覆蓋 移除抽象層時，最容易漏掉的是「只有某個整合測試才會走到」的路徑。移除前請先確認該區域的測試覆蓋率，必要時補 Characterization Test。

✅ 把「停下來的理由」寫進 PR 建議的寫法：

## 重構範圍
Extract Method × 5 → Extract Class × 1

## 為什麼停在這裡（沒有導入 Strategy）
痛點「新增費率要改 3 處」已在 Extract Class 後消除（現在只需改 1 處）。
檢視 git log 近兩年 27 次變更，其中 23 次改的是費率常數而非演算法，
不符合導入 Strategy 的前提（變體需各自獨立演化）。
若未來出現第 3 種演算法，可從本次的 FeeCalculation 類別繼續演進。

📌 Away From Patterns 的完整手法在第 18 章 本章只建立觀念。第 18 章會給出移除 Factory、Interface、Decorator、Observer 等的具體步驟與安全檢查。

第 5 章 為什麼企業需要 Refactoring to Patterns

前四章講的是「怎麼做」與「為什麼這樣做」。這一章要回答的是另一個問題：為什麼企業要花錢做這件事？

如果你需要說服的對象是部門主管、PMO 或資訊長，這一章就是你的素材。

5.1 變更成本曲線

軟體專案真正的成本，不在第一次開發，而在後續的每一次變更。

flowchart LR
    subgraph L["未做設計改善的系統"]
        direction TB
        L1["第 1 次變更：3 天"] --> L2["第 5 次變更：8 天"] --> L3["第 10 次變更：20 天"] --> L4["第 15 次變更：<br/>「這個不能改，<br/>我們另外做一支」"]
    end
    subgraph R["持續做設計改善的系統"]
        direction TB
        R1["第 1 次變更：3 天"] --> R2["第 5 次變更：4 天<br/>（含 1 天重構）"] --> R3["第 10 次變更：3 天"] --> R4["第 15 次變更：3 天"]
    end

    style L4 fill:#f8d7da,stroke:#dc3545
    style R4 fill:#d4edda,stroke:#28a745

左邊的終局——「這個不能改，我們另外做一支」——是企業 Legacy 系統氾濫的真正成因。它不是因為技術落後，是因為每次變更都比上次更貴，貴到某個臨界點之後，繞過它比修改它便宜。

然後你就有了兩套做類似事情的系統。五年後，有五套。

🔧 本手冊的工程建議：用「繞過成本」而非「技術債」來溝通 管理層對「技術債」四個字已經疲乏了。改用具體的問句：

• 「過去兩年，有幾個需求因為『那個系統不好改』而被放棄或繞過？」
• 「我們有幾套系統在做重疊的事？當初為什麼不改原本那套？」

這兩個問題的答案，通常比任何技術指標都更有說服力。

5.2 技術債的四個象限

不是所有技術債都該還。分類決定策略。

quadrantChart
    title 技術債的處理優先順序
    x-axis "很少變動" --> "經常變動"
    y-axis "改動成本低" --> "改動成本高"
    quadrant-1 "① 最優先處理"
    quadrant-2 "④ 觀察即可"
    quadrant-3 "③ 順手改善"
    quadrant-4 "② 次要處理"
    "計費核心模組": [0.85, 0.9]
    "報表產生器": [0.75, 0.35]
    "十年沒動的批次": [0.1, 0.85]
    "工具類別": [0.2, 0.2]

⚠️ 第 ④ 象限是 AI 最容易浪費資源的地方 當你對 AI 說「掃描整個專案找出 Code Smell」，它會忠實地回報第 ④ 象限的所有問題——那些又長又醜、但十年沒人碰過的程式碼。 這些報告看起來很有價值，實際上處理它們的投資報酬率是負的（重構風險 > 零收益）。 第 21 章的 AI Workflow 明確要求：Smell 分析必須結合 git 變更頻率資料，否則輸出無法用於決策。

實務上取得變更頻率的方式：

# 找出過去一年變更最頻繁的 30 個檔案（第 ①、② 象限的候選）
git log --since="1 year ago" --name-only --pretty=format: -- '*.java' \
  | grep -v '^$' | sort | uniq -c | sort -rn | head -30

把這份清單與 SonarQube 的複雜度報告交叉比對，交集就是第 ① 象限。這才是重構應該投入的地方。

5.3 AI 時代帶來的新壓力

這一節是本手冊與傳統重構教材最根本的差異。

在 2023 年之前，「設計品質」的把關機制大致是：

工程師寫程式（速度受限於人類）
    ↓
資深工程師 Code Review（速度也受限於人類，但量相當）
    ↓
品質大致可控

2026 年的現況是：

AI Agent 產生程式碼（一次 800 行，30 秒）
    ↓
資深工程師 Code Review（一次 800 行，30 分鐘，而且注意力會下降）
    ↓
❌ 產能不對等 → Review 退化成「看起來沒問題就 approve」

這造成三個新問題：

🤖 第 ③ 點值得特別展開 當你請 AI「重構這段程式碼並補上測試」時，AI 是先理解程式碼、再產生測試的。 如果它對程式碼的理解有偏差（例如誤解了某個 if 的業務意圖），那麼它產生的測試會忠實地驗證它的錯誤理解。 結果是：測試全綠，但行為已經改變。 而綠燈給了團隊虛假的安全感。

對策（第 38.3 節詳述）：

1. Characterization Test 必須在重構之前、基於現行程式碼的實際輸出產生，而非基於 AI 對程式碼的理解
2. 重構的 PR 中，測試檔案不應該被修改。若測試需要修改，代表行為改變了，必須明確說明
3. 高風險模組採用「A 產生實作、B 產生測試」的分離機制（人與 AI 或兩個獨立 AI session）

5.4 三個真實的企業痛點

🏭 這三個痛點在金融、保險、製造業的 IT 部門幾乎普遍存在。

痛點一：「那個系統只有某某人能改」

表象：人力風險、無法休假、離職即危機。

根因：程式碼的複雜度超過了「靠閱讀就能理解」的門檻，只能靠經驗記憶來維護。

Refactoring to Patterns 的作用：不是讓程式碼變漂亮，而是把「只存在某人腦中的知識」外顯成結構。當 if (type == 3 && flag == 'Y') 被重構成 if (order.isUrgentTransfer()) 時，那個知識就從人腦移到了程式碼裡。

痛點二：「需求評估永遠是 3 個月起跳」

表象：業務單位覺得 IT 沒有競爭力。

根因：每個需求都要穿過大量的既有耦合，評估時無法確定影響範圍，只能報高。

Refactoring to Patterns 的作用：把變化點收斂。當「新增一種商品」從「要改 8 個檔案、影響範圍不明」變成「新增 1 個類別、其他不動」時，評估才可能準確。

痛點三：「導入 AI 之後，程式碼品質反而下降了」

表象：PR 數量增加，但 bug 也增加；新人更看不懂專案。

根因：AI 加速了「產出」，但團隊沒有同步加速「把關」。

Refactoring to Patterns 的作用：提供一套AI 也能遵守的、可驗證的設計紀律——這正是第五部與附錄 B 的內容。

5.5 導入成本的誠實評估

🔧 本手冊的工程建議 任何宣稱「導入某方法論零成本」的文件都不可信。以下是誠實的估算，供規劃參考。

最常見的失敗模式（🏭 業界普遍觀察）：

5.6 本章實務案例

情境：某產險公司的核保系統現代化評估（2025 年）。

背景：系統 2009 年上線，Java 6 起家，現在是 Java 8 + Spring 4，約 120 萬行。業務單位抱怨「新商品上架要 6 個月」。

第一版提案（被否決）：全面重寫為微服務架構，預算 8000 萬，工期 30 個月。

否決理由：董事會詢問「重寫期間，現有系統的法規變更（每年約 15 次）怎麼辦？」提案方回答「並行維護」——等於同時養兩套系統 30 個月。

第二版提案（採用）：以 Refactoring to Patterns + Strangler Fig 為主軸，分三階段。

第一階段結束時的實際數據：

第二階段結束時：新商品上架工時降至平均 7 週。

這個案例的三個關鍵決策：

1. 沒有重寫。 把 8000 萬的重寫，換成 5100 萬的漸進改善，而且期間法規變更照常進行。
2. 第一階段完全沒有改善「功能」，只建立了安全網。 這是最難向管理層說明、但也最關鍵的一步——第二階段之所以能快，正是因為第一階段建好了測試。
3. Strategy 只導入了三處。 評估時發現原本預期的 17 處「多變體」中，只有 3 處符合「變體會各自獨立演化」的條件，其餘 14 處用參數外部化就解決了。

5.7 本章注意事項

⚠️ 不要承諾「重構之後開發速度會變快」 短期內不會。重構的收益出現在「第 5 次之後的變更」。承諾短期效益，三個月後會失去管理層的信任。 誠實的說法是：「前三個月會慢 15%，從第二季開始，同類需求的工時會下降。我們會逐月追蹤數據。」

⚠️ 不要在沒有度量的情況下開始 至少要有：① 該模組的變更頻率（git log）② 同類需求的歷史工時 ③ 上線後的回歸 bug 數。 沒有 before 數據，你永遠無法證明 after 有價值。

⚠️ 第 ④ 象限（低變動 + 高成本）真的不要碰 這一條會被違反，因為那些程式碼最醜、最容易在掃描報告中跳出來。請在 AI 的 Prompt 中明確排除。

✅ 把重構工時納入需求估算，而非另外申請 「這個需求 5 天，其中 1 天是為了讓它好做而先整理既有程式碼」——這是正常的工程估算，不需要特別核准。 反之，「我要申請 20 天做重構」一定會被砍。

📌 本部結束 到這裡，你應該能回答三個問題：什麼是 Refactoring to Patterns（第 1 章）、什麼算重構（第 2 章）、Pattern 的代價是什麼（第 3 章）、三個演進方向（第 4 章）、以及為什麼企業要投資（第 5 章）。 接下來的第二部，要處理更前面的問題：你怎麼知道哪裡有問題？

第二部：Code Smell

第一部建立的是判斷力，這一部要建立的是證據能力。

Refactoring to Patterns 全流程的起點不是「我想用某個 Pattern」，而是「這裡有一個可以被指出來的具體問題」。Code Smell 就是那個問題的名字。

沒有名字的問題無法討論、無法 Review、無法寫進 PR、也無法教給 AI。這一部的目的，是讓團隊擁有一套共同的詞彙。

第 6 章 Code Smell 判讀方法論

6.1 Smell 不是錯誤

這是最重要的觀念，也是最常被誤解的一點。

Code Smell 是「可能有設計問題」的徵兆，不是「一定有問題」的判決。

這個差別在工具與 AI 介入之後變得格外重要。SonarQube 會把 Code Smell 標成問題數量，AI 會把它列成待辦清單——兩者都很容易讓團隊誤以為「這些都要清掉」。

⚠️ 一個 800 行、十年沒人改過、而且跑得好好的批次程式，它的 Long Method 不是問題，是現狀。 動它才是問題（風險 > 0，收益 = 0）。這正是第 5.2 節第 ④ 象限的結論。

6.2 判讀 Smell 的三個問題

🔧 本手冊的工程建議 任何 Smell 被提出時（無論是人提的還是 AI 掃出來的），都必須通過這三個問題才進入重構候選名單。

flowchart TD
    A[發現一個 Code Smell] --> Q1{Q1. 它正在造成<br/>實際的變更痛苦嗎?}
    Q1 -->|否| R1["記錄技術債<br/>不處理"]
    Q1 -->|是| Q2{Q2. 這個區域<br/>未來還會變嗎?}
    Q2 -->|否| R2["記錄技術債<br/>不處理"]
    Q2 -->|是| Q3{Q3. 有測試保護嗎?}
    Q3 -->|否| R3["先建立<br/>Characterization Test"]
    Q3 -->|是| R4["✅ 進入重構候選"]
    R3 --> R4

    style R1 fill:#e9ecef,stroke:#6c757d
    style R2 fill:#e9ecef,stroke:#6c757d
    style R3 fill:#fff3cd,stroke:#ffc107
    style R4 fill:#d4edda,stroke:#28a745

三個問題各自需要什麼證據：

用一個指令同時取得 Q1 與 Q2 的證據：

# 某個檔案過去兩年的變更次數、每次的 commit 摘要
git log --since="2 years ago" --oneline --follow -- src/main/java/com/example/fee/FeeService.java

# 更有用的：找出「每次都一起被修改」的檔案組合（Shotgun Surgery 的直接證據）
git log --since="2 years ago" --name-only --pretty=format:"===%h" -- '*.java' \
  | awk '/^===/{if(n>1)print buf; buf="";n=0;next}{if($0!=""){buf=buf" "$0;n++}}END{if(n>1)print buf}' \
  | tr ' ' '\n' | grep -v '^$' | sort | uniq -c | sort -rn | head -20

6.3 何時不要重構

🔧 本手冊的工程建議：七個明確的「不要」

⚠️ 第 5 條特別容易被 AI 違反 AI 永遠不會說「我看不懂這段」。它會給出一個看似合理的解釋，然後基於那個解釋去重構。 這正是第 24 章「AI Hallucinated Business Rule」反模式的來源，也是附錄 B 治理規則第 8 條（Stop when business rules are unclear）存在的理由。

6.4 Smell 的嚴重度分級

🔧 本手冊的工程建議 導入時建議採用三級制，並把它寫進 Code Review 規範。

分級的關鍵不在 Smell 的種類，而在它所在的位置。

同樣是 Long Method：

  位於「每月改 3 次的計費核心」  → 🔴 阻斷
  位於「每年改 1 次的報表」      → 🟡 警告
  位於「十年沒改的批次」         → 🟢 觀察（且不處理）

🤖 AI Agent 使用建議 請 AI 做 Smell 分析時，必須同時提供變更頻率資料，並要求它輸出分級。 沒有分級的 Smell 清單是無法用於決策的——它只會讓團隊看到 400 個問題然後放棄。 附錄 A 的 Prompt 1（Code Smell Analysis）已內建這項要求。

6.5 本章實務案例

情境：某銀行團隊導入 SonarQube 後的第一週。

SonarQube 報告：4,127 個 Code Smell，技術債估計 312 天。

團隊的第一反應是「這個數字沒辦法看，先把 Quality Gate 關掉」。

改用本章方法論重新分析：

# Step 1：取得過去 18 個月變更最頻繁的檔案
git log --since="18 months ago" --name-only --pretty=format: -- '*.java' \
  | grep -v '^$' | sort | uniq -c | sort -rn > /tmp/churn.txt

head -20 /tmp/churn.txt

結果：4,127 個 Smell 分布在 892 個檔案中，但過去 18 個月被修改過的檔案只有 143 個。

決策：把 Quality Gate 設定為「只針對本次 PR 異動的程式碼」（SonarQube 的 New Code 模式），並把 54.3% 的歷史 Smell 標記為 baseline 不再計入。

六個月後的結果：

這個案例的核心教訓：

4,127 這個數字本身沒有意義，而且它的最大危害是讓團隊放棄。 把它拆成「會痛的 681 個」與「不會痛的 2,242 個」之後，這件事才變得可以執行。

相關的 SonarQube 設定方式，可參考本 repo 的 工具/SonarQube教學手冊.md。

6.6 本章注意事項

⚠️ 不要用 Smell 總數當 KPI 這會直接導致兩種行為：① 去清最容易清的（通常是最沒價值的）② 想辦法讓工具不要報。 有意義的指標是「高變更頻率檔案的 Smell 密度」。

⚠️ AI 掃出的 Smell 清單，預設是不可執行的 因為 AI 看不到 git 歷史與業務 roadmap（除非你提供）。請務必在 Prompt 中附上變更頻率資料，並要求分級。

✅ 把「這個 Smell 的證據是什麼」變成 Review 的標準問句 當有人在 Review 中說「這裡有 Code Smell」，標準回應是：「上次改這裡花了多久？未來還會改嗎？」 這一問能把討論從品味之爭拉回工程判斷。

📌 接下來兩章的用法 第 7、8 章是查詢用的目錄，不需要從頭讀完。建議的用法是：當你在 Review 或重構時遇到一個說不出名字的問題，來這裡找到它的名字，然後照著「候選重構」往下走。

第 7 章 Code Smell 目錄（上）重複、體積與職責

7.1 本章條目的共同格式

第 7、8 兩章共收錄 21 個 Code Smell。

⚠️ 請先看清楚這 21 個的來源，不要對外宣稱「原書有 21 個 smell」 Addison-Wesley 對《Refactoring to Patterns》的官方文案明載本書包含「descriptions of twelve design smells」，也就是 原書是 12 個。 本手冊列出 21 個，是因為企業現場的重構討論幾乎不可能只用 Kerievsky 的 12 個；Fowler《Refactoring》中另外 9 個在 Code Review 中同樣高頻。兩份清單合併後為 21 個。 以下對照表明確標示每一個 smell 的來源，供正式文件引用時擇一使用。

🔧 本手冊的工程建議 上表中標示「本書獨有」的四個 smell（Combinatorial Explosion、Oddball Solution、Solution Sprawl、Indecent Exposure），是 Kerievsky 對 smell 目錄最主要的貢獻，也是最直接指向 pattern-directed refactoring 的四個。若你的團隊時間有限，優先把這四個納入 Code Review Checklist 的效益最高。

每一個條目採用相同的九段格式，方便查詢與比對：

⚠️ 關於「可能演進出的 Pattern」欄位的鄭重提醒 這個欄位是本手冊最容易被誤用的地方。它的正確讀法是：

✅ 「如果痛點持續存在、而且變體會各自演化，走下去可能會長成 Strategy」
❌ 「這個 Smell 對應 Strategy，所以改成 Strategy」

第 9.1 節會再次強調這一點。請不要把第 9.2 節的總表當成自動轉換規則交給 AI。

7.2 Duplicated Code

症狀：同一段邏輯（或高度相似的邏輯）出現在兩個以上的地方。

根因：

• 趕時間時複製貼上，打算「之後再整理」
• 兩個團隊平行開發，不知道對方已經寫過
• 原本只是相似，後來各自演化成真的重複

風險：修改時漏改其中一處。這是企業裡最常見的生產事故成因——不是程式寫錯，是「改了 3 處、漏了第 4 處」。

值得重構的訊號：

• 這段邏輯改過，而且曾經漏改過
• 重複的是業務規則（例如手續費計算、資格判斷）
• 重複處 ≥ 3

不要重構的訊號：

• 只是長得像，但業務意義不同（例如「員工年齡驗證」與「商品保固天數驗證」剛好都是 > 0 && < 150）——強行合併會製造錯誤的耦合
• 重複在測試程式碼中（測試的重複容忍度較高，可讀性優先）
• 兩處分屬不同的 bounded context，未來會各自演化

候選低階重構：Extract Method → Pull Up Method（若在同一繼承體系）→ Extract Class → Form Template Method

可能演進出的 Pattern：Template Method（骨架相同、細節不同時）、Strategy（整段邏輯可替換時）

AI 如何識別與處理：

✅ AI 擅長：找出語法上相似的區塊（這是它的強項）
❌ AI 不擅長：判斷「長得像」與「真的是同一件事」的差別

要求 AI 輸出時必須說明：
- 這兩段的「業務意義」是否相同？依據是什麼？
- 過去兩年，這兩段是「一起被修改」還是「各自被修改」？

驗證方式：

• 抽取後，兩處的呼叫端測試皆全綠
• 確認抽出的方法沒有為了合併而新增參數旗標（若需要 boolean isTypeA 參數才能合併，代表它們不該合併）
• 確認沒有把不同 bounded context 的程式碼耦合在一起

⚠️ 最危險的重構之一：用旗標參數強行合併

// ❌ 這不是消除重複，這是製造更難維護的程式碼
private BigDecimal calculate(Order o, boolean isVip, boolean isOverseas, boolean isUrgent) {
    // 8 個分支組合
}

如果合併需要新增旗標參數，那代表這兩段本來就不是同一件事。這正是第 8.3 節 Combinatorial Explosion 的起點。

7.3 Long Method

症狀：一個方法長到需要捲動才能看完，或需要用註解分段。

根因：每次需求變更都往裡面加幾行，沒有人負責重新組織。

風險：無法單獨測試其中一段；理解成本高；容易在中間插入破壞性的變更。

值得重構的訊號：

• 方法內有註解分段（// 1. 驗證 // 2. 計算 // 3. 儲存）——註解正在告訴你邊界在哪
• 區域變數超過 7～8 個
• 巢狀層級 ≥ 3
• 這個方法最近改過

不要重構的訊號：

• 它是一段線性的、沒有分支的設定程式碼（例如 100 行的欄位對應）——拆開反而更難讀
• 效能敏感的內層迴圈（方法呼叫雖然通常會被 JIT inline，但在極端場景需實測）

候選低階重構：Extract Method → Replace Temp with Query → Introduce Parameter Object → Decompose Conditional

可能演進出的 Pattern：Compose Method（第 12.1 節，這是最直接的目標）、Command（若每一段都是獨立的操作）

AI 如何識別與處理：

✅ AI 擅長：Extract Method（這是機械化操作）
⚠️ AI 的常見錯誤：抽出來的方法名稱只描述「怎麼做」而非「做什麼」
    例如抽出 `private void doStep2()` — 這沒有改善任何事

要求 AI：
- 方法名稱必須描述「意圖」，不是「步驟編號」
- 每次只抽一個方法，跑完測試再抽下一個
- 不得同時調整邏輯

驗證方式：

• 既有測試全綠，且測試檔案未被修改
• 抽出的每個方法名稱，能讓人不看內容就知道它做什麼
• 主方法讀起來像一段「步驟說明」

7.4 Large Class

症狀：一個類別有太多欄位、太多方法，或明顯在做好幾件事。

根因：「這個功能跟現有的有點關係，就加在這裡吧」，累積而成。典型的 XxxService、XxxManager、XxxUtil。

風險：

• 高耦合（任何改動都可能影響其他功能）
• 無法平行開發（多人同時改同一個檔案）
• 測試需要準備大量無關的 mock

值得重構的訊號：

• 欄位可以明顯分成幾組，每組只被特定的方法使用（這是 Extract Class 的最佳訊號）
• git log 顯示這個檔案每次被改的原因不同（即 Divergent Change，第 7.8 節）
• 類別名稱裡有 And、Manager、Util、Helper

不要重構的訊號：

• 它是一個資料載體（DTO、Entity），欄位多是正常的
• 它是框架要求的結構（例如某些設定類別）

候選低階重構：Extract Class → Move Method / Move Field → Extract Interface（若有多個使用面向）

可能演進出的 Pattern：Facade（若拆出的多個類別仍需統一入口）、Strategy、State

AI 如何識別與處理：

✅ AI 擅長：分析「哪些欄位被哪些方法使用」，產生分群建議
❌ AI 不擅長：判斷分群的「業務意義」是否合理

要求 AI 輸出一張「欄位 × 方法」使用矩陣，由人類判斷切割線在哪裡。
不要讓 AI 直接執行切割。

驗證方式：

• 拆出的每個類別，都能用一句話說明它的職責（不含「和」字）
• 拆分後，測試準備的 mock 數量下降
• 沒有產生循環依賴（可用 ArchUnit 驗證，見第 39 章）

7.5 Long Parameter List

症狀：方法有太多參數（一般認為 > 4 就該警覺，> 7 幾乎必然有問題）。

根因：功能增加時不斷往簽章上加參數；或是為了「彈性」而把所有可能的選項都開放出來。

風險：呼叫端容易傳錯順序（尤其多個同型別參數並列時，編譯器抓不到）；難以閱讀；每次新增參數都要改所有呼叫端。

值得重構的訊號：

• 有 ≥ 2 個相鄰參數是同一個型別（calculate(String custId, String prodId, String branchId) — 傳錯順序編譯器不會報錯）
• 某幾個參數總是一起出現（這是 Data Clumps，第 7.6 節）
• 有 boolean 旗標參數（呼叫端讀起來是 calc(order, true, false, true)，完全無法理解）

不要重構的訊號：

• 參數確實各自獨立且都必要，且方法只被呼叫一兩次
• 是框架規定的簽章

候選低階重構：Introduce Parameter Object → Preserve Whole Object → Replace Parameter with Method Call → Remove Flag Argument（把一個帶旗標的方法拆成兩個具名方法）

可能演進出的 Pattern：Builder（參數多且有可選組合時，第 11.5 節）、Command（參數整組代表一次操作時）

AI 如何識別與處理：

✅ 要求 AI 優先處理 boolean 旗標參數 — 這是 CP 值最高的
    calc(order, true) → calcWithDiscount(order)
                       calcWithoutDiscount(order)
⚠️ 不要讓 AI 直接跳到 Builder。先做 Introduce Parameter Object，
    多數情況下那樣就夠了。

驗證方式：

• 呼叫端讀起來不需要對照方法簽章就能理解
• 沒有為了湊 Parameter Object 而把不相關的參數硬綁在一起

7.6 Data Clumps

症狀：同一組資料（三個以上的欄位或參數）總是成群出現在不同的地方。

典型例子：

// Java 8 — 這三個永遠一起出現
public void transfer(String fromBank, String fromBranch, String fromAccount,
                     String toBank,   String toBranch,   String toAccount,
                     BigDecimal amount) { ... }

根因：缺少一個代表該概念的型別。上例缺少的是 AccountNumber。

風險：驗證邏輯散落各處（每個用到這三個欄位的地方都要各自驗證）；參數容易傳錯；概念無法被命名與討論。

值得重構的訊號：

• 這組欄位在 ≥ 3 個地方一起出現
• 這組欄位有共同的驗證規則（例如帳號格式檢查）
• 你能為這組欄位取一個業務上的名字

不要重構的訊號：

• 只是碰巧一起出現，沒有共同的業務概念

候選低階重構：Extract Class / Introduce Parameter Object → Move Method（把相關的驗證與行為搬進新類別）

可能演進出的 Pattern：Value Object（DDD 概念，非 GoF）；有時會演進為 Composite

Before / After 對照：

// Before：Java 8
public void transfer(String fromBank, String fromBranch, String fromAccount,
                     String toBank, String toBranch, String toAccount,
                     BigDecimal amount) {
    if (fromBank == null || fromBank.length() != 3) throw new IllegalArgumentException();
    if (fromAccount == null || fromAccount.length() < 10) throw new IllegalArgumentException();
    // 同樣的驗證再寫一次給 to...
}

// After：Java 25 — record 讓 Value Object 幾乎沒有樣板程式碼
public record AccountNumber(String bank, String branch, String account) {
    public AccountNumber {
        if (bank == null || bank.length() != 3) {
            throw new IllegalArgumentException("銀行代碼必須為 3 碼");
        }
        if (account == null || account.length() < 10) {
            throw new IllegalArgumentException("帳號長度不足");
        }
    }
    public boolean isSameBank(AccountNumber other) {
        return this.bank.equals(other.bank);
    }
}

public void transfer(AccountNumber from, AccountNumber to, BigDecimal amount) { ... }

注意這次重構帶來的額外好處：驗證邏輯從「散落在每個呼叫點」變成「不可能建立出無效的 AccountNumber」。這是型別系統幫你做的事。

AI 如何識別與處理：

✅ AI 擅長：找出成群出現的參數
✅ AI 擅長：產生 record 與建構子驗證

⚠️ 必須人工確認：新型別的「名字」是否符合公司的領域語彙
    （例如公司內部叫「帳戶識別碼」而非「帳號」）

驗證方式：

• 所有呼叫端編譯通過
• 原本散落的驗證邏輯已集中，且行為完全一致（包含例外訊息）
• 序列化行為未改變（若該結構會進出 JSON 或 DB）

7.7 Primitive Obsession

症狀：用 String、int、BigDecimal 表示具有業務意義的概念。

String customerId;      // 其實有格式規則
BigDecimal amount;      // 其實有幣別
int status;             // 其實是 5 種狀態的其中之一
String email;           // 其實有驗證規則

根因：一開始只是一個簡單欄位，業務規則後來才長出來，但型別沒有跟著演化。

風險：

• 業務規則散落（每個用到 amount 的地方都要自己處理幣別）
• 型別無法防呆（transfer(customerId, accountId) 傳反了，編譯器不會抓）
• 金額相關的錯誤特別昂貴（不同幣別的 BigDecimal 直接相加）

值得重構的訊號：

• 這個 primitive 有格式或範圍的驗證規則
• 這個 primitive 有專屬的操作（例如金額的換匯、帳號的遮罩）
• 曾經因為參數傳反而出過 bug

不要重構的訊號：

• 它真的只是一個數字（例如迴圈計數器、陣列長度）
• 只在單一方法內部使用

候選低階重構：Replace Data Value with Object → Replace Type Code with Class（第 14.4 節）→ Extract Class

可能演進出的 Pattern：Value Object；若是狀態碼，可能演進為 State（第 13.1 節）

特別說明：金額

🏭 業界常見實務 金融系統中，BigDecimal 直接代表金額是最普遍的 Primitive Obsession，而且是最值得處理的一個：

// After：Java 25
public record Money(BigDecimal amount, Currency currency) implements Comparable<Money> {
    public Money {
        Objects.requireNonNull(amount);
        Objects.requireNonNull(currency);
    }
    public Money add(Money other) {
        if (!currency.equals(other.currency)) {
            throw new CurrencyMismatchException(currency, other.currency);   // ← 這個例外救過很多人
        }
        return new Money(amount.add(other.amount), currency);
    }
    @Override public int compareTo(Money o) { /* 同幣別才可比較 */ }
}

但請注意：在既有系統中導入 Money 是一次大範圍的變更，必須漸進進行（先在新程式碼使用，邊界處轉換），不能一次全換。

AI 如何識別與處理：

✅ AI 擅長：識別出「這個 String 其實有格式規則」
❌ AI 的高風險行為：一次把整個專案的 BigDecimal 換成 Money
    — 這會產生數千行的 diff，無法 Review，而且極可能改變精度行為

要求 AI：
- 一次只處理一個型別、一個模組
- 明確列出精度（scale）與捨入（RoundingMode）行為是否改變

驗證方式：

• 精度與捨入行為完全未變（金額重構的頭號風險）
• JSON 序列化的格式未變（下游系統可能依賴）
• DB 欄位對應未變

7.8 Divergent Change

症狀：同一個類別，因為不同的原因被反覆修改。

OrderService 過去一年的變更原因：
  3 次 — 稅率規則改變
  4 次 — 通知方式調整
  2 次 — 報表欄位增加
  5 次 — 折扣邏輯變更

根因：違反單一職責原則。這個類別承擔了多個「變化的軸線」。

風險：任何一個原因的變更，都可能影響到其他三個面向；測試範圍被迫擴大；多人同時修改時衝突頻繁。

值得重構的訊號：

• git log 顯示這個檔案的 commit 訊息主題明顯分成好幾類（這是最客觀的證據）
• 每次改動只碰到檔案的某一區塊，而不同次改動碰的區塊不重疊

不要重構的訊號：

• 變更雖然頻繁，但原因其實是同一個
• 這是一個 Facade，職責本來就是「彙整」

取得證據的方式：

# 列出某檔案的所有 commit 訊息，人工分類其變更原因
git log --pretty=format:"%ad %s" --date=short --follow \
  -- src/main/java/com/example/order/OrderService.java | head -40

候選低階重構：Extract Class（沿著「變化原因」切，不是沿著「功能」切）→ Move Method

可能演進出的 Pattern：Strategy（若某條軸線有多個變體）、Observer（若某條軸線是「通知」）

AI 如何識別與處理：

✅ 給 AI 這個 Prompt 效果很好：

"以下是 OrderService 過去兩年的 commit 訊息。
 請依「變更原因」分類，並指出每一類變更主要影響檔案的哪些方法。
 不要修改任何程式碼，只輸出分析。
 [貼上 git log 輸出]"

這比讓 AI 讀原始碼去猜職責準確得多 — 因為 git log 是行為證據。

驗證方式：

• 拆分後，模擬一次「稅率變更」，確認只需要改 1 個檔案
• 沒有產生新的雙向依賴

7.9 Shotgun Surgery

症狀：一個小小的需求變更，需要修改很多個檔案。

Divergent Change 的相反：

根因：某個概念沒有被封裝，它的片段散落在系統各處。

風險：這是企業裡最直接導致生產事故的 Smell——因為必然會有人漏改其中一處。

值得重構的訊號（🔴 通常直接列為阻斷級）：

• 曾經因為漏改而出事
• 新人第一次做這類需求時，必定會漏掉某處
• 團隊有一份「改 XX 時要記得改的地方」的文件（這份文件的存在本身就是證據）

不要重構的訊號：

• 散落的地方分屬不同的部署單元，收攏會製造新的耦合
• 收攏需要建立跨層的依賴（會違反架構規則）

候選低階重構：Move Method / Move Field（把散落的行為搬到一起）→ Inline Class（若某個類別只是個薄殼）→ Extract Class（建立一個真正擁有該概念的類別）

可能演進出的 Pattern：Facade、Observer（若散落的是「某事發生時要通知的動作」）

AI 如何識別與處理：

✅ 最有效的用法 — 讓 AI 分析 git 的「共同變更」關係：

"以下是過去兩年，每次 commit 修改的檔案清單。
 請找出「經常一起被修改」的檔案組合（同時出現 ≥ 5 次），
 並推測它們共享的是什麼概念。
 [貼上 git log --name-only 輸出]"

這會直接指出 Shotgun Surgery 的位置，準確度遠高於靜態分析。

驗證方式：

• 模擬一次典型變更，確認需要修改的檔案數下降
• 收攏後沒有違反架構分層（用 ArchUnit 驗證）
• 那份「要記得改的地方」的文件可以刪掉了

7.10 Feature Envy

症狀：某個方法對「別的類別的資料」比對「自己類別的資料」更有興趣。

// Before：Java 8 — 這個方法住錯地方了
public class OrderReportService {
    public String formatCustomerLabel(Customer c) {
        return c.getLastName() + c.getFirstName()
             + "（" + c.getVipLevel() + "）"
             + (c.getAge() >= 65 ? " [敬老]" : "");
    }
}

這個方法只用到 Customer 的資料，沒用到 OrderReportService 的任何東西。

根因：資料與行為被分開了（典型的「貧血模型」症狀）。

風險：Customer 的結構改變時，要修改散落在各服務中的方法；相同的格式化邏輯容易被重複實作。

值得重構的訊號：

• 方法中 otherObject.getXxx() 的呼叫次數，明顯多於 this.xxx
• 同樣的邏輯在其他服務裡也出現過（結合 Duplicated Code）

不要重構的訊號：

• 目標類別是 JPA Entity 且團隊採用嚴格的貧血模型架構——此時把行為搬進 Entity 會違反團隊約定（先討論架構決策，不要單方面改）
• 目標類別是 DTO 或外部 API 的回應結構（不該有業務行為）
• 這個方法需要用到多個類別的資料（此時它可能真的該待在服務層）

候選低階重構：Move Method → Extract Method 再 Move Method（若只有部分程式碼有 envy）

可能演進出的 Pattern：通常不需要 Pattern；有時會演進為 Visitor（第 15.4 節，當你不能修改目標類別時）

AI 如何識別與處理：

✅ AI 擅長：計算方法內的 this vs other 存取比例
⚠️ 必須人工確認：團隊的架構風格是否允許把行為放進該類別

Prompt 中必須告知 AI 團隊的架構約定，例如：
"本專案採用 Rich Domain Model，Entity 可以有業務方法"
或
"本專案 Entity 僅為資料載體，業務邏輯一律放在 Domain Service"
否則 AI 會依它的預設偏好（通常偏向 Rich Model）行動。

驗證方式：

• 搬移後，來源類別不再需要 import 目標類別的細節型別
• 沒有違反團隊的架構分層約定（ArchUnit）
• 若搬進 Entity，確認不會意外觸發 lazy loading

7.11 Solution Sprawl

症狀：實作一個職責所需的程式碼，散落在很多個類別或方法中。

📖 這是 Kerievsky 在原書中特別強調的 Smell，在 Fowler 的原始清單中沒有對應項目。

與 Shotgun Surgery 的差別：

典型例子：

「建立一張訂單」這件事，分布在：
  OrderController        — 組裝參數
  OrderValidator         — 驗證
  OrderNumberGenerator   — 產生單號
  OrderFactory           — 建立物件
  OrderEnricher          — 補充預設值
  OrderPersister         — 儲存
  OrderEventPublisher    — 發事件

想知道「一張訂單建立時到底做了哪些事」，要開 7 個檔案。

注意：這個例子裡的每一個類別單獨看都很合理。Solution Sprawl 的狡猾之處在於，它常常是「過度遵守單一職責原則」的結果。

風險：新人無法建立整體圖像；修改時容易在錯誤的層次動手；除錯時難以追蹤流程。

值得重構的訊號：

• 需要開 ≥ 5 個檔案才能理解一個業務流程
• 這些類別永遠一起被修改（用 git 驗證）
• 某些類別只有一個方法、且只被一個地方呼叫

不要重構的訊號：

• 這些類別確實各自被多處重用
• 分散是為了滿足明確的架構邊界（例如 Hexagonal 的 port/adapter）

候選低階重構：Inline Class（合併只有薄殼功能的類別）→ Move Method → Compose Method（第 12.1 節，讓主流程一眼可見）

可能演進出的 Pattern：Facade（保留細部類別，但提供一個統一入口，讓流程可見）

🔧 本手冊的工程建議：判斷準則 問一個問題：「這 7 個類別，有哪幾個曾經被單獨修改過、或被其他流程重用過？」 答案若是「沒有」，那它們不是 7 個職責，是 1 個職責被切成 7 塊。

AI 如何識別與處理：

⚠️ 這是 AI 最不擅長識別的 Smell，因為每個類別單看都符合 SRP
⚠️ 更糟的是：AI 本身就是 Solution Sprawl 的主要製造者
    （它傾向於為每個步驟建立一個類別）

有效的 Prompt：
"請畫出『建立訂單』這個流程實際經過的所有類別與方法的呼叫順序。
 然後標示出：哪些類別只被這一條流程使用？
 不要修改程式碼。"

驗證方式：

• 合併後，「這個流程做了什麼」能在 1～2 個檔案內看完
• 沒有把真正被重用的類別誤刪
• 沒有違反架構邊界

7.12 本章實務案例

情境：某壽險公司的「保單變更」功能，同時呈現了本章五個 Smell。

團隊在準備「新增保單借款功能」時，發現光是評估影響範圍就花了一週。以下是他們的診斷過程。

Step 1：先取證據，不先看程式碼

# 過去 24 個月，policy 套件下最常被一起修改的檔案
git log --since="24 months ago" --name-only --pretty=format:"===%h %s" \
  -- 'src/main/java/com/example/policy/**' > /tmp/policy-churn.txt

結果：

Step 2：對照 Smell 目錄

「三處的邊界值不同」是關鍵發現：

// PolicyChangeService.java
if (amount.compareTo(new BigDecimal("10000000")) > 0) { ... }   // 一千萬

// PolicyChangeValidator.java
if (amount.doubleValue() > 10000000) { ... }                     // 一千萬，但用 double

// PolicyDao.java（SQL 裡）
// AND CHG_AMT <= 9999999                                        // 少一元！

這代表已經發生過漏改，只是還沒有人發現。這個發現讓這次重構從「技術債整理」升級為「風險處理」，立刻獲得了排程。

Step 3：處理順序（依風險，不依難度）

Step 8：停下來的決定

團隊原本規劃第 7 步之後導入 Strategy（讓每種「保單變更類型」成為一個 Strategy）。

評估後決定不做：

檢視 git log：過去兩年新增的變更類型 = 1 種
PM roadmap：未來一年規劃新增 = 1 種
→ 不符合「變體會持續增加且各自演化」的前提（第 4.3 節）
→ 停在 Extract Class。
→ 在 PR 描述中記錄此決策與依據。

最終成果：

7.13 本章注意事項

⚠️ 不要一次處理多個 Smell 上面案例中的 7 個步驟，是 7 個獨立的 PR。混在一起的話，一旦出事就無法定位。

⚠️ Smell 與 Bug 要分開處理 案例中第 2、3 步是 bug 修正，必須獨立於重構之外。把 bug 修正藏在重構 PR 裡，是企業裡常見但極危險的做法——因為它讓重構 PR 失去了「可安全 revert」的性質。

⚠️ Duplicated Code 的三處若「行為不同」，那是警訊而非雜訊 發現重複的程式碼彼此行為不一致時，先停下來確認哪個才對。不要直接挑一個當作基準去統一——你有 2/3 的機率選錯。

✅ 用 git 當證據，不要用直覺 本章反覆出現的 git log 指令是整套方法論最實用的工具。它把「我覺得這裡很亂」變成「這個檔案 24 個月被改了 47 次，分屬 5 種原因」。

✅ 重構完成後要「重新測量」 案例中的第 7 步很關鍵：拆完之後重新評估 Shotgun Surgery 是否還存在。很多時候處理了根因，衍生的 Smell 會自動消失，不需要另外處理。

第 8 章 Code Smell 目錄（下）條件、耦合與過度設計

本章收錄的 11 個 Smell，是最容易被 AI 錯誤處理的一批——尤其是 8.1 到 8.3，AI 幾乎必然會建議套用 Pattern。

8.1 Conditional Complexity

症狀：複雜的條件邏輯——深層巢狀的 if、冗長的布林運算式、難以理解的判斷。

// Before：Java 8 — 真實系統裡的樣子
if (order.getType() == 1 && order.getAmount().compareTo(LIMIT) > 0
        && (customer.getLevel() >= 3 || customer.getYears() > 5)
        && !order.isOverseas() && order.getStatus() != 9) {
    // 40 行
} else if (...) {
    // 又 40 行
}

根因：每次新增的業務規則，都以「再加一個條件」的方式塞進來。

風險：無法理解；無法測試（分支組合爆炸）；修改時容易破壞既有規則。

值得重構的訊號：

• 條件式本身需要註解才能看懂
• 巢狀層級 ≥ 3
• 布林運算元 ≥ 4
• 圈複雜度（Cyclomatic Complexity）> 10

不要重構的訊號：

• 條件雖多但扁平、可讀（例如連續的 guard clause）
• 這段程式碼很少變動

候選低階重構（依序嘗試，通常前兩步就夠了）：

1. Decompose Conditional      把條件抽成具名方法 → isVipLargeOrder(order, customer)
2. Replace Nested Conditional with Guard Clauses   把巢狀改為提早返回
3. Consolidate Conditional Expression   合併同結果的條件
4. Extract Method             把每個分支的內容抽出
5. （若仍有痛點）Extract Class → Introduce Interface

可能演進出的 Pattern：Strategy（第 12.2 節）、State（第 13.1 節，若條件是關於狀態轉移）、Command（第 13.2 節，若是分派邏輯）

第 1 步的效果常常被低估：

// 只做 Decompose Conditional，一步就大幅改善
if (isVipLargeDomesticOrder(order, customer)) {
    // 40 行
}

private boolean isVipLargeDomesticOrder(Order order, Customer customer) {
    return order.getType() == ORDER_TYPE_NORMAL
        && order.getAmount().compareTo(LIMIT) > 0
        && isVipCustomer(customer)
        && !order.isOverseas()
        && order.getStatus() != STATUS_CANCELLED;
}

private boolean isVipCustomer(Customer c) {
    return c.getLevel() >= VIP_LEVEL_THRESHOLD || c.getYears() > VIP_YEARS_THRESHOLD;
}

這一步沒有新增任何類別，卻解決了 80% 的可讀性問題。

AI 如何識別與處理：

🔴 這是 AI 最容易過度反應的 Smell

AI 的預設行為：
  看到多分支 if/else → 直接產生 Strategy 介面 + N 個實作類別

必須在 Prompt 中明確限制：
  "請依序只做以下步驟，做完一步停下來等我確認：
   1. Decompose Conditional（把條件抽成具名方法）
   2. Replace Nested Conditional with Guard Clauses
   不要建立任何新的類別或介面。"

驗證方式：

• 圈複雜度下降（SonarQube 可量測）
• 分支覆蓋率未下降
• 所有原本的邊界條件行為完全一致（特別注意 >= vs >）
• 沒有為了簡化而改變短路求值的順序（若條件中有副作用或 null 檢查，順序改變會出事）

⚠️ 短路求值順序是隱形地雷

if (customer != null && customer.getLevel() >= 3) { }   // 安全
if (customer.getLevel() >= 3 && customer != null) { }   // NPE

AI 在「整理」條件式時可能重排順序。這是必須明確檢查的項目。

8.2 Switch Statements

症狀：同一組 switch 或 if-else if 的型別判斷，在多個地方重複出現。

// 在三個不同的檔案裡都出現
switch (product.getType()) {
    case "LOAN":     return calcLoanFee(product);
    case "DEPOSIT":  return calcDepositFee(product);
    case "FX":       return calcFxFee(product);
}

根因：型別碼（type code）沒有被物件化，導致「依型別分派」的邏輯必須在每個需要的地方重寫。

風險：新增一種型別時，必須找出所有的 switch 並各自修改（這是 Shotgun Surgery 的特例）。

⚠️ 重要澄清：單一個 switch 不是 Smell 一個 switch 只出現在一個地方、而且它就是那個「唯一的分派點」，這是完全正常且良好的設計。 Smell 是同一組判斷在多處重複。這個區別非常重要，因為 AI 幾乎總是把「看到 switch」當成 Smell。

值得重構的訊號：

• 同一組 case 在 ≥ 3 處出現
• 新增型別時曾經漏改
• 每個 case 的內容 ≥ 10 行

不要重構的訊號：

• 只出現在一處
• case 內容都是一行（例如單純的字串對應）
• 型別集合是封閉且穩定的（例如「借、貸」兩種，十年不會變）

Java 25 的重要變化：

// Java 25：sealed interface + pattern matching switch
// 編譯器會檢查是否涵蓋所有情況 — 漏掉一種就編譯失敗
public sealed interface Product permits Loan, Deposit, Fx {}

BigDecimal fee = switch (product) {
    case Loan l    -> l.principal().multiply(LOAN_RATE);
    case Deposit d -> d.balance().multiply(DEPOSIT_RATE);
    case Fx f      -> f.amount().multiply(f.spread());
};
// 新增一種 Product 時，所有 switch 都會編譯失敗 → 不可能漏改

🔧 本手冊的工程建議 在 Java 21 以上的專案裡，sealed + pattern matching switch 常常是比 Strategy 更好的答案：

	Strategy	sealed + switch
新增型別時漏改的可能	有（忘記註冊）	零（編譯失敗）
新增「操作」（例如新增一種計算）	要改所有實作類別	只要新增一個 switch
型別集合是否需要開放擴充	開放	封閉
檔案數	N+1	1

選擇準則：型別集合封閉 → sealed switch；型別需要由外部（其他模組、plugin）擴充 → Strategy。 這是本手冊與 2004 年原書最重要的一處時代差異。

候選低階重構：Replace Type Code with Class（第 14.4 節）→ Replace Conditional with Polymorphism → 或改用 sealed 型別

可能演進出的 Pattern：Strategy、State、Command；或不需要 Pattern（用 sealed）

AI 如何識別與處理：

必須在 Prompt 中明確告知 Java 版本與偏好：

"本專案為 Java 25。處理型別分派時：
 - 若型別集合封閉，優先使用 sealed interface + pattern matching switch
 - 只有在型別需要被外部模組擴充時，才考慮 Strategy
 - 請先回答：這組型別是封閉的還是開放的？依據是什麼？"

驗證方式：

• 所有原本的 case（包含 default 的行為）都被涵蓋
• default 分支原本若是丟例外，重構後行為一致
• 新增一種型別時，確認會編譯失敗或有測試會失敗（主動驗證這一點）

8.3 Combinatorial Explosion

症狀：大量程式碼在處理「不同組合」的情況，而這些組合是幾個獨立維度的乘積。

// Before：8 個方法 = 2 × 2 × 2
findByCustomer(id)
findByCustomerAndDate(id, date)
findByCustomerAndDateAndStatus(id, date, status)
findByCustomerAndStatus(id, status)
findByDate(date)
findByDateAndStatus(date, status)
findByStatus(status)
findAll()

或是：

// 或這種形式
if (isVip && isOverseas && isUrgent)       { ... }
else if (isVip && isOverseas && !isUrgent) { ... }
else if (isVip && !isOverseas && isUrgent) { ... }
// ... 8 個分支

根因：幾個獨立的變化維度被展開成了笛卡兒積，而不是被組合。

風險：新增一個維度，程式碼量加倍；維度之間的交互規則難以維護；測試組合爆炸。

值得重構的訊號：

• 方法名稱或分支呈現明顯的組合規律
• 新增一個「條件」需要新增多個方法或分支
• 分支數 = 2ⁿ 或 m × n 的形式

不要重構的訊號：

• 組合數少（≤ 4）且穩定
• 各組合的處理邏輯完全不同（代表它們其實不是同一組維度的組合）

候選低階重構：Extract Method → 找出獨立維度 → 把每個維度變成可組合的物件

可能演進出的 Pattern：

• Decorator（第 12.3 節）——當維度是「附加行為」時
• Interpreter / Specification（第 15.5 節）——當維度是「查詢條件」時
• Builder（第 11.5 節）——當維度是「建構選項」時

Before / After（查詢條件的情況）：

// After：Java 25 — 用可組合的 Specification 取代組合爆炸
public interface OrderSpec {
    Predicate toPredicate(Root<Order> root, CriteriaBuilder cb);

    default OrderSpec and(OrderSpec other) {
        return (root, cb) -> cb.and(this.toPredicate(root, cb), other.toPredicate(root, cb));
    }
}

// 8 個方法 → 3 個可組合的條件
OrderSpec byCustomer(String id) { return (r, cb) -> cb.equal(r.get("customerId"), id); }
OrderSpec byDate(LocalDate d)   { return (r, cb) -> cb.equal(r.get("orderDate"), d); }
OrderSpec byStatus(Status s)    { return (r, cb) -> cb.equal(r.get("status"), s); }

// 呼叫端自由組合
repository.findAll(byCustomer(id).and(byDate(today)).and(byStatus(ACTIVE)));

代價的誠實說明：

⚠️ 不要在只有 4 個組合時做這件事。 8 個方法雖然囉唆，但比一套組合機制好懂。

AI 如何識別與處理：

✅ AI 擅長：識別命名上的組合規律
❌ AI 的高風險行為：一看到組合就導入 Specification / Decorator 框架

要求 AI 先回答：
 "目前有幾個獨立維度？每個維度有幾種值？
  未來一年預計會新增幾個維度？（若不知道，請說不知道，不要猜）"

驗證方式：

• 所有原本的組合都能產生完全相同的結果（逐一測試 2ⁿ 種組合）
• SQL 產生的語句與原本等價（可比對 spring.jpa.show-sql 的輸出）
• 效能沒有退化（動態組合的查詢可能無法使用原本的索引）

8.4 Oddball Solution

症狀：同一個問題，在系統的不同地方用了不同的解法。

日期格式化：
  ModuleA 用 SimpleDateFormat
  ModuleB 用 DateTimeFormatter
  ModuleC 用自己寫的 DateUtil
  ModuleD 用 Apache Commons 的 DateFormatUtils

📖 這也是 Kerievsky 特別列出的 Smell。

根因：缺乏團隊共識；不同時期、不同人各自解決；沒有共用元件或沒人知道它存在。

風險：行為不一致（尤其在邊界情況，例如時區、閏年、跨日）；維護時需要理解多套做法；修 bug 時只修了其中一套。

值得重構的訊號：

• 不同解法產生了不一致的結果（🔴 阻斷級）
• 新人不知道該用哪一套
• 其中某些解法已經過時或有已知缺陷（例如 SimpleDateFormat 非執行緒安全）

不要重構的訊號：

• 不同解法各自有合理的理由（例如效能敏感處用了特殊做法）
• 統一的成本 > 不一致的成本

候選低階重構：Substitute Algorithm（把各處換成統一解法）→ Extract Class（建立共用元件）

可能演進出的 Pattern：Strategy（若確實需要多種解法並存）；多數情況下只需要統一，不需要 Pattern

AI 如何識別與處理：

✅ 極適合 AI 的任務：

"請掃描整個專案，找出所有進行『日期格式化』的程式碼，
 列出各自使用的方式、所在檔案，以及它們在以下情境的行為差異：
 - 跨時區
 - 閏年 2/29
 - 月底日期加一個月
 不要修改任何程式碼。"

AI 在「找出所有相似目的的不同實作」這件事上非常強。

驗證方式：

• 統一後，逐一驗證邊界情況的行為與各原始實作一致（或明確記錄哪些行為被刻意改變了）
• 執行緒安全性未退化
• 效能未退化

8.5 Alternative Classes with Different Interfaces

症狀：兩個類別做的事情很像，但方法名稱、參數或回傳型別不同，無法互換使用。

// 兩者都是「寄送通知」，但介面完全不同
class EmailSender {
    public boolean send(String to, String subject, String body) { }
}
class SmsGateway {
    public SendResult dispatch(SmsRequest req) { }
}

根因：分別在不同時期由不同人開發；或分別包裝了不同的第三方 SDK。

風險：呼叫端必須為每一種寫不同的程式碼；無法統一處理（例如統一的重試、記錄、監控）。

值得重構的訊號：

• 呼叫端出現 if (type == EMAIL) {...} else if (type == SMS) {...} 這種分派
• 需要對兩者做同樣的橫切處理（重試、稽核記錄）
• 要新增第三種通道

不要重構的訊號：

• 兩者雖然「概念相似」，但語意差異大（例如 Email 可以很長、SMS 有 70 字限制且計費，硬統一會隱藏重要差異）
• 只有一個呼叫端，而且不會增加

候選低階重構：Rename Method → Add Parameter / Remove Parameter → Move Method → Extract Superclass 或 Extract Interface

可能演進出的 Pattern：Adapter（第 16.2、16.3 節，當你無法修改其中一方時）、Strategy

關鍵判斷：

兩個類別都是你可以修改的        → Unify Interfaces（第 16.1 節），直接改成一致
其中一個是第三方或不可修改      → Extract Adapter（第 16.3 節）
兩者語意差異大，不該統一        → 不要重構，保持各自的介面

AI 如何識別與處理：

⚠️ AI 傾向於「統一」— 因為統一看起來比較整齊

要求 AI 先列出兩者的「語意差異」：
 "請列出 EmailSender 與 SmsGateway 在以下面向的差異：
  失敗語意、重試語意、長度限制、計費、送達確認、非同步性。
  然後回答：統一介面是否會隱藏其中任何一項重要差異？"

驗證方式：

• 統一後的介面沒有隱藏重要的行為差異
• 錯誤處理語意一致（或明確地分開處理）
• 沒有為了統一而產生「只有某些實作才支援」的方法（那是 Refused Bequest）

8.6 Indecent Exposure

症狀：類別把不該公開的內部細節公開了出去——public 的欄位、public 的內部輔助類別、回傳可變的內部集合。

// Before — 三個問題
public class Order {
    public List<OrderLine> lines = new ArrayList<>();   // ① public 欄位
    public BigDecimal internalTaxBase;                   // ② 內部計算的中間值也公開了

    public List<OrderLine> getLines() {
        return lines;                                     // ③ 回傳可變集合，外部可以直接改
    }
}

📖 Kerievsky 列出的 Smell。它同時也是封裝原則的直接違反。

根因：為了方便；或是被 IDE 的「自動產生 getter/setter」帶著走。

風險：

• 外部程式碼直接修改內部狀態，繞過所有驗證
• 內部結構無法改變（因為外部已經依賴它）
• 這是最難事後補救的 Smell之一（呼叫端越多越難改）

值得重構的訊號：

• 有外部程式碼直接修改該欄位或集合
• 內部結構想改但不敢改
• 曾經因為「某處繞過驗證直接改資料」而出過 bug

不要重構的訊號：

• 是 DTO 或 Entity，且團隊明確採用貧血模型
• 是框架要求（例如某些序列化需要 public 欄位）

候選低階重構：Encapsulate Field → Encapsulate Collection → Hide Method → Move Method（把操作搬進來）

可能演進出的 Pattern：通常不需要；有時會演進為 Facade（收斂對外介面）

After 範例：

// After：Java 25
public class Order {
    private final List<OrderLine> lines = new ArrayList<>();
    private BigDecimal internalTaxBase;          // 不對外公開

    public List<OrderLine> lines() {
        return List.copyOf(lines);               // 回傳不可變副本
    }

    public void addLine(OrderLine line) {        // 唯一的修改入口，可以驗證
        Objects.requireNonNull(line);
        if (lines.size() >= MAX_LINES) {
            throw new TooManyOrderLinesException(MAX_LINES);
        }
        lines.add(line);
        recalculateTaxBase();                    // 確保內部一致性
    }
}

⚠️ List.copyOf() 是行為變更，不是純重構 原本外部拿到的 list 可以修改（而且那個修改會反映到 Order 內部）。改成不可變副本之後，原本依賴這個行為的程式碼會拋 UnsupportedOperationException。 這必須先用 Find Usages 找出所有呼叫端，逐一確認。這是一次行為變更，需要完整的回歸測試。

驗證方式：

• 所有呼叫端已確認，沒有依賴「修改回傳集合」的行為
• 序列化行為未變（Jackson 對 List.copyOf 的處理）
• 效能未受影響（每次呼叫都複製，在高頻路徑上要注意）

8.7 Temporary Field

症狀：某個欄位只在特定情況下才有值，其他時候是 null 或預設值。

public class ReportGenerator {
    private List<Row> rows;           // 只在 generate() 執行期間有值
    private BigDecimal runningTotal;  // 同上
    private int pageCount;            // 同上

    public Report generate(Query q) {
        rows = fetch(q);
        runningTotal = BigDecimal.ZERO;
        pageCount = 0;
        // ... 一連串方法互相透過這些欄位傳遞資料
        return buildReport();
    }
}

根因：為了避免在多個私有方法之間傳遞參數，把它們提升成了欄位。

風險：

• 執行緒安全問題（若該物件是 Spring 的 singleton bean，這段程式碼在並行下會出錯）
• 物件狀態難以理解（什麼時候有值？）
• 無法單獨測試那些私有方法

🔴 在 Spring 環境中，這個 Smell 常常是阻斷級的 @Service 預設是 singleton。上面那段程式碼在兩個請求同時進來時，runningTotal 會互相污染。 這類 bug 在測試環境幾乎測不出來，只在生產環境的尖峰時段偶發。

值得重構的訊號：

• 該類別是 Spring bean 或其他共享實例（🔴 立即處理）
• 欄位只在一個 public 方法的執行期間有意義
• 有多個這樣的欄位互相配合

不要重構的訊號：

• 該物件確實是每次使用都 new 的短生命週期物件，且非共享

候選低階重構：Replace Method with Method Object（把整個運算變成一個獨立物件）→ Introduce Parameter Object → Move Accumulation to Collecting Parameter（第 15.3 節）

可能演進出的 Pattern：Collecting Parameter、Builder

After 範例：

// After：把運算過程封裝成獨立的、每次新建的物件
@Service
public class ReportGenerator {                 // singleton，但現在無狀態
    public Report generate(Query q) {
        return new ReportBuilding(fetch(q)).build();   // 每次新建，執行緒安全
    }

    private record ReportBuilding(List<Row> rows) {    // 或用一般 class
        Report build() {
            var total = rows.stream()
                            .map(Row::amount)
                            .reduce(BigDecimal.ZERO, BigDecimal::add);
            // ...
        }
    }
}

驗證方式：

• 並行測試：同時發起多個請求，確認結果互不影響（這是本 Smell 最重要的驗證）
• 該 Spring bean 現在是無狀態的
• 效能未退化（每次新建物件的成本通常可忽略，但高頻路徑要實測）

8.8 Message Chains

症狀：一長串的方法呼叫鏈。

String city = order.getCustomer().getAddress().getCity().getName();

根因：呼叫端需要深層的資料，但沒有人提供一個直接的存取方式。

風險：

• 呼叫端與整條鏈上的所有型別耦合（其中任何一個改變都要修改這裡）
• 任何一環是 null 就會 NPE
• JPA 環境下可能觸發多次 lazy loading（效能陷阱）

值得重構的訊號：

• 同樣的鏈在多處出現
• 鏈長 ≥ 3
• 曾經因為鏈上的 null 而出過 NPE

不要重構的訊號：

• 是流暢介面（Fluent API），例如 StringBuilder.append().append() 或 Stream 鏈——那不是 Message Chain
• 鏈長為 2 且只出現一次

候選低階重構：Hide Delegate（在 Order 上提供 getCustomerCity()）→ Extract Method → Move Method

可能演進出的 Pattern：通常不需要；過度使用 Hide Delegate 會產生 Middle Man（第 8.9 節）

⚠️ 這個 Smell 有一個對立的 Smell 消除 Message Chains 的手法是 Hide Delegate（增加轉發方法）。 做過頭之後，就會產生 Middle Man（一堆什麼都不做、只負責轉發的方法）。 這兩個 Smell 是一組天平的兩端，實務上要在中間找平衡點，而不是把其中一個消滅到零。

驗證方式：

• JPA 查詢次數未增加（用 spring.jpa.properties.hibernate.generate_statistics=true 檢查）
• null 處理行為一致
• 沒有為了隱藏委派而在中介類別塞入大量轉發方法

8.9 Middle Man

症狀：一個類別的大部分方法，都只是把工作轉發給另一個物件。

public class OrderService {
    private final OrderRepository repo;

    public Order find(Long id)      { return repo.find(id); }
    public void save(Order o)       { repo.save(o); }
    public void delete(Long id)     { repo.delete(id); }
    public List<Order> findAll()    { return repo.findAll(); }
    // ... 15 個方法，全都是一行轉發
}

根因：

• 為了「符合分層架構」而建立的空殼層
• 過度使用 Hide Delegate
• 「每個 Repository 都要有對應的 Service」這類團隊慣例

風險：增加了一層卻沒有增加任何價值；修改時要改兩個地方；讀程式碼時多跳一層。

值得重構的訊號：

• ≥ 70% 的方法是單純轉發（無任何邏輯）
• 這一層從未擋下或改變過任何東西

不要重構的訊號：

• 這一層是架構邊界（例如 Hexagonal 的 port），即使目前是純轉發，它的存在是為了隔離
• 這一層有橫切關注點（@Transactional、@PreAuthorize、稽核記錄）——即使方法體只有一行，annotation 也是實質內容

⚠️ 這是 AI 最容易誤判的 Smell AI 看到「方法體只有一行轉發」就會建議 Inline。但如果那個方法上有 @Transactional，inline 掉它會破壞交易邊界——這是第 24 章「AI Ignoring Transaction Boundary」反模式。

候選低階重構：Remove Middle Man（讓呼叫端直接使用被委派者）→ Inline Class

可能演進出的 Pattern：移除通常是往 Away From Patterns 的方向（第 18 章）

驗證方式：

• 確認沒有 annotation 被移除（@Transactional、@Cacheable、@PreAuthorize、@Retryable）
• 確認沒有違反架構分層規則（用 ArchUnit 驗證，第 39 章）
• 交易邊界未改變（可用交易測試驗證：故意丟例外，確認 rollback 範圍一致）

8.10 Lazy Class

症狀：一個類別做的事太少，不足以justify它的存在。

根因：

• 重構過程中留下的殘骸（原本的職責被搬走了）
• 為了「未來擴充」而預先建立
• 過度拆分的結果

風險：增加檔案數與認知負荷，但沒有對應收益。

值得重構的訊號：

• 只有一個方法，且只被一處呼叫
• 沒有欄位，或只有一個欄位
• 名稱中有 Helper、Util、Manager 且內容單薄

不要重構的訊號：

• 它是一個有意義的領域概念，即使目前很小（例如 Money、AccountNumber）
• 它是架構邊界的一部分
• 它是策略的其中一個實作（即使很短）

候選低階重構：Inline Class → Collapse Hierarchy（若是只有一個子類別的繼承）

可能演進出的 Pattern：移除（第 18 章）

⚠️ 不要用行數判斷 Lazy Class public record Money(BigDecimal amount, Currency currency) {} 只有一行，但它是極有價值的類別。 判斷準則是「它是否代表一個獨立的概念」，不是「它有幾行」。

驗證方式：

• Inline 之後，沒有讓接收的類別變成 Large Class
• 沒有刪除掉實際上被外部模組使用的類別

8.11 Speculative Generality

症狀：為了「未來可能的需求」而建立的、目前沒有用到的彈性機制。

典型表現：

根因：

• 「以後一定會用到」
• 想展現設計能力
• AI 產生的程式碼（🔴 這是目前最大的來源）

風險：

• 付出了所有的代價（間接層、類別數、認知負荷），卻沒有得到任何收益
• 而且它猜錯方向的機率很高（回顧第 3.5 節的案例）
• 未來真的要擴充時，往往發現當初的抽象不符合實際需求，還要先拆掉

值得重構的訊號（即：值得移除）：

• 介面只有一個實作，且超過一年沒有新增
• 抽象類別沒有子類別
• 參數永遠傳同一個值
• 設定項從未被改過

不要移除的訊號：

• 介面是為了測試替身而存在（但先確認測試是否真的用到了）
• 介面是架構邊界（Hexagonal 的 port，即使只有一個 adapter）
• 是對外發布的 API（移除會破壞相容性）

候選低階重構：Inline Class → Collapse Hierarchy → Remove Parameter → Inline Method

可能演進出的 Pattern：這是純粹的 Away From Patterns（第 18 章）

取得證據的方式：

# 找出只有一個實作的介面（粗略版，需人工複核）
for i in $(grep -rl "^public interface" src/main/java --include="*.java"); do
  name=$(basename "$i" .java)
  count=$(grep -rl "implements .*\b$name\b" src/main/java --include="*.java" | wc -l)
  if [ "$count" -le 1 ]; then echo "$count  $name  ($i)"; fi
done | sort -n

AI 如何識別與處理：

🔴 最重要的一段

AI 是 Speculative Generality 的主要製造者。它的訓練資料大量來自
開源框架 — 而框架「本來就該」高度抽象，因為使用者是未知的。
你的內部系統不是框架。

必須寫進 CLAUDE.md / copilot-instructions.md 的規則（見附錄 B）：

  - 不得為單一實作建立介面
  - 不得建立沒有子類別的抽象類別
  - 不得新增目前沒有使用情境的設定項
  - 不得為「未來可能的需求」預留擴充點
  - 若認為某處需要擴充點，必須先說明「現在有哪個已知需求需要它」

驗證方式：

• 移除後編譯通過、測試全綠
• 確認沒有外部模組依賴被移除的介面
• 確認測試沒有依賴該介面做 mock（若有，評估是否改用真實物件）

8.12 本章實務案例

情境：某證券公司委託一個外包團隊開發「智能下單」模組，六個月後接手。

接手時的統計：

診斷：這是一個典型的 Speculative Generality 重災區。312 個檔案在承載約 4,800 行的實際邏輯。

接手團隊的處理方式：

Step 1：先確認哪些抽象是有價值的（不是全部刪掉）

71 個單一實作的介面，逐一分類：

  ✅ 保留 12 個 — 是 Hexagonal 架構的 port（對外部系統的邊界）
  ✅ 保留  6 個 — 測試中確實用到 mock，且該依賴難以在測試中建立
  ❌ 移除 53 個 — 沒有任何價值

Step 2：建立安全網

在移除任何東西之前，先針對「智能下單」的 5 條主要流程建立端對端的 Characterization Test。

Step 3：分批移除（每批一個 PR）

結果：

最後一列值得注意：業務邏輯行數幾乎不變，證明這次大規模的移除完全沒有改變功能——移除的都是純粹的包裝。

一個沒有預期到的收穫：移除過程中發現了 3 個 bug。因為原本的抽象層太多，某些條件判斷被分散在介面的預設方法、抽象類別的樣板方法、與實作類別中，合併之後才看出邏輯互相矛盾。

8.13 本章注意事項

⚠️ 8.1～8.3 是 AI 的高風險區 Conditional Complexity、Switch Statements、Combinatorial Explosion——這三個 Smell，AI 幾乎必然會建議套用 Pattern。 請務必在 Prompt 中限制步驟（見各節的「AI 如何識別與處理」），並要求它做完一步就停下來。

⚠️ Message Chains 與 Middle Man 是一組天平 不要試圖把兩者都消滅到零——消除其中一個會增加另一個。實務上要找的是平衡點。

⚠️ Middle Man 的 annotation 是實質內容 移除「只有一行轉發」的方法前，務必確認方法上沒有 @Transactional、@Cacheable、@PreAuthorize、@Retryable、@Async。這些 annotation 才是那個方法存在的理由。

⚠️ Temporary Field 在 Spring 環境是執行緒安全問題 這不只是設計問題，是生產環境的並行 bug。發現 @Service 類別有可變欄位時，應列為 🔴 阻斷級。

✅ Speculative Generality 的移除，必須從「分類」開始 不要一律刪除。先分出「架構邊界」「測試需要」「純粹多餘」三類，只刪第三類。

📌 接下來 第 9 章會把這 21 個 Smell 整理成一張對應表，並且會非常嚴肅地說明那張表不該怎麼用。

第 9 章 Smell 到 Refactoring 到 Pattern 的對應

9.1 這張表怎麼用，以及怎麼被誤用

在給出對應表之前，必須先講清楚它的性質。

⚠️ 這張表是「候選方向」，不是「自動轉換規則」。

為什麼特別要強調這件事：

這張表的形式（A → B → C）天然帶有「流程」的暗示。人類讀者會自動補上「所以要走完」的語意，AI 更是如此。

實際上，正確的讀法是：

Code Smell      = 症狀（你觀察到的）
Refactoring     = 藥方（多半只需要吃前一兩帖）
Pattern         = 如果症狀持續，而且是某種特定體質，可能需要的手術
警告            = 這個手術什麼情況下不該做

多數情況下，你只需要「候選重構」那一欄。

9.2 完整對應總表

統計一下這張表告訴我們什麼：

🔧 這就是本手冊最想傳達的比例感 在真實專案中，「需要導入 Design Pattern」的情況，遠比 Pattern 教材給人的印象少得多。 絕大多數的設計改善，止於 Extract Method、Extract Class、Move Method。

9.3 反向查表：從 Pattern 回推該有的 Smell

這張表是給 Code Review 用的。當有人（或 AI）提議導入某個 Pattern 時，用它來檢查前提。

🔧 使用方式：提案者必須能指出「必要證據」欄位的具體事實。指不出來 → 退回。

9.4 AI Agent 使用這張表的限制

🤖 這一節是給團隊制定 AI 規範時使用的。

如果你直接把 9.2 節的表貼給 AI，會發生什麼：

實測觀察（🏭 業界普遍現象）：AI 會忽略「候選低階 Refactoring」欄位與「警告」欄位，直接跳到「可能的 Pattern」欄位。

原因有三：

1. Pattern 欄位的內容最具體（有明確的名字與結構）
2. 產生 Pattern 的程式碼在訓練資料中最常見
3. 「做得更多」在多數 RLHF 訓練中被視為更有幫助

正確的使用方式：

❌ 錯誤：
"這裡有 Conditional Complexity，請參考下表重構：[貼整張表]"

✅ 正確：
"這裡有 Conditional Complexity。
 請**只執行** Decompose Conditional：把複雜的布林條件抽成具名的私有方法。
 不要建立任何新的類別或介面。
 不要改變條件的判斷順序。
 完成後停下來，執行測試，並回報：
 （a）圈複雜度的變化
 （b）你認為痛點是否已經解決
 （c）如果沒有，下一步你建議什麼，以及為什麼"

關鍵差異：

🤖 把這個模式寫進團隊規範 附錄 A 的 20 組 Prompt 全部採用這個結構（Role / Context / Objective / Constraints / Steps / Expected Output / Verification / Stop Conditions）。 其中 Stop Conditions 是最常被遺漏、也最重要的一段。

9.5 本章實務案例

情境：某團隊導入 Claude Code 協助重構，第一個月的實測記錄。

他們設計了一個對照實驗：同一份程式碼（一個 480 行、有 6 層巢狀 if 的 LoanApprovalService），分別用三種 Prompt 方式處理。

方式 A：開放式指令

Prompt: "請重構 LoanApprovalService，改善它的可讀性與可維護性。"

結果：

方式 B：貼上第 9.2 節的完整對應表

Prompt: "這裡有 Conditional Complexity。請參考以下對應表進行重構：[整張表]"

結果：

方式 C：限定單一步驟 + 明確的停止條件

Prompt:
"角色：資深 Java 工程師，正在對 Legacy 程式碼進行安全重構。

 背景：LoanApprovalService.approve() 有 480 行、6 層巢狀 if。
 本專案為 Java 25 + Spring Boot 4.1.x。
 已有 Characterization Test 共 340 筆（LoanApprovalCharacterizationTest）。

 目標：只執行 Decompose Conditional。

 限制（硬性）：
 - 不得新增任何 class、interface、enum、record
 - 不得改變任何條件的判斷順序（短路求值必須完全一致）
 - 不得修改測試檔案
 - 不得修改方法簽章
 - 每抽出一個條件方法，就執行一次測試

 步驟：
 1. 列出所有複雜的布林條件式（含所在行號）
 2. 為每一個提出具業務意義的方法名稱，等我確認
 3. 我確認後，一次抽出一個，每次執行 mvn test -Dtest=LoanApprovalCharacterizationTest

 預期輸出：
 - 步驟 1、2 只輸出分析，不修改程式碼
 - 步驟 3 每次只提供一個方法的 diff

 停止條件：
 - 任何測試失敗 → 立即停止並回報
 - 若你發現某個條件的業務意義不明確 → 停止並詢問，不要猜測
 - 完成所有抽取後停止，不要繼續進行其他重構"

結果：

AI 提出的那 3 個疑問中，最有價值的一個：

"第 219 行的條件是：
   if (applicant.getAge() >= 20 && applicant.getAge() < 65
       && !(applicant.getAge() == 64 && applicant.getMonth() > 6))

 前兩個條件我可以命名為 isWorkingAgeApplicant()，
 但第三個條件（64 歲且月份 > 6 時排除）我無法從程式碼推斷其業務意義。

 這可能是：
 (a) 某個法規的特殊規定
 (b) 一個 bug
 (c) 已經失效的舊規則

 請提供業務意義後我再命名。我不會自行猜測命名。"

團隊查證後發現：這是 2016 年某次法規調整留下的過渡條款，該條款已於 2019 年失效，但程式碼沒有移除。

這個發現的價值，遠超過這次重構本身。

三種方式的總結：

🔧 這個實驗最重要的結論 限制 AI 的範圍，不會降低它的價值，反而會提高。 方式 C 產出最少的程式碼，但它是唯一通過 Review 的，而且是唯一發現既有問題的。 原因是：當 AI 不被允許「用新增抽象來解決問題」時，它只能真正去理解那段程式碼。

9.6 本章注意事項

⚠️ 不要把 9.2 節的表當成 checklist 去「清完」 這張表是查詢用的字典，不是待辦清單。

⚠️ 不要在 Code Review 用「表上寫了 X，你為什麼沒做」來質疑 正確的問法是：「你停在這裡的理由是什麼？」

⚠️ 9.3 節的反向表是 Review 工具，請實際使用它 當 PR 中出現新的介面或抽象類別時，要求提案者填寫「必要證據」欄位。這一個動作能擋掉大部分的過度設計。

✅ Prompt 的品質決定產出的品質 第 9.5 節的實驗顯示，同一個 AI、同一份程式碼，Prompt 的差異造成了 8 倍的 diff 大小差異與完全相反的 Review 結果。 Prompt 工程不是「話術」，是工程規範的一部分。

✅ 鼓勵 AI 說「我不知道」 方式 C 的 Prompt 中，「若業務意義不明確 → 停止並詢問，不要猜測」這一句，是整段最有價值的限制。 預設情況下 AI 不會說不知道——它會給出一個聽起來合理的解釋。你必須明確授權它停下來。

📌 本部結束 你現在有了 21 個 Smell 的詞彙、一套判讀方法論、以及一張（要小心使用的）對應表。 第三部開始，會逐一展開 Kerievsky 官方 catalog 的 27 個 pattern-directed refactorings——每一個都附帶「什麼時候不要用」。

第三部：Pattern-directed Refactoring Catalog

這一部是本手冊的參考核心：Kerievsky 官方 catalog 的 27 個 pattern-directed refactorings，逐一展開。

在開始之前，請先接受一個心理準備：

這 27 個條目中，你的專案這輩子可能只會用到 6～8 個。 而且其中至少 3 個是「把東西拆掉」的方向。

這不是誇張。第 9.2 節的統計已經說明，絕大多數的設計改善止於 Extract Method 與 Extract Class。這一部的價值不在於「全部學會」，而在於當你真的遇到那 6～8 個情境時，有一份可靠的步驟說明與停損點。

第 10 章 Catalog 總覽

10.1 官方 27 項清單

以下清單依 Industrial Logic 公開的 Refactoring to Patterns catalog 頁面查證，共 27 項，此處依原頁面的字母順序列出：

來源：Industrial Logic, Refactoring to Patterns Catalog（現行頁） https://www.industriallogic.com/xp/refactoring/catalog.html 每一項的官方條目 URL 與命名沿革，完整列於 附錄 H。 查證日期：2026-09-16

⚠️ Industrial Logic 同時存在兩份 catalog 頁面 除了上述現行頁，網站上還保留著一份出版前的舊頁（https://www.industriallogic.com/papers/catalog.html，頁面上寫的是「forthcoming book… to be published by Addison Wesley mid 2004」）。 兩份都是 27 項、且條目一一對應，但有三個條目的名稱不同。這是業界清單混亂的真正根源，詳見 10.3 節。

10.2 本手冊的分組方式

⚠️ 重要聲明 Industrial Logic 公開的 catalog 網頁只提供扁平的 27 項清單，沒有提供分組；但原書本身是有章節分組的（第 1～4 章為理論、第 5 章為 catalog 導讀，其後依主題分章展開 27 個條目）。 本手冊未能從公開來源取得原書 catalog 各分章的完整章名（O’Reilly 目次頁僅公開到第 5 章），因此下表六個分組仍屬 本手冊為了教學便利而自行整理，不等於原書章節結構。 若你需要引用原書的章節結構，請直接查閱原書，不要引用本手冊的分組當作原書結構。

分組的完整對應：

flowchart TD
    C["Creation 7 項<br/>第 11 章"]
    S1["Simplification 上 3 項<br/>第 12 章"]
    S2["Simplification 下 3 項<br/>第 13 章"]
    G["Generalization 4 項<br/>第 14 章"]
    P["Protection 與 Accumulation 5 項<br/>第 15 章"]
    B["Boundary 與 Utilities 5 項<br/>第 16 章"]

    C --> C1["Replace Constructors with Creation Methods<br/>Move Creation Knowledge to Factory<br/>Encapsulate Classes with Factory<br/>Introduce Polymorphic Creation with Factory Method<br/>Encapsulate Composite with Builder<br/>Inline Singleton<br/>Limit Instantiation with Singleton"]
    S1 --> S1a["Compose Method<br/>Replace Conditional Logic with Strategy<br/>Move Embellishment to Decorator"]
    S2 --> S2a["Replace State-Altering Conditionals with State<br/>Replace Conditional Dispatcher with Command<br/>Replace Implicit Tree with Composite"]
    G --> G1["Form Template Method<br/>Extract Composite<br/>Replace One-Many Distinctions with Composite<br/>Replace Type Code with Class"]
    P --> P1["Introduce Null Object<br/>Replace Hard-Coded Notifications with Observer<br/>Move Accumulation to Collecting Parameter<br/>Move Accumulation to Visitor<br/>Replace Implicit Language with Interpreter"]
    B --> B1["Unify Interfaces<br/>Unify Interfaces with Adapter<br/>Extract Adapter<br/>Chain Constructors<br/>Extract Parameter"]

    style C fill:#cfe2ff,stroke:#0d6efd
    style S1 fill:#d1e7dd,stroke:#198754
    style S2 fill:#d1e7dd,stroke:#198754
    style G fill:#fff3cd,stroke:#ffc107
    style P fill:#f8d7da,stroke:#dc3545
    style B fill:#e2d9f3,stroke:#6f42c1

10.3 與常見清單的差異對照

網路上與各種教材中流傳的「Refactoring to Patterns 清單」，經常與現行官方 catalog 不完全一致。其中大多數差異並不是錯誤，而是命名沿革。本節把三種性質完全不同的情況分開列出，避免讀者在交叉比對時把「舊名」誤判為「幻覺」。

情況一：同一條目的出版前舊名

Industrial Logic 網站上的出版前舊 catalog 頁（papers/catalog.html）與現行頁（xp/refactoring/catalog.html）都是 27 項，但有三個條目換過名字。兩頁的條目連結使用完全相同的 URL slug，這就是「它們是同一條目」的直接證據：

🏭 這件事為什麼重要 許多企業內部文件（甚至部分 AI 生成的整理）會把 Consolidate Creation with Factory 或 Pull Up Common Interface 直接判定為「書上沒有、可能是幻覺」。 這個判定是錯的。 它們是 Industrial Logic 在 2004 年書籍出版前使用的官方名稱，舊頁至今仍可存取。正確的說法是「這是舊名，現行名稱是……」，而不是「沒有這個條目」。

情況二：官方有、但常見清單經常遺漏的兩項

情況三：真的不屬於本書的條目

下表這些名稱常被混入 Refactoring to Patterns 清單，但它們實際來自 Fowler《Refactoring》，屬於低階重構，不是 pattern-directed refactoring：

🔧 本手冊的工程建議 名稱混淆在企業內部文件中非常常見，而且會造成實際問題：當 A 工程師說「我們做一下 Consolidate Creation with Factory」，B 工程師去查新版書卻查不到，溝通就斷了。 建議三點：

1. 正式文件（ADR、PR 描述、Commit message）一律使用現行 27 個英文名稱。
2. 舊名不是錯誤，但只當口語說法；若必須寫入文件，請以「現行名（舊名）」格式標註。
3. 收到 AI Agent 產出的名稱時，先查附錄 H 的對照表再判定是否為幻覺，不要直接否定。

10.4 每個條目的閱讀方式

第 11～16 章的每一個條目，都採用以下十段格式：

⚠️ 關於 Before 範例的說明 本手冊的 Before 範例刻意使用 Java 8 + Spring Boot 2.x + javax 的寫法，包含一些現在看來過時的做法（SimpleDateFormat、@Autowired 欄位注入、Date）。 這不是疏忽，是刻意的——因為企業裡實際會遇到的就是這樣的程式碼。用 Java 25 寫「假的爛程式碼」沒有教學價值。

10.5 本章實務案例

情境：某團隊建立內部的「重構手法清單」時遇到的問題。

團隊架構師整理了一份 Wiki 頁面，列出 35 個「重構手法」，來源包括 Fowler 的書、Kerievsky 的書、幾篇部落格文章與 AI 工具的整理。

三個月後發現的問題：

修正做法：

拆成三份文件，各自標明來源：

  文件 A：低階重構手法（來源：Fowler《Refactoring》）
          → 直接連到本 repo 的 分析與設計/Refactoring重構教學.md

  文件 B：Pattern-directed Refactoring（來源：Kerievsky，27 項，附官方 URL）
          → 即本手冊第三部

  文件 C：團隊自訂的慣例做法（明確標示「這是我們自己的，不是書上的」）

成效：

🔧 這個案例的教訓 在 AI 協助整理技術資料的時代，「來源可查證」比「清單完整」更重要。 一份 27 項、每項都能追到官方頁面的清單，價值遠高於一份 35 項、其中 4 項是虛構的清單。

10.6 本章注意事項

⚠️ 不要把本章的分組當成原書結構引用 官方 catalog 頁面沒有提供分組。本手冊的六個分組是教學用的整理，請在引用時註明。

⚠️ Kerievsky 的條目與 Fowler 的條目要分開 兩者的層級不同：Fowler 的是「一步」，Kerievsky 的是「一連串步驟組成的演進」。混在一起會讓團隊低估後者的成本。

✅ 建立團隊的名稱共識 建議在團隊 Wiki 上直接連結本章 10.1 節的表格，並約定「正式文件只使用這 27 個英文名稱」。

✅ 先讀「什麼時候不要用」 這是本手冊建議的閱讀順序。當你在考慮某個重構時，先看它的「不要用」條件，比先看步驟更有效率——因為多數情況下你會在這一段就決定不做。

第 11 章 Creation 類重構

這一章的 7 個條目，全部圍繞同一件事：物件是怎麼被建立出來的。

在進入細節之前，先看一張決策圖。這張圖最重要的訊息是：多數情況下的答案是「不需要任何東西」。

flowchart TD
    A[物件建立遇到問題] --> B{問題是什麼}
    B -->|建構子太多分不清| C["Replace Constructors<br/>with Creation Methods 11.1"]
    B -->|建構子之間有重複| D["Chain Constructors 16.4"]
    B -->|建立邏輯複雜散落多處| E{建立時需要選型嗎}
    B -->|參數太多組合複雜| F["Encapsulate Composite<br/>with Builder 11.5"]
    B -->|有手寫 Singleton 但沒必要| G["Inline Singleton 11.6"]
    B -->|真的需要限制唯一實例| H["Limit Instantiation<br/>with Singleton 11.7"]

    E -->|否，只是組裝| I["Move Creation Knowledge<br/>to Factory 11.2"]
    E -->|是，要依條件選類別| J{呼叫端該知道有哪些實作嗎}
    J -->|不該知道| K["Encapsulate Classes<br/>with Factory 11.3"]
    J -->|選型邏輯依子類別而異| L["Introduce Polymorphic Creation<br/>with Factory Method 11.4"]

    style G fill:#d4edda,stroke:#28a745
    style H fill:#f8d7da,stroke:#dc3545

⚠️ 整章最重要的一句話 把 new 包起來本身不是價值。 一個內容只有 return new Xxx(); 的 Factory，提供的抽象等於零，成本卻是一個額外的檔案加一層間接。 在 Spring 專案中，這件事更嚴重——因為 Spring 的 DI 容器本來就在做物件建立與組裝，自己再寫一層 Factory 通常是重複了框架的職責。

11.1 Replace Constructors with Creation Methods

一句話

把「多個難以分辨的建構子」換成「名稱能說明意圖的靜態工廠方法」。

起點 Smell

• 一個類別有多個建構子，簽章相似到需要看文件才知道差別
• 建構子被迫用「多一個沒用的參數」來區分多載（overload）
• 呼叫端讀起來像 new Loan(commitment, riskRating, maturity, null)，完全看不出意圖

Before

// Before：Java 8 — 三個建構子，呼叫端無法分辨
public class Loan {
    private final BigDecimal commitment;
    private final BigDecimal outstanding;
    private final int riskRating;
    private final Date maturity;
    private final Date expiry;

    // 定期貸款
    public Loan(BigDecimal commitment, int riskRating, Date maturity) {
        this(commitment, BigDecimal.ZERO, riskRating, maturity, null);
    }

    // 循環信用
    public Loan(BigDecimal commitment, int riskRating, Date maturity, Date expiry) {
        this(commitment, BigDecimal.ZERO, riskRating, maturity, expiry);
    }

    // 已動用的循環信用 — 注意：只差在多了 outstanding
    public Loan(BigDecimal commitment, BigDecimal outstanding,
                int riskRating, Date maturity, Date expiry) {
        this.commitment = commitment;
        this.outstanding = outstanding;
        this.riskRating = riskRating;
        this.maturity = maturity;
        this.expiry = expiry;
    }
}

呼叫端：

// 這三行分別建立了什麼？必須去看建構子的實作才知道
Loan a = new Loan(amount, 3, maturityDate);
Loan b = new Loan(amount, 3, maturityDate, expiryDate);
Loan c = new Loan(amount, used, 3, maturityDate, expiryDate);

重構步驟

中間態

走完步驟 2 就已經獲得了大部分價值：呼叫端變得可讀。步驟 3、4 是收尾。

如果這個類別是對外發布的 API（其他團隊或外部系統在用），步驟 3 必須跳過——把建構子改成 private 會破壞相容性。此時保留 public 建構子，只是不再推薦使用即可。

After

// After：Java 25
public final class Loan {
    private final Money commitment;
    private final Money outstanding;
    private final RiskRating riskRating;
    private final LocalDate maturity;
    private final LocalDate expiry;      // 可為 null，代表無到期展期

    private Loan(Money commitment, Money outstanding, RiskRating riskRating,
                 LocalDate maturity, LocalDate expiry) {
        this.commitment = Objects.requireNonNull(commitment);
        this.outstanding = Objects.requireNonNull(outstanding);
        this.riskRating = Objects.requireNonNull(riskRating);
        this.maturity = Objects.requireNonNull(maturity);
        this.expiry = expiry;
    }

    /** 定期貸款：一次撥貸、到期還清，無循環額度。 */
    public static Loan newTermLoan(Money commitment, RiskRating rating, LocalDate maturity) {
        return new Loan(commitment, Money.zero(commitment.currency()), rating, maturity, null);
    }

    /** 循環信用額度：尚未動用。 */
    public static Loan newRevolver(Money commitment, RiskRating rating,
                                   LocalDate maturity, LocalDate expiry) {
        return new Loan(commitment, Money.zero(commitment.currency()), rating, maturity, expiry);
    }

    /** 循環信用額度：已動用部分金額。 */
    public static Loan newDrawnRevolver(Money commitment, Money outstanding,
                                        RiskRating rating, LocalDate maturity, LocalDate expiry) {
        return new Loan(commitment, outstanding, rating, maturity, expiry);
    }
}

呼叫端：

Loan a = Loan.newTermLoan(amount, RiskRating.of(3), maturityDate);
Loan b = Loan.newRevolver(amount, RiskRating.of(3), maturityDate, expiryDate);
Loan c = Loan.newDrawnRevolver(amount, used, RiskRating.of(3), maturityDate, expiryDate);

得到什麼

• 呼叫端一眼可讀，不需要查建構子
• 每種建立方式可以有各自的驗證規則（但請見下方的重要警告）
• 未來可以在方法內加入快取、池化或回傳子類別，而呼叫端不受影響
• 方法名稱成為領域語彙的一部分（newRevolver 是業務詞彙，new Loan(...) 不是）

付出什麼

什麼時候不要用

• 類別只有一個建構子，且參數意圖清楚 → 不需要
• 類別是 JPA Entity（需要無參數建構子）或 DTO（框架要反序列化）→ 需要額外處理，通常不值得
• 類別是對外 API 且不能破壞相容性 → 可以新增具名方法，但不要動原建構子
• 只是為了「看起來比較專業」→ 不要

AI Prompt 與驗證

角色：資深 Java 工程師。

背景：[類別名稱] 有 [N] 個建構子，呼叫端難以分辨用途。
      本專案 Java 25 / Spring Boot 4.1.x。

目標：執行 Replace Constructors with Creation Methods。

限制：
- 不得修改任何建構子的邏輯，只新增 static 方法呼叫它們
- 不得在新方法中加入任何新的驗證或檢查（這是行為變更，我會另外處理）
- 不得把建構子改為 private（這一步我會另外決定）
- 不得修改測試檔案
- 方法名稱必須使用本專案既有的領域語彙（參考 [glossary 檔案路徑]）

步驟：
1. 先列出每個建構子實際代表的業務情境，以及你建議的方法名稱，等我確認
2. 確認後，一次新增一個 static 方法，每次執行測試
3. 列出所有呼叫端，但不要修改它們

停止條件：
- 若某個建構子的業務意圖無法從程式碼判斷，停止並詢問，不要猜測命名
- 若發現該類別是 JPA Entity 或有 Jackson annotation，停止並回報

驗證 checklist：

• 所有既有測試全綠，且測試檔案未被修改
• 若類別參與序列化：JSON 的序列化與反序列化結果完全一致
• 若類別是 JPA Entity：確認無參數建構子仍存在
• 沒有在 Creation Method 中新增任何驗證（見下方警告）
• 方法名稱經過領域專家或 PM 確認

⚠️ 最容易出事的一點 在 Creation Method 中「順手」加上驗證（例如檢查動用金額不得大於額度），是行為變更，不是重構。 原本可以建立的無效物件，現在會丟例外。如果 Legacy 系統中真的存在這種資料（很常見），這會造成生產事故。 正確做法：先分成兩個 PR——第一個純粹重構，第二個才加驗證，並且第二個 PR 要先查詢生產資料確認有多少筆會受影響。

11.2 Move Creation Knowledge to Factory

一句話

把「建立某個物件所需的知識」從散落的呼叫端，集中到一個 Factory 中。

起點 Smell

• 同一組「建立 + 組裝 + 設定預設值」的程式碼，在 3 個以上的地方重複
• 建立一個物件需要知道很多細節（要先查表、要依條件設定欄位、要組裝子物件）
• 建立邏輯改變時，要修改多個地方（Shotgun Surgery）

Before

// Before：Java 8 — 兩個 Service 各自組裝 Notification，邏輯幾乎相同但細節有差
@Service
public class OrderService {
    @Autowired private CustomerDao customerDao;
    @Autowired private TemplateDao templateDao;
    @Autowired private NotificationSender sender;

    public void notifyOrderPlaced(Order order) {
        Notification n = new Notification();
        n.setRecipient(customerDao.findEmail(order.getCustomerId()));
        n.setTemplate(templateDao.find("ORDER_PLACED"));
        n.setLocale(customerDao.findLocale(order.getCustomerId()));
        n.setPriority(order.getAmount().compareTo(BIG) > 0 ? 1 : 5);
        n.setRetryCount(3);
        n.setSendAt(new Date());
        sender.send(n);
    }
}

@Service
public class ShipmentService {
    @Autowired private CustomerDao customerDao;
    @Autowired private TemplateDao templateDao;
    @Autowired private NotificationSender sender;

    public void notifyShipped(Shipment s) {
        Notification n = new Notification();
        n.setRecipient(customerDao.findEmail(s.getCustomerId()));
        n.setTemplate(templateDao.find("SHIPPED"));
        n.setLocale(customerDao.findLocale(s.getCustomerId()));
        n.setPriority(5);
        n.setRetryCount(3);
        // 這裡忘了 setSendAt — 這就是散落建立邏輯的典型後果
        sender.send(n);
    }
}

重構步驟

中間態

步驟 4 之後就可以停下來評估。如果只有兩處呼叫端，而且它們的差異其實很大，那麼把它們硬塞進同一個 Factory 可能不划算。

判斷準則：如果 Factory 的方法需要 2 個以上的 boolean 參數來應付差異，代表這些建立邏輯不該合併。

After

// After：Java 25 + Spring Boot 4.x
@Component
public class NotificationFactory {
    private final CustomerDao customerDao;
    private final TemplateDao templateDao;
    private final Clock clock;                       // 可測試的時間來源

    public NotificationFactory(CustomerDao customerDao, TemplateDao templateDao, Clock clock) {
        this.customerDao = customerDao;
        this.templateDao = templateDao;
        this.clock = clock;
    }

    public Notification forOrderPlaced(Order order) {
        Priority priority = order.amount().isGreaterThan(Money.of(BIG_AMOUNT))
                            ? Priority.HIGH : Priority.NORMAL;
        return baseFor(order.customerId(), TemplateCode.ORDER_PLACED, priority);
    }

    public Notification forShipped(Shipment shipment) {
        return baseFor(shipment.customerId(), TemplateCode.SHIPPED, Priority.NORMAL);
    }

    private Notification baseFor(CustomerId customerId, TemplateCode code, Priority priority) {
        var profile = customerDao.findProfile(customerId);
        return Notification.builder()
                .recipient(profile.email())
                .locale(profile.locale())
                .template(templateDao.find(code))
                .priority(priority)
                .retryCount(DEFAULT_RETRY)
                .sendAt(LocalDateTime.now(clock))      // 不會再有人忘記
                .build();
    }
}

得到什麼

• 建立邏輯只有一份，不會再出現「某處忘了設某個欄位」
• 新增一種通知只需要在 Factory 加一個方法
• Service 不再需要認識 CustomerDao、TemplateDao（依賴減少）
• Factory 可以單獨測試

付出什麼

什麼時候不要用

• 只有 1 至 2 處呼叫端 → 直接抽一個私有方法就好，不需要新類別
• 各處的建立邏輯差異大，合併後需要多個旗標參數 → 不要合併
• Spring 已經在做這件事——如果你要建立的是 Spring bean，用 @Configuration 加 @Bean 即可，不要另外寫 Factory
• 建立邏輯只有 new Xxx() → 這是最常見的誤用，包一層 Factory 毫無價值

AI Prompt 與驗證

角色：資深 Java 工程師。

背景：以下 [N] 個位置都在建立 [類別名稱]，疑似有重複的建立邏輯。
      [列出檔案與行號]

目標：分析是否應該執行 Move Creation Knowledge to Factory。

限制（第一階段只做分析，不得修改程式碼）：
- 不得修改任何檔案

步驟：
1. 逐一比對各處的建立邏輯，做出一張「欄位 × 位置」的設定對照表
2. 標示出有差異的欄位，並分類為：
   (a) 有意的業務差異
   (b) 疑似遺漏或 bug
   (c) 無法判斷
3. 回答：若要合併，Factory 的方法需要幾個參數？其中有幾個是 boolean 旗標？
4. 給出建議：合併 / 不合併 / 先修 bug 再評估

停止條件：
- 步驟 2 中若出現 (b) 或 (c) 類別的欄位，停止，先由人類確認業務規則
- 若步驟 3 的 boolean 旗標達 2 個以上，建議不合併，並說明理由

驗證 checklist：

• 各處的行為與重構前完全一致（包含原本的差異，除非已明確決定統一）
• 若統一了原本不一致的行為，這是行為變更，需獨立 PR 與回歸測試
• Factory 沒有變成一個什麼都做的 God Class
• Factory 的方法簽章中沒有 2 個以上的 boolean 旗標
• 時間、亂數等不確定來源已抽象化（如 Clock），使 Factory 可測試

11.3 Encapsulate Classes with Factory

一句話

把「有哪些實作類別」這件事藏起來，只讓呼叫端看到介面與 Factory。

起點 Smell

• 呼叫端需要 import 一堆具體實作類別
• 呼叫端出現 if (type.equals("A")) return new AProcessor(); else ...
• 想新增一個實作時，發現要修改多個呼叫端

Before

// Before：Java 8 — 呼叫端知道太多
package com.example.report;

public interface ReportGenerator { byte[] generate(ReportRequest req); }
public class PdfReportGenerator implements ReportGenerator { }    // public
public class ExcelReportGenerator implements ReportGenerator { }  // public
public class CsvReportGenerator implements ReportGenerator { }    // public

// 呼叫端
import com.example.report.PdfReportGenerator;
import com.example.report.ExcelReportGenerator;
import com.example.report.CsvReportGenerator;

public byte[] download(String format, ReportRequest req) {
    if ("PDF".equals(format))        return new PdfReportGenerator().generate(req);
    else if ("XLSX".equals(format))  return new ExcelReportGenerator().generate(req);
    else if ("CSV".equals(format))   return new CsvReportGenerator().generate(req);
    else throw new UnsupportedFormatException(format);
}

重構步驟

中間態

步驟 2 之後就有價值了。步驟 3 至 5 是「把門鎖上」，防止未來回退。

如果專案還沒有 ArchUnit，步驟 5 可以省略，但步驟 4 一定要做——package-private 是最便宜的封裝機制。

After

// After：Java 25 + Spring Boot 4.x
package com.example.report;

// 對外只有這兩個是 public
public interface ReportGenerator {
    ReportFormat format();
    byte[] generate(ReportRequest req);
}

@Component
public class ReportGeneratorFactory {
    private final Map<ReportFormat, ReportGenerator> generators;

    // Spring 會自動注入所有 ReportGenerator 實作
    public ReportGeneratorFactory(List<ReportGenerator> all) {
        this.generators = all.stream()
            .collect(Collectors.toUnmodifiableMap(ReportGenerator::format, Function.identity()));
    }

    public ReportGenerator create(ReportFormat format) {
        ReportGenerator generator = generators.get(format);
        if (generator == null) {
            throw new UnsupportedFormatException(format);
        }
        return generator;
    }
}

// 這三個變成 package-private，外部看不到
@Component class PdfReportGenerator   implements ReportGenerator { }
@Component class ExcelReportGenerator implements ReportGenerator { }
@Component class CsvReportGenerator   implements ReportGenerator { }

搭配 ArchUnit 規則（第 39 章會詳述）：

@ArchTest
static final ArchRule 報表實作不得被套件外直接使用 =
    classes().that().implement(ReportGenerator.class)
             .should().onlyBeAccessed().byClassesThat()
             .resideInAPackage("com.example.report..");

🔧 Spring 環境的重要提醒 上面的 After 版本利用了 Spring 的「注入同型別所有 bean」機制。這在 Spring 專案中通常比手寫 switch 的 Factory 更好，因為新增一個實作時完全不需要修改 Factory。 但代價是：新增一個實作變成隱式的——看 Factory 的程式碼看不出有哪些實作。團隊要在「新增時零修改」與「可見性」之間取捨。

得到什麼

• 呼叫端不再與具體實作耦合
• 新增一種格式：只需新增一個 package-private 類別（Spring 版本連 Factory 都不用改）
• 實作類別可以自由改名、改結構、合併，不影響外部

付出什麼

什麼時候不要用

• 只有一個實作 → 這是 Speculative Generality（第 8.11 節），不要做
• 實作類別本來就該被外部知道（例如它們是公開 API 的一部分）
• 選型邏輯只出現在一個地方 → 那個 if/else 就是唯一的分派點，它沒有問題
• 呼叫端本來就只用其中一種

AI Prompt 與驗證

角色：資深 Java / Spring 工程師。

背景：[介面名稱] 目前有 [N] 個實作，呼叫端直接 new 具體類別。
      本專案 Java 25 / Spring Boot 4.1.x，使用建構子注入。

目標：評估並執行 Encapsulate Classes with Factory。

限制：
- 不得改變任何實作類別的內部邏輯
- 不得改變選型的判斷結果（相同輸入必須選到相同的實作）
- 保留原本 default 或 else 分支的例外型別與訊息

步驟：
1. 先回答：目前有幾個實作？有哪些呼叫端？（列出檔案行號）
2. 回答：實作數量是否達 2 個以上？若只有 1 個，請建議不要執行本重構並停止
3. 提出兩種方案的比較：
   (a) Factory 內用明確的 switch（可見性好，新增要改 Factory）
   (b) Spring 注入 List 介面（新增零修改，可見性差）
   說明各自的取捨，等我選擇
4. 依我的選擇實作，每步跑測試

停止條件：
- 實作數為 1，停止
- 發現有實作類別被 com.example.report 以外的套件使用，停止並列出

驗證 checklist：

• 所有原本的 format 值都能選到相同的實作
• 未知 format 的例外型別與訊息完全一致
• 實作類別已改為 package-private，且編譯通過
• 若使用 Spring 自動注入：確認所有實作都有 @Component（漏掉一個會靜默少一種格式）
• 若使用 Spring 自動注入：確認沒有兩個實作回傳相同的 format key（toUnmodifiableMap 會丟例外，但要在啟動時就發現）
• 加上 ArchUnit 規則防止回退

11.4 Introduce Polymorphic Creation with Factory Method

一句話

當一個繼承體系裡，每個子類別都需要「建立自己專屬的某種物件」時，把那個建立動作抽成一個可覆寫的方法。

⚠️ 先講結論：這是 Creation 類中最少用到的一項。在 Spring 專案中，它幾乎總是被依賴注入取代。請先讀「什麼時候不要用」。

起點 Smell

• 一個繼承體系中，多個子類別有幾乎相同的方法，唯一的差別是中間 new 了不同的類別
• 這是 Duplicated Code（7.2）的一種特殊形式

Before

// Before：Java 8 — 兩個測試類別的 setUp 幾乎一樣，只差在 new 了不同的東西
public abstract class DataProcessorTest {
    // 子類別各自複製了幾乎相同的流程
}

public class XmlProcessorTest extends DataProcessorTest {
    public void testProcess() {
        DataProcessor p = new XmlProcessor();      // ← 只有這行不同
        p.setEncoding("UTF-8");
        p.setStrictMode(true);
        Result r = p.process(sampleInput());
        assertEquals(expected(), r);
    }
}

public class JsonProcessorTest extends DataProcessorTest {
    public void testProcess() {
        DataProcessor p = new JsonProcessor();     // ← 只有這行不同
        p.setEncoding("UTF-8");
        p.setStrictMode(true);
        Result r = p.process(sampleInput());
        assertEquals(expected(), r);
    }
}

重構步驟

中間態

步驟 2 之後，子類別仍有重複的流程，但建立點已經被抽象化。如果重複的部分只有兩三行，可以停在這裡——把流程也拉到父類別會引入繼承耦合，未必划算。

After

// After：Java 25 + JUnit 5
abstract class DataProcessorTestBase {

    /** 由各子類別決定要測試哪一種實作。 */
    protected abstract DataProcessor createProcessor();

    @Test
    void 處理樣本輸入應產生預期結果() {
        DataProcessor processor = createProcessor();
        processor.setEncoding(StandardCharsets.UTF_8);
        processor.setStrictMode(true);

        Result result = processor.process(sampleInput());

        assertThat(result).isEqualTo(expected());
    }
}

class XmlProcessorTest extends DataProcessorTestBase {
    @Override protected DataProcessor createProcessor() { return new XmlProcessor(); }
}

class JsonProcessorTest extends DataProcessorTestBase {
    @Override protected DataProcessor createProcessor() { return new JsonProcessor(); }
}

🔧 本手冊的工程建議：JUnit 5 有更好的做法 上面的繼承結構在 JUnit 5 中可以用 @ParameterizedTest 完全取代，而且不需要繼承：

@ParameterizedTest
@MethodSource("processors")
void 處理樣本輸入應產生預期結果(DataProcessor processor) {
    processor.setEncoding(StandardCharsets.UTF_8);
    processor.setStrictMode(true);
    assertThat(processor.process(sampleInput())).isEqualTo(expected());
}

static Stream<DataProcessor> processors() {
    return Stream.of(new XmlProcessor(), new JsonProcessor());
}

在 JUnit 5 專案中，請優先考慮這個做法。 這是本手冊與 2004 年原書的另一處時代差異——當年的 JUnit 3 沒有參數化測試。

得到什麼

• 消除子類別間的重複流程
• 新增一種實作的測試只需要寫一個方法

付出什麼

什麼時候不要用

• Spring 專案的正式程式碼中 → 用依賴注入，不要用繼承 + Factory Method
• JUnit 5 專案的測試中 → 用 @ParameterizedTest
• 只有兩個子類別，且重複只有兩三行 → 重複比繼承便宜
• 子類別之間的流程其實有微妙差異 → 硬拉到父類別後會出現一堆 if (isXml())，比原本更糟

AI Prompt 與驗證

角色：資深 Java 工程師。

背景：[父類別] 底下有 [N] 個子類別，疑似有重複的流程。
      本專案 Java 25 / JUnit 5。

目標：評估是否適合 Introduce Polymorphic Creation with Factory Method。

限制（只做分析）：
- 不得修改任何檔案

步驟：
1. 逐行比對各子類別的重複方法，標示出「完全相同」與「有差異」的部分
2. 回答：差異是否只有物件建立那一行？若還有其他差異，請列出
3. 回答：這是測試程式碼還是正式程式碼？
4. 依以下規則給出建議：
   - 若是測試且專案為 JUnit 5，建議改用 @ParameterizedTest 而非繼承
   - 若是 Spring 正式程式碼，建議改用依賴注入而非繼承
   - 若差異不只建立那一行，建議不要執行本重構
   - 其餘情況才建議執行

停止條件：
- 完成步驟 4 後停止，等我決定

驗證 checklist：

• 所有子類別的測試仍然各自執行（沒有因為抽到父類別而少跑）
• 測試數量與重構前相同
• 沒有把「原本有差異的行為」誤當成相同而合併

11.5 Encapsulate Composite with Builder

一句話

當要建立一個巢狀的樹狀結構（例如 XML、DOM、規則樹）很囉唆時，用 Builder 把建立過程變得簡潔且不易出錯。

起點 Smell

• 建立巢狀結構的程式碼充滿樣板：new Node(); node.setX(); parent.add(node); 反覆出現
• 呼叫端需要知道 Composite 的內部結構細節
• 容易忘記把子節點加入父節點（結構建錯但不會報錯）

Before

// Before：Java 8 — 建立一段 XML 需要大量樣板
TagNode orders = new TagNode("orders");

TagNode order = new TagNode("order");
order.addAttribute("id", "12345");
orders.add(order);

TagNode product = new TagNode("product");
product.addAttribute("id", "P-001");
product.addAttribute("color", "red");
order.add(product);

TagNode price = new TagNode("price");
price.addAttribute("currency", "TWD");
price.setValue("1200");
product.add(price);
// 很容易寫成 orders.add(price) — 結構錯了，但編譯與執行都不會報錯

重構步驟

中間態

步驟 3 進行到一半是完全可以接受的狀態——新程式碼用 Builder，舊程式碼維持原樣。不需要一次改完所有呼叫端。

After

// After：Java 25
public final class TagBuilder {
    private final Deque<TagNode> stack = new ArrayDeque<>();
    private final TagNode root;

    public TagBuilder(String rootName) {
        this.root = new TagNode(rootName);
        stack.push(root);
    }

    public TagBuilder addChild(String name) {
        TagNode child = new TagNode(name);
        stack.peek().add(child);          // 不可能忘記掛到父節點
        stack.push(child);
        return this;
    }

    public TagBuilder addAttribute(String name, String value) {
        stack.peek().addAttribute(name, value);
        return this;
    }

    public TagBuilder addValue(String value) {
        stack.peek().setValue(value);
        return this;
    }

    public TagBuilder end() {
        if (stack.size() <= 1) {
            throw new IllegalStateException("已在根節點，無法再結束");
        }
        stack.pop();
        return this;
    }

    public String toXml() {
        return root.toXml();
    }
}

呼叫端：

String xml = new TagBuilder("orders")
        .addChild("order").addAttribute("id", "12345")
            .addChild("product")
                .addAttribute("id", "P-001")
                .addAttribute("color", "red")
                .addChild("price").addAttribute("currency", "TWD").addValue("1200").end()
            .end()
        .end()
        .toXml();

得到什麼

• 呼叫端不可能忘記把子節點掛到父節點（結構由 Builder 保證）
• 程式碼的縮排反映了結構的巢狀關係，可讀性大幅提升
• Composite 的內部結構被封裝，未來可以替換實作

付出什麼

⚠️ 安全性提醒 上面的範例沒有做 XML 跳脫。若 addValue 的內容可能來自使用者輸入，必須對 < > & " ' 進行跳脫，否則會產生結構破壞或注入問題。 實務上請優先使用成熟的函式庫（JAXB、Jackson XML、DOM API），不要自己寫 XML 產生器。本節的範例是為了說明 Builder 的結構，不是建議你自己實作 XML。

什麼時候不要用

• 已經有成熟的函式庫（JSON 用 Jackson、XML 用 JAXB）→ 用函式庫
• 結構只有兩層且固定 → 直接寫，不需要 Builder
• 只在一兩個地方建立 → 抽一個私有方法就夠
• 把 Builder 用在非樹狀的簡單物件上（那是另一種 Builder，見 7.5 節的 Long Parameter List）

AI Prompt 與驗證

角色：資深 Java 工程師。

背景：以下程式碼在建立巢狀的 [結構名稱]，樣板程式碼很多。
      [貼上程式碼]
      本專案 Java 25。

目標：評估並執行 Encapsulate Composite with Builder。

限制：
- 產出的結果字串必須與原本「逐字元完全相同」
- 不得改變任何屬性的輸出順序
- 不得新增或移除任何跳脫處理（若原本沒跳脫，保持沒跳脫，但要在回報中標示這是安全風險）

步驟：
1. 先回答：專案是否已有處理此格式的成熟函式庫？若有，建議改用函式庫並停止
2. 若沒有，設計 Builder 的 API，先只輸出設計，等我確認
3. 確認後實作 Builder，並附上單元測試
4. 一次改寫一處呼叫端，每次都輸出「重構前後的結果字串比對」

停止條件：
- 任何一處的輸出字串有差異，立即停止並回報差異內容
- 發現內容可能來自使用者輸入而原本沒有跳脫，停止並回報安全風險

驗證 checklist：

• 產出的字串與重構前逐字元相同（用 assertEquals 比對完整輸出，不要只比對片段）
• 屬性順序未改變（某些下游系統會依順序解析）
• 跳脫行為未改變
• end() 呼叫不足或過多時有明確的例外
• 大量產生時的效能未明顯退化

11.6 Inline Singleton

一句話

把不必要的 Singleton 拆掉，讓它變回一般的物件。

🔧 本手冊認為這是 Creation 類中最重要的一項，因為企業 Java 專案裡的手寫 Singleton，絕大多數都該被移除。

起點 Smell

• 有一個手寫的 Singleton（私有建構子 + getInstance()）
• 它的「唯一性」沒有任何領域上的必要，只是為了方便存取
• 測試時無法替換它，導致測試必須連到真實的資料庫或外部系統
• 它持有可變狀態，在並行下有風險

Before

// Before：Java 8 — 典型的手寫 Singleton
public class ExchangeRateCache {
    private static final ExchangeRateCache INSTANCE = new ExchangeRateCache();
    private final Map<String, BigDecimal> rates = new HashMap<>();   // 可變狀態
    private Date lastRefresh;

    private ExchangeRateCache() { }

    public static ExchangeRateCache getInstance() { return INSTANCE; }

    public BigDecimal getRate(String currency) {
        if (lastRefresh == null || isStale(lastRefresh)) {
            refresh();                    // 會連外部 API
        }
        return rates.get(currency);
    }
}

// 呼叫端 — 散落在 23 個地方
BigDecimal rate = ExchangeRateCache.getInstance().getRate("USD");

這段程式碼的四個問題：

重構步驟

步驟 1 的橋接寫法（讓新舊寫法可以並存，這是能漸進遷移的關鍵）：

// 過渡期：兩種寫法都能用
@Component
public class ExchangeRateCache {
    private static ExchangeRateCache instance;       // 過渡用，最後會移除

    public ExchangeRateCache(RateApiClient client) { /* ... */ }

    @PostConstruct
    void registerLegacyAccess() { instance = this; }

    /** @deprecated 過渡期用，請改為建構子注入。預計於 2026-Q4 移除。 */
    @Deprecated(since = "2026-09", forRemoval = true)
    public static ExchangeRateCache getInstance() { return instance; }
}

中間態

步驟 1 完成後就是一個可以長期停留的狀態：新程式碼用注入，舊程式碼繼續用 getInstance()。

這讓你可以在不中斷開發的情況下，花三個月慢慢遷移 23 個呼叫端。加上 @Deprecated(forRemoval = true) 之後，IDE 會提醒每個碰到舊寫法的人。

After

// After：Java 25 + Spring Boot 4.x
@Component
public class ExchangeRateCache {
    private final RateApiClient client;
    private final Clock clock;
    private final Map<String, BigDecimal> rates = new ConcurrentHashMap<>();   // 執行緒安全
    private volatile Instant lastRefresh;

    public ExchangeRateCache(RateApiClient client, Clock clock) {
        this.client = client;
        this.clock = clock;
    }

    public BigDecimal getRate(CurrencyCode currency) {
        refreshIfStale();
        return rates.get(currency.value());
    }
}

// 呼叫端 — 依賴變成明示的
@Service
public class OrderService {
    private final ExchangeRateCache rateCache;

    public OrderService(ExchangeRateCache rateCache) {   // 一眼看出依賴
        this.rateCache = rateCache;
    }
}

得到什麼

• 測試可以注入假的匯率，單元測試不再連外部 API（這通常是最大的收穫）
• 依賴關係變成明示的，從建構子簽章就看得出來
• 生命週期由 Spring 管理，可以做 @PreDestroy、健康檢查、metrics
• 可以有多個實例（例如測試用、正式用）

付出什麼

什麼時候不要用

• Singleton 的唯一性是領域要求（例如一個實體的硬體裝置控制器）→ 保留，但改用 11.7 節的做法
• 不在 DI 容器環境中（純工具程式、Android 的某些情境）
• 它是真正無狀態的工具類別（例如只有 static 方法的 StringUtils）→ 那不是 Singleton，不需要處理
• 呼叫端超過 100 處且該模組即將下線 → 成本效益不成立

AI Prompt 與驗證

角色：資深 Java / Spring 工程師。

背景：[類別名稱] 是手寫的 Singleton（private 建構子 + getInstance()）。
      本專案 Java 25 / Spring Boot 4.1.x，使用建構子注入。

目標：執行 Inline Singleton，改為 Spring 管理的 bean。

限制：
- 必須採用「過渡橋接」方式，不得一次改完所有呼叫端
- 每個 PR 最多修改 5 個呼叫端
- 不得在本次重構中修改該類別的任何業務邏輯
- 不得在本次重構中修正執行緒安全問題（那是另一個 PR）

步驟：
1. 列出所有 getInstance() 的呼叫端（檔案與行號），並統計總數
2. 回答：該類別是否持有可變狀態？是否有執行緒安全疑慮？（只回報，不修正）
3. 實作過渡橋接版本（保留 getInstance 並標示 @Deprecated(forRemoval = true)）
4. 提出遷移計畫：分幾個 PR、每個 PR 改哪些呼叫端

停止條件：
- 若呼叫端超過 30 處，停止並先與我確認遷移計畫
- 若發現該類別在 static 初始化區塊中有副作用，停止並回報

驗證 checklist：

• 過渡期：getInstance() 與注入兩種方式都能取得同一個實例
• 所有呼叫端遷移完成後，static 欄位與 getInstance() 已完全移除
• 確認沒有在 Spring context 初始化前呼叫 getInstance()（會拿到 null）
• 確認沒有在 static 初始化區塊或 static 方法中使用該類別
• 測試現在可以注入測試替身，且單元測試不再連外部系統
• 執行緒安全問題已記錄為獨立的後續工作

11.7 Limit Instantiation with Singleton

一句話

當「必須只有一個實例」是真實的需求時，用 Singleton 限制它。

⚠️ 這是 27 個條目中，本手冊最不建議使用的一項。 在 Spring / Jakarta EE 環境中，容器已經提供了這個能力，自己實作幾乎總是錯的。 本節存在的目的，主要是說明「什麼時候才真的需要」，以及「若真的需要，正確做法是什麼」。

起點 Smell

• 系統中意外產生了多個本該唯一的實例，造成資源浪費或狀態不一致
• 例如：連線池被建立了三份、快取有多份副本互不同步

什麼情況才算「真的需要」

必須同時滿足以下條件：

若任何一項不成立 → 不要用 Singleton。

Before 與 After 的正確對照

// ❌ 不要這樣：在 Spring 專案中手寫 Singleton
public class ConnectionPool {
    private static final ConnectionPool INSTANCE = new ConnectionPool();
    private ConnectionPool() { }
    public static ConnectionPool getInstance() { return INSTANCE; }
}

// ✅ Spring 專案的正確做法：讓容器管理
@Component            // 預設就是 singleton scope
public class ConnectionPool {
    public ConnectionPool(DataSourceProperties props) { }
}

// 或在設定類別中
@Configuration
public class PoolConfig {
    @Bean                                   // 容器保證唯一
    public ConnectionPool connectionPool(DataSourceProperties props) {
        return new ConnectionPool(props);
    }
}

// ✅ 非 DI 環境（例如純 Java 工具程式）的正確做法：enum singleton
public enum FileLockManager {
    INSTANCE;

    private final Map<Path, FileLock> locks = new ConcurrentHashMap<>();

    public FileLock acquire(Path path) { }
}

🏭 業界常見實務：為什麼 enum 是最安全的 Singleton 實作

實作方式	執行緒安全	防序列化破壞	防反射破壞	程式碼量
static 欄位 + getInstance()	✅	❌	❌	中
雙重檢查鎖定（DCL）	⚠️ 需 volatile，容易寫錯	❌	❌	多
靜態內部類別（holder）	✅	❌	❌	中
enum	✅	✅	✅	最少

若真的必須手寫 Singleton，請使用 enum。

得到什麼

• 保證唯一實例
• 避免重複建立昂貴資源

付出什麼

什麼時候不要用

實務上，以下情況佔了 95% 以上，全部都不該用 Singleton：

• 在 Spring / Jakarta EE / Quarkus 等 DI 容器中 → 用容器的 singleton scope
• 只是想「方便存取」 → 用依賴注入
• 只是想「避免重複建立」 → 用容器的 bean 或 lazy 初始化
• 需要被測試替換 → 絕對不要
• 持有可變的業務狀態 → 絕對不要（並行風險）

🤖 AI Agent 的特別提醒 AI 在被要求「實作一個快取」或「實作一個設定管理器」時，經常會自動產生 Singleton，因為那是教科書上的標準答案。 請在 CLAUDE.md 中明確規定（見附錄 B）：

禁止手寫 Singleton（private 建構子 + getInstance）。
需要唯一實例時，一律使用 Spring 的 @Component 或 @Bean。
若確認非 DI 環境且必須唯一，使用 enum singleton，並在 PR 描述中說明理由。

AI Prompt 與驗證

角色：資深 Java / Spring 工程師。

背景：[需求描述]。本專案 Java 25 / Spring Boot 4.1.x。

目標：判斷是否需要限制唯一實例，以及應採用什麼方式。

限制：
- 不得直接產生程式碼

步驟：
1. 回答以下四個問題（逐一給出依據）：
   (a) 唯一性是領域或技術的硬性要求嗎？多個實例會導致什麼錯誤？
   (b) 這個物件是否在 Spring 容器管理範圍內？
   (c) 它是否持有可變狀態？
   (d) 測試時是否需要替換它？
2. 依以下規則給出結論：
   - (b) 為是，建議使用 @Component 或 @Bean，不要手寫 Singleton
   - (a) 為否，建議不要限制唯一性
   - (d) 為是，建議不要使用 Singleton
   - 只有全部條件都指向「必須手寫」時，才建議 enum singleton
3. 輸出結論與理由，等我決定

停止條件：
- 完成步驟 3 後停止

驗證 checklist：

• 已確認四個前提條件全部成立（否則不該做）
• 若在 Spring 環境 → 已改用 @Component / @Bean，沒有手寫 Singleton
• 若必須手寫 → 使用 enum 實作
• 沒有持有可變的業務狀態；若有，已處理執行緒安全
• 在 ADR 或 PR 描述中記錄了「為什麼必須唯一」

11.8 本章實務案例

情境：某保險公司的核心系統，2011 年起累積了 47 個手寫 Singleton。

問題浮現的過程：

團隊要為「保費試算」寫單元測試時，發現一個測試要跑 8 秒——因為 RateTableCache.getInstance() 會連 DB2 載入 12 萬筆費率。而這個 Singleton 被 6 個其他 Singleton 依賴，形成一張隱藏的依賴網。

盤點結果：

# 找出所有手寫 Singleton
grep -rn "private static final.*INSTANCE\|getInstance()" src/main/java --include="*.java" \
  | grep -v "^.*Test" | wc -l

執行過程（歷時 5 個月，共 34 個 PR）：

第 5 階段的 ArchUnit 規則：

@ArchTest
static final ArchRule 不得手寫_Singleton =
    noClasses().that().resideInAPackage("com.example..")
        .and().areNotEnums()
        .should(new ArchCondition<JavaClass>("宣告 getInstance() 靜態方法") {
            @Override
            public void check(JavaClass item, ConditionEvents events) {
                item.getMethods().stream()
                    .filter(m -> m.getModifiers().contains(JavaModifier.STATIC))
                    .filter(m -> m.getName().equals("getInstance"))
                    .forEach(m -> events.add(SimpleConditionEvent.violated(item,
                        item.getName() + " 宣告了 getInstance()，請改用 Spring 管理的 bean")));
            }
        })
        .because("手寫 Singleton 會讓依賴隱藏且無法測試，見手冊第 11.6、11.7 節");

成果：

最後一列最值得注意：原本的 RateTableCache 在叢集環境下每個節點有一份，而重新載入的時機各自獨立——導致同一筆試算在不同節點會得到不同結果。改為 Spring bean 之後，團隊才有機會加上統一的快取失效機制。

🔧 這個案例最重要的一點 測試時間從 8.2 秒降到 0.04 秒，不是效能優化的成果，是可測試性改善的副產品。 而測試變快之後，團隊才真的開始寫測試——這是所有後續改善的前提。

11.9 本章注意事項

⚠️ 不要為了「包住 new」而建立 Factory 一個只有 return new Xxx(); 的 Factory 沒有任何價值。Factory 的價值來自它封裝了建立的知識（選型、組裝、驗證、快取）。

⚠️ Spring 專案中，先問「容器是不是已經在做這件事」 物件建立、生命週期管理、依賴組裝、單例保證——這些 Spring 都在做。自己再寫一層，多半是重複勞動。

⚠️ 在 Creation Method 中新增驗證是行為變更 這是本章最容易被忽略的風險。重構 PR 中不要加驗證；要加，另開 PR，並先確認生產資料中有多少筆會被擋下。

⚠️ Inline Singleton 必須用過渡橋接漸進遷移 一次改完所有呼叫端的 PR 無法 Review，也無法安全 revert。@Deprecated(forRemoval = true) 是讓遷移可以拖三個月而不失控的關鍵。

✅ 用 ArchUnit 把決策固化下來 花五個月清掉的 44 個 Singleton，如果沒有規則保護，兩年後會長回來。第 39 章有完整的規則寫法。

✅ 框架相容性要在動手前確認 JPA 需要無參數建構子、Jackson 需要可存取的建構子或 setter、某些函式庫用反射建立物件。把建構子改 private 之前，先確認這些。

📌 下一章 第 12 章進入 Simplification 類的前三項：Compose Method、Replace Conditional Logic with Strategy、Move Embellishment to Decorator。 其中 Replace Conditional Logic with Strategy 是全書最常被誤用的條目，該節會用最大的篇幅說明「什麼時候不要用」。

第 12 章 Simplification 類重構（上）

本章三個條目的共同目標是：讓複雜的程式碼變簡單。

但三者的「代價曲線」差異極大：

flowchart LR
    A["Compose Method<br/>12.1"] --> A1["代價：幾乎為零<br/>適用：幾乎所有長方法<br/>使用頻率：★★★★★"]
    B["Replace Conditional Logic<br/>with Strategy 12.2"] --> B1["代價：高（N+1 個檔案）<br/>適用：嚴格的前提條件<br/>使用頻率：★★☆☆☆"]
    C["Move Embellishment<br/>to Decorator 12.3"] --> C1["代價：中高<br/>適用：可組合的附加責任<br/>使用頻率：★★☆☆☆"]

    style A1 fill:#d4edda,stroke:#28a745
    style B1 fill:#f8d7da,stroke:#dc3545
    style C1 fill:#fff3cd,stroke:#ffc107

🔧 本手冊的工程建議 如果你這輩子只學一個 pattern-directed refactoring，學 Compose Method。 它適用範圍最廣、代價最低，而且是所有其他重構的前置步驟。

12.1 Compose Method

一句話

把一個長方法改寫成「一連串同一抽象層級的具名步驟」，讓主方法讀起來像一段說明。

起點 Smell

• Long Method（7.3）
• 方法內有註解分段（// 1. 驗證 // 2. 計算）
• 方法內混雜了不同抽象層級：一行是 validateOrder(o)，下一行是 if (s.charAt(3) == 'X')

Before

// Before：Java 8 — 混雜了四種抽象層級
@Service
public class SettlementService {

    public SettlementResult settle(String batchId) {
        // 1. 取得批次
        Batch batch = batchDao.find(batchId);
        if (batch == null) {
            throw new BatchNotFoundException(batchId);
        }
        if (batch.getStatus() != 1 && batch.getStatus() != 2) {
            throw new IllegalBatchStatusException(batchId, batch.getStatus());
        }

        // 2. 計算總額
        BigDecimal total = BigDecimal.ZERO;
        BigDecimal fee = BigDecimal.ZERO;
        for (Transaction t : batch.getTransactions()) {
            if (t.getStatus() == 9) continue;
            total = total.add(t.getAmount());
            if (t.getAmount().compareTo(new BigDecimal("50000")) > 0) {
                fee = fee.add(t.getAmount().multiply(new BigDecimal("0.001")));
            } else {
                fee = fee.add(new BigDecimal("15"));
            }
        }

        // 3. 寫入結算檔
        StringBuilder sb = new StringBuilder();
        sb.append("H").append(new SimpleDateFormat("yyyyMMdd").format(new Date()));
        sb.append(String.format("%015d", total.movePointRight(2).longValue()));
        for (Transaction t : batch.getTransactions()) {
            if (t.getStatus() == 9) continue;
            sb.append("D").append(t.getId()).append(...);
        }
        Files.write(Paths.get("/data/settle/" + batchId + ".txt"), sb.toString().getBytes());

        // 4. 更新狀態
        batch.setStatus(3);
        batch.setSettledAt(new Date());
        batchDao.update(batch);

        return new SettlementResult(batchId, total, fee);
    }
}

重構步驟

✅ 步驟 1 請務必使用 IDE 的自動重構功能，不要手打。 IntelliJ：選取程式碼後 Ctrl+Alt+M。它會自動處理區域變數的進出參數，不會手滑。

中間態

步驟 1 + 2 完成後就已經達成目標。步驟 3～5 是精修。

⚠️ 步驟 2 是關鍵，不能省略 只做步驟 1（抽方法但不改名）的結果是 doStep1()、doStep2()，這沒有改善任何事——你只是把 100 行分成 4 個 25 行，讀者仍然要全部讀完才知道在做什麼。 好的名稱讓讀者可以不讀實作。這才是 Compose Method 的價值。

After

// After：Java 25 + Spring Boot 4.x
@Service
public class SettlementService {

    private static final Money LARGE_TXN_THRESHOLD = Money.twd(50_000);
    private static final BigDecimal LARGE_TXN_FEE_RATE = new BigDecimal("0.001");
    private static final Money SMALL_TXN_FLAT_FEE = Money.twd(15);

    public SettlementResult settle(BatchId batchId) {
        Batch batch = loadSettleableBatch(batchId);
        List<Transaction> effective = effectiveTransactions(batch);

        Money total = sumAmounts(effective);
        Money fee = calculateTotalFee(effective);

        writeSettlementFile(batchId, total, effective);
        markBatchAsSettled(batch);

        return new SettlementResult(batchId, total, fee);
    }

    // ---- 以下每個方法都在「比主方法低一層」的抽象層級 ----

    private Batch loadSettleableBatch(BatchId batchId) {
        Batch batch = batchDao.find(batchId)
                .orElseThrow(() -> new BatchNotFoundException(batchId));
        if (!batch.status().isSettleable()) {
            throw new IllegalBatchStatusException(batchId, batch.status());
        }
        return batch;
    }

    private List<Transaction> effectiveTransactions(Batch batch) {
        return batch.transactions().stream()
                    .filter(t -> !t.isVoided())
                    .toList();
    }

    private Money sumAmounts(List<Transaction> transactions) {
        return transactions.stream()
                .map(Transaction::amount)
                .reduce(Money.zeroTwd(), Money::add);
    }

    private Money calculateTotalFee(List<Transaction> transactions) {
        return transactions.stream()
                .map(this::feeOf)
                .reduce(Money.zeroTwd(), Money::add);
    }

    private Money feeOf(Transaction transaction) {
        return transaction.amount().isGreaterThan(LARGE_TXN_THRESHOLD)
               ? transaction.amount().multiply(LARGE_TXN_FEE_RATE)
               : SMALL_TXN_FLAT_FEE;
    }
    // writeSettlementFile / markBatchAsSettled 略
}

現在 settle() 讀起來像一段業務說明：載入可結算的批次 → 取出有效交易 → 加總金額 → 計算手續費 → 寫結算檔 → 標記已結算。

得到什麼

• 主方法成為流程的目錄，讀者可以只讀它就理解整體
• 每個私有方法可以單獨理解、單獨測試（若改為 package-private）
• 業務詞彙被明確命名（isSettleable、isVoided、effectiveTransactions）
• 後續的任何重構（Strategy、Factory）都以此為起點

付出什麼

什麼時候不要用

• 方法是線性、無分支的資料對應（例如 80 行的欄位 mapping）→ 拆開反而更難對照
• 極端效能敏感的內層迴圈（需實測，不要憑感覺）
• 方法已經很短且清楚

AI Prompt 與驗證

角色：資深 Java 工程師，正在執行安全重構。

背景：[類別].[方法] 有 [N] 行，包含註解分段。
      本專案 Java 25 / Spring Boot 4.1.x。
      已有測試：[測試類別名稱]。

目標：只執行 Compose Method。

限制（硬性）：
- 不得新增任何 class、interface、enum、record
- 不得改變任何邏輯、條件順序或例外行為
- 不得修改測試檔案
- 不得改變方法簽章
- 抽出的方法一律為 private
- 方法名稱必須描述「做什麼」，禁止使用 step1 / doPart2 / process1 這類名稱

步驟：
1. 列出你打算抽出的每一段（起訖行號）與建議的方法名稱，等我確認
2. 確認後，一次抽出一個方法，每次執行 [測試指令]
3. 每次回報：抽出的方法名稱、diff、測試結果

停止條件：
- 任何測試失敗，立即停止並回報
- 若某一段的業務意圖不明確而無法命名，停止並詢問，不要猜測
- 完成所有抽取後停止，不要繼續進行其他重構（特別是不要導入任何 Pattern）

驗證 checklist：

• 既有測試全綠，測試檔案未被修改
• 圈複雜度下降（SonarQube）
• 主方法的每一行都在同一抽象層級
• 沒有 step1 / doPart2 這類名稱
• 條件的短路求值順序未改變
• 例外的型別、訊息與拋出時機完全一致
• 沒有新增任何類別

12.2 Replace Conditional Logic with Strategy

🔴 這是全書最常被誤用的條目。請先讀「什麼時候不要用」再讀其他段落。

一句話

把「依條件選擇不同演算法」的邏輯，改成「把演算法變成可替換的物件」。

起點 Smell

• Conditional Complexity（8.1）
• 同一組條件分派在多處重複（8.2 Switch Statements）
• 每個分支內部都是一整套完整的演算法（不是一兩行）

使用前的三道關卡

🔧 本手冊的工程建議：這三個問題必須全部答「是」，才能進行本重構。

flowchart TD
    A[考慮導入 Strategy] --> Q1{現有變體是否達 3 個<br/>或 2 個且 roadmap 有第 3 個?}
    Q1 -->|否| N1["⛔ 不要做<br/>改用 Compose Method 12.1"]
    Q1 -->|是| Q2{git log 顯示各變體<br/>曾各自單獨被修改嗎?}
    Q2 -->|否，都是一起改| N2["⛔ 不要做<br/>它們是同一件事的不同參數"]
    Q2 -->|是| Q3{每個分支的內容<br/>是否為完整演算法<br/>而非僅參數差異?}
    Q3 -->|否，只是數字或字串不同| N3["⛔ 不要做<br/>把差異外部化為設定"]
    Q3 -->|是| Y["✅ 可以進行"]

    style N1 fill:#f8d7da,stroke:#dc3545
    style N2 fill:#f8d7da,stroke:#dc3545
    style N3 fill:#f8d7da,stroke:#dc3545
    style Y fill:#d4edda,stroke:#28a745

取得第二道關卡的證據：

# 檢視含分派邏輯的檔案，過去兩年每次改了哪些分支
git log --since="2 years ago" -p --follow -- src/main/java/com/example/fee/FeeCalculator.java \
  | grep -E "^\+|^commit|^Date" | head -80

Before

// Before：Java 8 — 三種計息方式，每種都是完整的演算法
@Service
public class InterestCalculator {

    public BigDecimal calculate(Loan loan, Date asOf) {
        String method = loan.getInterestMethod();

        if ("SIMPLE".equals(method)) {
            // 單利：本金 × 年利率 × 天數 / 365
            long days = daysBetween(loan.getStartDate(), asOf);
            return loan.getPrincipal()
                       .multiply(loan.getAnnualRate())
                       .multiply(new BigDecimal(days))
                       .divide(new BigDecimal(365), 2, RoundingMode.HALF_UP);

        } else if ("COMPOUND_MONTHLY".equals(method)) {
            // 月複利：逐月滾入
            BigDecimal balance = loan.getPrincipal();
            BigDecimal monthlyRate = loan.getAnnualRate()
                                         .divide(new BigDecimal(12), 10, RoundingMode.HALF_UP);
            int months = monthsBetween(loan.getStartDate(), asOf);
            for (int i = 0; i < months; i++) {
                balance = balance.add(balance.multiply(monthlyRate)
                                             .setScale(2, RoundingMode.HALF_UP));
            }
            return balance.subtract(loan.getPrincipal());

        } else if ("ACTUAL_360".equals(method)) {
            // 實際天數 / 360（國際慣例）
            long days = daysBetween(loan.getStartDate(), asOf);
            return loan.getPrincipal()
                       .multiply(loan.getAnnualRate())
                       .multiply(new BigDecimal(days))
                       .divide(new BigDecimal(360), 2, RoundingMode.HALF_UP);

        } else {
            throw new UnsupportedInterestMethodException(method);
        }
    }
}

這個例子通過了三道關卡嗎？

結論：可以進行。

重構步驟

⚠️ 步驟 1 與步驟 2 不可跳過 直接從 Before 跳到 Strategy 是 AI 最常犯的錯誤。先做 Compose Method 有兩個好處： ① 它本身就可能解決問題（那就省下了 N+1 個檔案） ② 它讓後續的搬移變成機械動作，風險大幅降低

中間態

步驟 2 是本手冊最強調的停損點。 做完 Compose Method 之後，程式碼長這樣：

public BigDecimal calculate(Loan loan, LocalDate asOf) {
    return switch (loan.interestMethod()) {
        case SIMPLE           -> simpleInterest(loan, asOf);
        case COMPOUND_MONTHLY -> monthlyCompoundInterest(loan, asOf);
        case ACTUAL_360       -> actual360Interest(loan, asOf);
    };
}

這已經很好讀了。 如果你的痛點是「看不懂」，到這裡就結束。

只有當痛點是「新增一種計息方式要改這個檔案，而這個檔案還有其他 20 個方法，每次改都要 Review 全部」時，才需要繼續往下走。

After

// After：Java 25 + Spring Boot 4.x

public interface InterestCalculationStrategy {
    InterestMethod method();
    Money calculate(Loan loan, LocalDate asOf);
}

@Component
class SimpleInterestStrategy implements InterestCalculationStrategy {
    private static final BigDecimal DAYS_PER_YEAR = new BigDecimal(365);

    @Override public InterestMethod method() { return InterestMethod.SIMPLE; }

    @Override
    public Money calculate(Loan loan, LocalDate asOf) {
        long days = ChronoUnit.DAYS.between(loan.startDate(), asOf);
        return loan.principal()
                   .multiply(loan.annualRate())
                   .multiply(BigDecimal.valueOf(days))
                   .divide(DAYS_PER_YEAR, 2, RoundingMode.HALF_UP);
    }
}

@Component
class MonthlyCompoundInterestStrategy implements InterestCalculationStrategy {
    @Override public InterestMethod method() { return InterestMethod.COMPOUND_MONTHLY; }

    @Override
    public Money calculate(Loan loan, LocalDate asOf) {
        Money balance = loan.principal();
        BigDecimal monthlyRate = loan.annualRate()
                                     .divide(BigDecimal.valueOf(12), 10, RoundingMode.HALF_UP);
        int months = (int) ChronoUnit.MONTHS.between(loan.startDate(), asOf);
        for (int i = 0; i < months; i++) {
            balance = balance.add(balance.multiply(monthlyRate)
                                         .setScale(2, RoundingMode.HALF_UP));
        }
        return balance.subtract(loan.principal());
    }
}

// Actual360InterestStrategy 略

@Service
public class InterestCalculator {
    private final Map<InterestMethod, InterestCalculationStrategy> strategies;

    public InterestCalculator(List<InterestCalculationStrategy> all) {
        this.strategies = all.stream().collect(
            Collectors.toUnmodifiableMap(InterestCalculationStrategy::method, Function.identity()));
    }

    public Money calculate(Loan loan, LocalDate asOf) {
        InterestCalculationStrategy strategy = strategies.get(loan.interestMethod());
        if (strategy == null) {
            throw new UnsupportedInterestMethodException(loan.interestMethod());
        }
        return strategy.calculate(loan, asOf);
    }
}

得到什麼

• 新增一種計息方式：新增一個檔案，不修改任何既有檔案（開放封閉原則）
• 每種演算法可以獨立測試、獨立 Review、獨立部署變更
• 各演算法的複雜邏輯不再互相干擾

付出什麼

⚠️ 金融計算的特別提醒 搬移計算邏輯時，RoundingMode 與 scale 的每一個細節都必須完全保留。 上面的 MonthlyCompoundInterestStrategy 中，setScale(2, HALF_UP) 在迴圈內部——若重構時誤把它移到迴圈外，算出來的利息會差好幾塊錢。 這類差異不會被「大方向對不對」的測試抓到，必須用歷史資料做逐筆比對。

什麼時候不要用

這一段是本節最重要的部分。

Map + Lambda 的替代方案（當每個分支很短時）：

// 當每個「策略」只有一行時，這比 3 個類別好得多
private static final Map<InterestMethod, BiFunction<Loan, LocalDate, Money>> CALCULATORS =
    Map.of(
        InterestMethod.SIMPLE,      (loan, asOf) -> simpleInterest(loan, asOf),
        InterestMethod.ACTUAL_360,  (loan, asOf) -> actual360(loan, asOf)
    );

🤖 AI Agent 的行為模式（必讀） 在第 9.5 節的實測中，當被要求「重構這段有多分支 if/else 的程式碼」時，AI 在三次嘗試中三次都直接產生了完整的 Strategy 結構，沒有先做 Compose Method，也沒有詢問變體是否會各自演化。 這不是模型能力問題，是預設行為問題。必須用 Prompt 的 Constraints 段落明確阻止。

AI Prompt 與驗證

角色：資深 Java 工程師，正在評估設計變更。

背景：[類別].[方法] 有 [N] 個條件分支，各自執行不同的計算。
      本專案 Java 25 / Spring Boot 4.1.x。
      以下是該檔案過去兩年的 git log：
      [貼上 git log --oneline 輸出]

目標：判斷是否應該導入 Strategy，並在確認後執行。

限制（第一階段只做評估，不得修改任何程式碼）：
- 不得產生任何程式碼

步驟：
1. 回答三道關卡（各自給出依據，不得推測）：
   (a) 現有變體幾個？未來是否會增加？依據是什麼？（若無法從提供的資料判斷，請回答「無法判斷」）
   (b) 從 git log 看，各分支是「一起被修改」還是「各自被修改」？請列出具體 commit
   (c) 各分支的差異是「完整演算法」還是「參數或常數」？
2. 若任一關卡未通過，明確建議「不要導入 Strategy」，並提出替代方案
3. 若三關皆通過，提出分階段計畫：
   階段一 Compose Method（先做，做完重新評估）
   階段二 Extract Strategy（僅在階段一後痛點仍在時才做）
4. 等我決定後才進入實作

停止條件：
- 完成步驟 3 後停止
- 若 (a) 的答案是「無法判斷」，停止並要求我提供 roadmap 資訊

驗證 checklist：

• 每個分支的計算結果與重構前逐筆相同（用歷史資料做回歸比對，不只測幾個樣本）
• RoundingMode 與 scale 在每一步都完全一致
• 迴圈內外的運算順序未改變
• 未知型別的例外型別與訊息一致
• 所有 Strategy 都有 @Component（用測試驗證：斷言 Map 的 size 等於列舉數量）
• 沒有兩個 Strategy 回傳相同的 key
• 效能：若在批次迴圈中使用，已實測百萬筆的執行時間

強烈建議加上這個測試（防止漏註冊）：

@Test
void 每一種計息方式都必須有對應的_Strategy() {
    assertThat(strategies.keySet())
        .containsExactlyInAnyOrder(InterestMethod.values());
}

12.3 Move Embellishment to Decorator

一句話

把「加在核心邏輯上的附加行為」（記錄、快取、重試、計時、加密）搬到可組合的 Decorator 中。

起點 Smell

• 核心方法裡混雜了大量非核心的程式碼（log、try-catch 重試、計時、快取檢查）
• 這些附加行為在多個類別中重複出現
• Combinatorial Explosion（8.3）：出現 WithCacheAndRetryService、WithRetryOnlyService 這類類別

Before

// Before：Java 8 — 核心邏輯只有 3 行，其餘 30 行都是附加行為
@Service
public class CreditScoreService {
    private static final Logger log = LoggerFactory.getLogger(CreditScoreService.class);

    public CreditScore query(String customerId) {
        long start = System.currentTimeMillis();                    // 計時
        log.info("查詢信用評分 start, customerId={}", customerId);    // 記錄

        CreditScore cached = cache.get(customerId);                 // 快取
        if (cached != null && !isStale(cached)) {
            log.info("命中快取, customerId={}", customerId);
            return cached;
        }

        int attempt = 0;
        while (true) {                                              // 重試
            try {
                attempt++;
                // ===== 以下 3 行才是核心邏輯 =====
                CreditReportRequest req = new CreditReportRequest(customerId);
                CreditReportResponse resp = jcicClient.query(req);
                CreditScore score = mapper.toScore(resp);
                // ==============================
                cache.put(customerId, score);
                log.info("查詢信用評分 end, cost={}ms", System.currentTimeMillis() - start);
                return score;
            } catch (TimeoutException e) {
                if (attempt >= 3) {
                    log.error("查詢信用評分失敗, 已重試 {} 次", attempt, e);
                    throw new CreditScoreUnavailableException(customerId, e);
                }
                sleep(1000L * attempt);
            }
        }
    }
}

重構步驟

中間態

步驟 3 完成後可以停下來評估：如果只需要重試，一個 Decorator 就夠了，不必把 log、快取、計時全部拆開。

🔧 本手冊的工程建議：先問「框架有沒有提供」 在 Spring 專案中，這四種附加行為全部都有現成的宣告式支援：

附加行為	Spring 提供的方式	還需要自己寫 Decorator 嗎
快取	@Cacheable	❌ 不需要
重試	@Retryable（Spring Retry）	❌ 不需要
計時與 metrics	@Timed（Micrometer）	❌ 不需要
記錄	AOP @Around 或 @Observed	❌ 通常不需要
交易	@Transactional	❌ 不需要
自訂的業務性包裝	無	✅ 這才是 Decorator 的用武之地

這是本節最重要的提醒：在 Spring 環境中，Move Embellishment to Decorator 的適用範圍比原書小很多，因為 AOP 已經解決了橫切關注點。

After（兩個版本）

版本 A：Spring 宣告式（多數情況的正確答案）

// After A：Java 25 + Spring Boot 4.x — 核心邏輯回到 3 行
@Service
public class CreditScoreService {

    @Cacheable(cacheNames = "creditScore", key = "#customerId.value()")
    @Retryable(retryFor = TimeoutException.class, maxAttempts = 3,
               backoff = @Backoff(delay = 1000, multiplier = 2))
    @Timed(value = "creditScore.query", description = "JCIC 信用評分查詢耗時")
    public CreditScore query(CustomerId customerId) {
        CreditReportResponse response = jcicClient.query(new CreditReportRequest(customerId));
        return mapper.toScore(response);
    }

    @Recover
    CreditScore onExhausted(TimeoutException e, CustomerId customerId) {
        throw new CreditScoreUnavailableException(customerId, e);
    }
}

版本 B：手寫 Decorator（當附加行為有業務語意時）

// After B：當包裝本身有業務規則時（例如：查詢要扣點、要寫稽核軌跡）
public interface CreditScoreQuery {
    CreditScore query(CustomerId customerId);
}

@Component
@Primary
class AuditedCreditScoreQuery implements CreditScoreQuery {
    private final CreditScoreQuery delegate;
    private final AuditLogger auditLogger;

    AuditedCreditScoreQuery(@Qualifier("quotaLimited") CreditScoreQuery delegate,
                            AuditLogger auditLogger) {
        this.delegate = delegate;
        this.auditLogger = auditLogger;
    }

    @Override
    public CreditScore query(CustomerId customerId) {
        auditLogger.record(AuditEvent.creditScoreQueried(customerId));   // 法規要求
        return delegate.query(customerId);
    }
}

@Component("quotaLimited")
class QuotaLimitedCreditScoreQuery implements CreditScoreQuery {
    private final CreditScoreQuery delegate;
    private final QuotaService quotaService;

    @Override
    public CreditScore query(CustomerId customerId) {
        quotaService.consumeOrThrow(customerId);      // 每月查詢次數上限
        return delegate.query(customerId);
    }
}

版本 B 的判斷準則：附加行為是否有業務規則？稽核軌跡與額度扣點是業務要求（會被稽核、會被客訴），用宣告式 AOP 表達會讓業務規則藏在 annotation 裡，不容易被發現與測試。

得到什麼

• 核心邏輯回到本質（3 行）
• 附加行為可以自由組合、調整順序
• 每個 Decorator 可以單獨測試
• 新增一種附加行為不需要修改核心

付出什麼

🔴 順序是安全議題，不只是設計議題

✅ 正確：權限檢查 → 快取 → 重試 → 核心
❌ 錯誤：快取 → 權限檢查 → 重試 → 核心
         （第一個有權限的人查詢後，無權限的人也能從快取讀到）

建議做法：把組裝順序寫在一個明確的 @Configuration 類別中，並加上註解說明為什麼是這個順序。不要依賴 @Order 的數字。

什麼時候不要用

• Spring 已有宣告式支援（快取、重試、交易、metrics）→ 用 annotation
• 只有一種裝飾，而且永遠都套用 → 直接寫在核心裡
• 裝飾之間有順序依賴且難以表達 → 明確的流程方法比隱式組合好
• 團隊不熟悉這個結構 → 除錯成本會超過收益

AI Prompt 與驗證

角色：資深 Java / Spring 工程師。

背景：[類別].[方法] 中，核心邏輯被大量附加行為包圍。
      [貼上程式碼]
      本專案 Java 25 / Spring Boot 4.1.x，已引入 Spring Retry 與 Micrometer。

目標：評估是否應執行 Move Embellishment to Decorator。

限制（只做分析）：
- 不得修改程式碼

步驟：
1. 逐段標示：哪幾行是核心邏輯？哪幾行是附加行為？分別是哪一類附加行為？
2. 對每一種附加行為，回答：
   (a) Spring 是否已有宣告式支援？（@Cacheable / @Retryable / @Timed / @Transactional）
   (b) 這個附加行為是否帶有業務規則（會被稽核、會影響計費、客戶會感知）？
3. 依規則給出建議：
   - (a) 為是且 (b) 為否，建議改用 Spring annotation
   - (b) 為是，建議手寫 Decorator，並說明它應該排在哪一層
   - 若只有一種附加行為且永遠套用，建議維持現狀
4. 若建議手寫 Decorator，請明確列出建議的組裝順序，並說明每一層為何在該位置
   （特別說明：權限或額度檢查是否必須在快取之前）

停止條件：
- 完成步驟 4 後停止

驗證 checklist：

• 重構後的行為完全一致：快取命中率、重試次數、退避時間、例外型別
• 組裝順序正確，且權限／額度檢查在快取之前
• 組裝順序有明確的文件或 @Configuration 說明
• 沒有 Spring 循環依賴（啟動測試）
• 堆疊深度可接受；已確認例外的堆疊追蹤仍可定位問題
• 若改用 @Cacheable：確認 key 的產生方式與原本的快取 key 完全一致
• 若改用 @Retryable：確認重試條件、次數與退避演算法與原本相同

12.4 本章實務案例

情境：某銀行的「交易手續費計算」重構，一次同時遇到本章三個條目。

原始程式碼：FeeService.calculateFee()，620 行，處理 6 種交易類型，每種都混雜了快取、log 與重試。

團隊的處理順序與決策：

最終結果：

這個案例最值得注意的三個決定：

1. 第 5 步是整件事的關鍵，但它不是任何一個 catalog 條目——它只是「把資料從程式碼移到資料表」。最有價值的改善經常不是 Pattern。
2. 第 6 步決定不導入 Strategy，儘管所有人的直覺都是「這裡應該用 Strategy」。理由是第一道關卡：只剩 2 個變體。
3. 總共只新增 2 個類別。如果一開始就交給 AI 做開放式重構，很可能會得到 15 個以上的新檔案。

12.5 本章注意事項

⚠️ Compose Method 是所有其他重構的前置步驟，不要跳過 直接從「一坨 if/else」跳到 Strategy，會讓你錯過「其實 Compose Method 就夠了」這個最省成本的結局。

⚠️ Strategy 的三道關卡必須逐一書面回答 建議在 PR 描述中直接列出三個問題與答案。這能讓 Review 者快速判斷，也留下決策記錄。

⚠️ 金融計算的搬移，必須逐筆比對歷史資料 RoundingMode、scale、迴圈內外的位置——任何一個細節錯了，結果會差幾塊錢，而「差幾塊錢」的 bug 極難被一般測試抓到。

⚠️ Decorator 的組裝順序是安全議題 權限與額度檢查必須在快取之前。請把順序寫在明確的 @Configuration 中並加註說明。

✅ Spring 環境中，先問「框架有沒有提供」 快取、重試、交易、metrics、記錄——這些都有現成的宣告式支援。手寫 Decorator 只保留給「帶有業務規則」的包裝。

✅ 加上「所有實作都已註冊」的測試 Strategy 與 Factory 的 Spring 自動注入版本有一個共同風險：漏加 @Component 會靜默失效。一個斷言 Map size 的測試就能防住。

第 13 章 Simplification 類重構（下）

本章三個條目處理的是更特定的情境，使用頻率比第 12 章低，但在遇到時價值很高。

13.1 Replace State-Altering Conditionals with State

一句話

當「狀態轉移的規則」散落在一堆 if 裡面時，把每個狀態變成一個物件，讓它自己決定能轉到哪裡。

起點 Smell

• 有一個 status 欄位，而程式碼中到處是 if (status == X) 的判斷
• 狀態轉移的規則散落在多個方法中
• 曾經發生「不該允許的狀態轉移」造成的資料錯誤

三個前提（必須全部成立）

⚠️ 最常見的誤用：看到 enum Status 就導入 State Pattern。 一個只是用來標記的 status 欄位，不需要 State Pattern。

Before

// Before：Java 8 — 轉移規則散落在四個方法中
@Service
public class OrderStateService {

    public void pay(Order order) {
        if (order.getStatus() != 1) {                 // 1 = 待付款
            throw new IllegalStateException("狀態不允許付款");
        }
        order.setStatus(2);                           // 2 = 已付款
        order.setPaidAt(new Date());
        inventoryService.reserve(order);
    }

    public void ship(Order order) {
        if (order.getStatus() != 2) {
            throw new IllegalStateException("狀態不允許出貨");
        }
        order.setStatus(3);                           // 3 = 已出貨
        order.setShippedAt(new Date());
        notifyService.notifyShipped(order);
    }

    public void cancel(Order order) {
        // 取消的規則比較複雜 — 不同狀態下行為不同
        if (order.getStatus() == 1) {
            order.setStatus(9);                       // 直接取消
        } else if (order.getStatus() == 2) {
            order.setStatus(9);
            refundService.refund(order);              // 已付款要退款
            inventoryService.release(order);
        } else if (order.getStatus() == 3) {
            throw new IllegalStateException("已出貨不可取消，請申請退貨");
        } else {
            throw new IllegalStateException("狀態不允許取消");
        }
    }
}

檢視三個前提：

結論：適合導入。

重構步驟