DRY (Don’t Repeat Yourself) 是軟體開發的核心原則之一。本章基於 Error Pattern IMP-001，學習如何識別重複程式碼並建立共用模組。後半部分以 v0.31.0 的模組演進和遷移實戰為例，示範共用庫如何隨系統成長持續演進。

問題背景

症狀

相同功能在多個檔案中重複實作：

1# hooks/pre_commit.py
2def run_git_command(cmd):
3    result = subprocess.run(cmd, capture_output=True, text=True)
4    return result.stdout.strip()
5
6# hooks/post_merge.py  -- 完全相同
7# hooks/branch_check.py  -- 完全相同
8# hooks/worktree_guardian.py  -- 完全相同

四個檔案中存在完全相同的函式定義。

5 Why 分析

1. Why 1: 相同的 run_git_command 函式在 4 個檔案中重複
2. Why 2: 每個 Hook 獨立開發，沒有共用模組
3. Why 3: 缺乏 Hook 系統的架構設計和共用程式庫規劃
4. Why 4: 快速開發時複製貼上最快
5. Why 5: 缺乏 DRY 原則的強制檢查機制

DRY 原則核心

重複程式碼的四大壞處：修改需改多處、容易不一致、增加維護成本、測試困難。

DRY 的完整含義不只是「不要複製貼上」：

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

– Andy Hunt & Dave Thomas, The Pragmatic Programmer

這意味著不只是程式碼，還包括業務邏輯、資料定義、設定內容。

識別重複程式碼

1# 找出重複的函式定義
2grep -rh "^def " .claude/hooks/*.py | sort | uniq -c | sort -rn | head -20
3
4# 範例輸出：
5#    4 def run_git_command(cmd):
6#    3 def get_current_branch():
7#    2 def parse_worktree_line(line):

建立共用程式庫

模組結構

1.claude/lib/
2├── __init__.py           # 公開介面
3├── git_utils.py          # Git 操作
4├── config_loader.py      # 配置載入
5├── hook_io.py            # 輸入輸出
6└── hook_logging.py       # 日誌系統

抽取共用函式

從重複程式碼中抽取，加上完整的型別標註和 docstring：

 1# lib/git_utils.py
 2"""Git 操作工具模組。"""
 3
 4import subprocess
 5from pathlib import Path
 6from typing import List, Optional
 7
 8def run_git_command(
 9    cmd: List[str],
10    cwd: Optional[Path] = None,
11    check: bool = False
12) -> str:
13    """執行 Git 命令並回傳輸出。
14
15    Args:
16        cmd: Git 命令列表，例如 ["git", "status"]
17        cwd: 工作目錄，預設為當前目錄
18        check: 是否在命令失敗時拋出異常
19    """
20    result = subprocess.run(
21        cmd, capture_output=True, text=True, cwd=cwd, check=check
22    )
23    return result.stdout.strip()
24
25def get_current_branch(cwd: Optional[Path] = None) -> str:
26    """取得當前分支名稱。"""
27    return run_git_command(["git", "branch", "--show-current"], cwd=cwd)

更新使用處

1# hooks/pre_commit.py（重構後）
2from lib.git_utils import run_git_command, get_current_branch
3
4def check_branch():
5    current_branch = get_current_branch()
6    # 使用共用函式，不再重複定義

抽取技巧

處理微小差異

當重複程式碼有微小差異時，使用參數化：

 1# 重構前：三個檔案各自的版本
 2# hooks/file_a.py
 3def parse_worktree_line(line):
 4    return line[9:]                        # 不 strip
 5
 6# hooks/file_b.py
 7def parse_worktree_line(line):
 8    return line[9:].strip()                # 有 strip
 9
10# hooks/file_c.py
11def parse_worktree_line(line):
12    return line.removeprefix("worktree ")  # 用 Python 3.9+ API
13
14# 重構後：統一實作，支援選項
15WORKTREE_PREFIX = "worktree "
16
17def parse_worktree_line(line: str, strip: bool = True) -> str:
18    """解析 worktree 輸出行。"""
19    result = line.removeprefix(WORKTREE_PREFIX)
20    return result.strip() if strip else result

使用高階函式

當邏輯結構相同但操作不同時：

 1from pathlib import Path
 2from typing import Callable
 3
 4# 重構前
 5def check_all_python_files():
 6    for file in Path(".").glob("**/*.py"):
 7        if validate_python(file): print(f"OK: {file}")
 8
 9def check_all_yaml_files():
10    for file in Path(".").glob("**/*.yaml"):
11        if validate_yaml(file): print(f"OK: {file}")
12
13# 重構後
14def check_files(pattern: str, validator: Callable[[Path], bool]) -> None:
15    for file in Path(".").glob(pattern):
16        if validator(file): print(f"OK: {file}")
17
18check_files("**/*.py", validate_python)
19check_files("**/*.yaml", validate_yaml)

共用模組設計原則

模組演進：從 4 個到 7+ 個

共用程式庫隨著系統成長持續演進。

模組演進表

演進的驅動力

每次新增模組都有明確的驅動力，而非預先設計：

v0.28.0（初建期）：四個函式重複 → 建立四個共用模組。

v0.31.0（成熟期）：Hook 數量從 7 個成長到 40+ 個，新的重複模式浮現：

1. 日誌系統分裂：hook_logging.py 和 common_functions.setup_hook_logging 兩套實作並存，40+ 個 Hook 各自選用。最終建立 hook_utils.py 統一取代
2. 訊息散落各處：19 個 Hook 各自硬編碼使用者訊息 → 建立 hook_messages.py 集中管理

這驗證了「至少重複兩次再抽取」的 Rule of Three 原則：模組是在真實需求驅動下自然長出來的。

漸進遷移策略

共用庫建立後，需要將現有使用者逐步遷移。「一次全改」風險太高，以下是 W22 遷移 40+ 個 Hook 到新日誌系統的實戰策略。

分批遷移計畫

每個 Hook 的遷移步驟

 1# === 步驟 1：替換 import ===
 2# 遷移前
 3from lib.common_functions import setup_hook_logging
 4# 遷移後
 5from hook_utils import setup_hook_logging
 6
 7# === 步驟 2：包裹主函式 ===
 8# 遷移前
 9if __name__ == "__main__":
10    try:
11        main()
12    except Exception as e:
13        logger.error(f"執行失敗: {e}")
14        sys.exit(1)
15# 遷移後
16from hook_utils import run_hook_safely
17if __name__ == "__main__":
18    sys.exit(run_hook_safely(main, "my-hook"))
19
20# === 步驟 3：驗證 ===
21uv run python hook-name.py < /dev/null

為什麼分批而非一次全改

遷移陷阱：IMP-005

模組遷移最常見的陷阱是 import 路徑未同步更新。這個問題在系統中發生過兩次，我們將其記錄為 Error Pattern IMP-005。

症狀

模組從目錄 A 移到目錄 B 後，部分使用者的 import 忘記更新：

1# 遷移前（同目錄）
2from common_functions import hook_output  # OK
3
4# 遷移後（模組移到 lib/，但 import 未更新）
5from common_functions import hook_output  # ModuleNotFoundError!
6
7# 正確的遷移後 import
8from lib.common_functions import hook_output  # OK

為什麼容易遺漏

1. py_compile 不偵測 import 問題：只檢查語法，不解析模組路徑
2. 部分 Hook 不常觸發：SessionStart Hook 只在啟動時執行，測試不容易覆蓋
3. 多源錯誤疊加：多個 Hook 同時報錯，修完幾個就以為全部修好

遷移前強制檢查清單

1# 1. 列出所有引用舊路徑的檔案
2grep -r "from common_functions import" .claude/hooks/*.py
3
4# 2. 逐一更新每個引用者的 import 路徑
5
6# 3. 逐一驗證（不能只跑其中幾個！）
7for f in .claude/hooks/*.py; do
8    uv run python "$f" < /dev/null 2>&1 | grep -q "Error" && echo "FAIL: $f"
9done

Import 防護機制

在 Hook 入口加 try-except，讓 import 失敗時顯示具體原因：

1try:
2    from hook_utils import setup_hook_logging
3except ImportError as e:
4    print(f"[Hook Import Error] {Path(__file__).name}: {e}", file=sys.stderr)
5    sys.exit(1)

實際案例統計

v0.28.0 初建共用庫：

總計消除數百行重複程式碼。

v0.31.0 持續演進：

常見錯誤

錯誤 1：過早抽象

只用一次就抽出去是過度抽象。原則：至少重複兩次再抽取（Rule of Three）。

錯誤 2：強行統一

不同概念硬塞進同一個函式（靠 mode 參數切換）。解決：不同概念應該是不同的函式。

錯誤 3：忽略測試

重構時沒有先寫測試，導致引入新 bug。原則：先寫測試，確保重構不改變行為。

錯誤 4：遷移不徹底

模組搬家後只更新「自己知道的」使用處。原則：用 grep 列出所有引用，逐一更新並驗證（詳見 IMP-005）。

實作練習

練習 1：識別重複

找出以下程式碼的可抽取重複：

 1# file1.py
 2def process_user_data(user):
 3    if not user.get("name"):
 4        return {"error": "缺少姓名"}
 5    if not user.get("email"):
 6        return {"error": "缺少信箱"}
 7    return {"success": True, "data": user}
 8
 9# file2.py
10def process_order_data(order):
11    if not order.get("product"):
12        return {"error": "缺少商品"}
13    if not order.get("quantity"):
14        return {"error": "缺少數量"}
15    return {"success": True, "data": order}

 1def validate_required_fields(data: dict, required_fields: list) -> dict:
 2    """驗證必填欄位。"""
 3    for field in required_fields:
 4        if not data.get(field):
 5            return {"error": f"缺少{field}"}
 6    return {"success": True, "data": data}
 7
 8def process_user_data(user: dict) -> dict:
 9    return validate_required_fields(user, ["name", "email"])
10
11def process_order_data(order: dict) -> dict:
12    return validate_required_fields(order, ["product", "quantity"])

練習 2：規劃遷移策略

20 個 Hook 要從 from common_functions import setup_logging 遷移到 from hook_utils import setup_hook_logging，請規劃遷移策略。

 1# 1. 盤點
 2grep -rl "from common_functions import" .claude/hooks/*.py | wc -l
 3
 4# 2. 分批（按事件類型）
 5# 第一批：SessionStart hooks（啟動就能看到）
 6# 第二批：UserPromptSubmit hooks
 7# 第三批：PreToolUse / PostToolUse hooks
 8
 9# 3. 逐批執行，每批完成後 commit
10
11# 4. 全量掃描（不可省略！防止 IMP-005）
12grep -r "from common_functions import" .claude/hooks/*.py
13# 預期輸出：空

小結

• DRY 原則要求每個知識只有單一權威來源，用 grep 識別重複的函式定義
• 不要過早抽象，至少重複兩次再抽取（Rule of Three）
• 建立結構清晰的共用程式庫，重構前先寫測試確保行為不變
• 共用庫隨系統成長持續演進，大規模遷移採用分批策略
• 模組搬家後必須全量 grep 引用並逐一驗證，防止 IMP-005 陷阱

下一章：配置分離與常數管理

文件版本：v0.31.1 建立日期：2026-03-04

核心議題：高階函式是特定場景的自然解 — 當「流程固定、變化點單一且開放」時，把變化點抽成函式參數最省。要不要用它，由場景特徵決定。本文先論證這個場景為何適合 HOF，再比較同一 pattern 的兩種表達（裸函式型別 vs typedef）各自的優缺點。 案例骨幹：SettingsController.update(transform) — 9 個設定欄位共用同一條「取值→算新值→去重→通知」流程，唯一的變化是「改哪個欄位」。

1. 案例：一個收函式的設定更新方法

設定有 9 個欄位（字型、顏色、描邊、時間格式、目標螢幕、開機啟動…）。每個欄位變更都要走同一串流程：取當前設定 → 算出新設定 → 比對是否確實改變 → 賦回並通知 UI 重繪。把這串流程封裝成一個方法：

1class SettingsController extends ValueNotifier<SettingsModel> {
2  void update(SettingsModel Function(SettingsModel current) mutate) {
3    final SettingsModel next = mutate(value);
4    if (next != value) {
5      value = next;
6    }
7  }
8}

呼叫端只描述「改哪個欄位」：

1controller.update((s) => s.copyWith(fillColor: c));
2controller.update((s) => s.copyWith(fontSize: v));

update 收的這個參數本身是「一個函式」 — 把函式當成可傳遞的值。這就是 higher-order function。

簽章的型別與名字拆解

這個簽章的關鍵是分清「哪裡是型別、哪裡是名字」。它是一個普通的參數宣告，順序跟常見的 int count、Color color 一樣是 型別 名字，只是這次型別換成了較長的函式型別：

1void update(SettingsModel Function(SettingsModel current)  mutate)
2//          └──────────── 型別（函式型別）────────────┘  └名字┘

mutate 是這個參數的名字 — 方法內部靠它指涉傳進來的那個函式：

1void update(SettingsModel Function(SettingsModel current) mutate) {
2  final SettingsModel next = mutate(value);  // ← 用名字 mutate「呼叫」傳進來的函式
3}

容易混淆的是型別裡面那個 current：它和 mutate 不同層級 — current 只是函式型別內標記參數的名字，純文件性，寫成 SettingsModel Function(SettingsModel) 行為完全一樣，只是讓型別讀起來更清楚。換句話說，前半的函式型別規定「這個名字必須是什麼形狀的函式」，最後的 mutate 則是「這個函式參數叫什麼」。下一節先補 HOF 的基礎，第 4 節再回頭談「前半那串型別裸寫在簽章」造成的閱讀摩擦。

2. Higher-order function 是什麼（最小定義）

把函式當資料處理的函式 — 接收函式當參數，或回傳函式，符合其一即是。前提是語言把函式視為一等公民（first-class），能像變數一樣傳遞。Dart、JS、Kotlin、Swift 皆成立。

常見的 list.map((x) => x*2)、list.where((x) => x>0)、onPressed: () => ... 都屬此類。update((s) => ...) 是同一家族。

3. 為什麼這個場景適合用 HOF

這個場景有三個特徵，剛好對上 HOF 的強項 — HOF 適不適用，由這些特徵決定。

3.1 流程固定、變化點單一

9 個欄位的更新，流程 100% 相同（取值、去重、賦回、通知），唯一差異是中間那一步「copyWith(哪個欄位: 值)」。

當「共用流程」與「變化點」能這樣切乾淨時，HOF 正好對上這個結構：把固定流程寫死在 update 裡，把變化點抽成函式參數 transform 由呼叫端帶入。map 對「走訪迴圈（固定）+ 元素變換（變化）」做的是同一件事。

3.2 模型不可變，本來就是「current → next」

SettingsModel 是不可變物件（@immutable + 全 final）：要改 fillColor，得用 copyWith 產生新副本、再把整個物件替換回去。

也就是說，不可變模型下的更新，在語意上就是一個 (current) => next 的函式 — 拿舊值算出新值。用函式參數表達這件事，是最貼合的形狀。

3.3 變化點開放、難以列舉

「未來會改哪些欄位、怎麼組合」是開放的（可能同時改兩個欄位、可能有條件邏輯）。函式參數能表達任意轉換；若改用「enum 指定欄位 + switch」則被固定的列舉鎖死，每加一種改法都要動 update 內部。HOF 把「怎麼改」的決定權留在呼叫端，update 不需要知道。

反過來說，當「變化集合是封閉的、而且需要被序列化或跨層比對」時，enum + switch 反而較好 — 例如要把「使用者改了哪個欄位」存進 undo 堆疊、或透過網路傳給後端，列舉值是可序列化的資料，閉包不是。本案例的變化點純粹發生在呼叫端、不需要 persist，HOF 才站得住。所以「開放」算不算優點，要跟「變化是否需要被當資料搬運」一起看。

判準：流程固定 + 變化點單一 + 變化開放 三者同時成立時，HOF 幾乎總是比「列舉 + 分支」或「複製多個方法」更省。

對照反例放進具體場景更清楚。假設一個只有「深色模式開關」單一布林設定的 controller，更新邏輯就是 value = !value，既沒有共用流程、也沒有開放的變化點 — 這時把它包成收函式的 update，只是逼讀者解析一串函式型別去做一件 toggleDarkMode() 就講完的事，抽象成本大於收益。另一種反向情境是：9 個欄位看似共用流程，實際每個的更新路徑各不相同（有的要打 API、有的要寫檔、有的純記憶體），那麼「固定流程」的前提根本不成立，硬抽進 update 反而把三條不同的路徑塞進同一個殼裡。三條件少一條，具名方法通常更省 — 場景不對時硬用，才是過度設計。

4. 原始寫法的優缺點（裸函式型別）

1void update(SettingsModel Function(SettingsModel current) mutate) {
2  final SettingsModel next = mutate(value);
3  if (next != value) value = next;
4}

什麼是「函式型別裸寫在簽章」

這是整個討論的起點，值得單獨講清楚。把術語拆三個詞：

• 函式型別：描述「一個函式長什麼樣」的型別，例如 SettingsModel Function(SettingsModel current) — 收一個 SettingsModel、回傳一個 SettingsModel。
• 裸寫：把完整型別整串攤開寫出來，沒有先取名包裝（對比「裸數字 / magic number」直接寫 120 而非具名常數）。
• 在簽章：寫在方法的參數列（signature）裡。

合起來就是：把那串 SettingsModel Function(SettingsModel current) 原封不動塞進參數位，而不是先用 typedef 取個名字再引用。

1// 裸寫：函式型別整串長在簽章裡
2void update(SettingsModel Function(SettingsModel current) mutate)
3//          └────────── 這一整串就是「裸寫的函式型別」──────────┘

為什麼偏偏是「函式型別」會因為裸寫而卡住，一般型別卻不會？因為 int、Color 這類型別已經是短名稱，裸寫毫無負擔；而函式型別的完整語法 X Function(Y) 較長、巢狀時更難讀，讀者得當場在腦中解析「這是收什麼、回什麼的函式」。讀程式碼第一眼卡住的，正是這串裸寫的函式型別 — 它才是這篇要討論「要不要抽 typedef」的真正觸發點。下面的優缺點，都圍繞「裸寫 vs 取名」這個軸展開。

優點

• 型別就地可見：函式的形狀（收什麼、回什麼）直接寫在簽章上，讀者不必跳到別處查定義。
• 零額外宣告：不需要為了一個參數多定義一個型別別名。

缺點

• 簽章冗長、語法門檻：SettingsModel Function(SettingsModel current) 對不熟函式型別語法的人構成解析負擔，一眼難消化。
• 命名與語境矛盾：參數叫 mutate（變異／就地修改），但模型不可變、實際是「產生新副本」，名稱會誤導。
• 缺使用錨點：簽章沒有範例，第一次用的人不知道該傳什麼形狀的 lambda。

5. typedef 改寫後的優缺點

1/// 設定轉換規則：收當前設定、回傳改好的新設定（通常以 copyWith 實作）。
2typedef SettingsMutator = SettingsModel Function(SettingsModel current);
3
4/// 套用一條「目前設定 → 新設定」的轉換規則 …
5/// 範例：`controller.update((s) => s.copyWith(fillColor: c));`
6void update(SettingsMutator transform) {
7  final SettingsModel next = transform(value);
8  if (next != value) value = next;
9}

優點

• 簽章簡潔、概念命名：SettingsMutator 把函式型別升格成領域詞彙，認知從「解析 X Function(Y)」降到「讀一個名詞」。
• 命名精準：transform（轉換）貼合不可變語境，不再暗示就地修改。
• 有錨點：doc comment 的範例讓第一次使用者立即知道怎麼傳。
• 錯誤訊息更易讀：型別對不上時，編譯器印的是 SettingsMutator 這個名字，而不是整串 SettingsModel Function(SettingsModel)；裸寫版的錯誤訊息會把完整型別攤開，較難一眼定位。
• 可重用：同一個 SettingsMutator 型別若日後被多個 API 共用，定義集中一處。

缺點

• 多一層 indirection：想知道 transform 的確切型別，得跳到 typedef 定義；只看 update 簽章看不到形狀。
• 多一個命名負擔：SettingsMutator 本身要取得好；命名不當反而多一層要理解的東西。
• 對單一用途略顯重：若這個函式型別只在一處使用，typedef 的「集中重用」優點用不上，只剩「命名」一項收益。

6. 並排比較

關鍵：兩者是同一個 pattern（HOF + ValueNotifier）的兩種表達。取捨重點在「型別就地可見」對上「簽章簡潔 + 概念命名」—— 當函式型別會被多處使用、或語法門檻造成實際閱讀摩擦時，typedef 划算；若只用一次且團隊熟悉函式型別語法，裸寫也完全合理。

改寫的驗證也印證它停在「表達層」：呼叫端傳 lambda 不依賴參數名 → 零修改；行為不變；全套測試原封不動通過。

7. 收斂

• HOF 適合的場景特徵：流程固定 + 變化點單一 + 變化開放。三者齊備時，把變化點抽成函式參數最省；場景不符（欄位少、流程各異）則具名方法更直白。
• 不可變模型的更新本質就是 (current) => next，用函式參數表達是語意上最貼合的形狀。
• 兩種寫法的取捨：裸函式型別型別就地可見、零宣告；typedef 簽章簡潔、命名成概念、可重用，但多一層 indirection。
• 選擇依據：函式型別是否多處共用、語法是否造成實際閱讀摩擦。摩擦明顯就抽 typedef，否則裸寫無妨。

延伸：本文「模型不可變」段是整個 HOF 適配的前提之一。SettingsModel 那種 @immutable + copyWith 結構怎麼產生、以及更好懂的替代路徑，見 Freezed 的三層結構解剖。