Optimization on Tarragon

Flash Attention

Tue, 12 May 2026 00:00:00 +0000

Flash Attention 的核心概念是「重新組織 Attention 計算的順序、把中間結果留在 GPU 高速 cache、減少對 GPU memory 的讀寫往返」。它不改變 attention 的數學定義（輸出跟原始實作在浮點誤差範圍內一致）、但實作層面對長 context 推論吞吐有明顯提升、且是部分 KV cache 量化組合在 llama.cpp 上的必要前置。

概念位置

Flash Attention 在推論架構中的角色：

1推論時的 attention 計算：
2 ├── 原始實作：Q · K^T 整個算完、寫進 memory、再讀出來做 softmax、再算 · V
3 │ └── 多次 memory 讀寫、長 context 下 IO 成為瓶頸
4 └── Flash Attention：用 tiling 把計算切塊、中間結果留在 SRAM / register
5 └── 減少 memory 讀寫、長 context 加速明顯

跟 attention 變體的關係：

Flash Attention 是實作層的優化、跟 MHA / GQA / MLA 等架構層變體是兩個獨立維度。
不同變體都能搭配 Flash Attention 的實作技巧。

在 llama.cpp 中的旗標：

1llama-server -fa # 啟用 flash attention
2# 或
3llama-server --flash-attn

事實查核註：Flash Attention 的版本演進快（Flash Attention 1 / 2 / 3）、不同推論引擎的支援度依版本變化。具體限制（如「V cache Q4 量化要 -fa 才能啟用」）依 llama.cpp 版本變動、引用前以 llama-server --help 跟 release notes 為準。

設計責任

理解 Flash Attention 後可以解釋兩個現象：為什麼啟用 -fa 後長 context 推論速度提升明顯（IO bound 變 compute bound）、為什麼部分 KV cache 量化組合（如 V=Q4_0）在 llama.cpp 上需要 flash attention 才能跑（實作層面的耦合）。

工程實務上、啟用 flash attention 通常沒副作用（數學上等價、品質不變）、是 PC 場景長 context 推論的預設啟用旗標。詳見 5.2 KV cache 量化策略的 flash attention 段落。

Prefix Cache

Tue, 12 May 2026 00:00:00 +0000

Prefix Cache 的核心概念是「當多個請求共用相同的前綴 prompt（如同一 system prompt、同一 few-shot 範例）、把該前綴的 KV cache 算一次、後續請求共用、省下重複 prefill 算力」。是 production LLM 服務的常見優化、能大幅降低 latency 跟成本；但在多租戶場景下、跨租戶共用 prefix cache 是直接的隱私洩漏面。

概念位置

Prefix Cache 在推論流程中的角色：

1傳統推論：
2 Request A：system prompt + user A → 完整 prefill → 生成
3 Request B：system prompt + user B → 完整 prefill → 生成
4 ↑ 重複算 system prompt
5
6開啟 Prefix Cache：
7 Request A：system prompt + user A → prefill 整段、cache 共用 prefix
8 Request B：system prompt + user B → 重用 cache 的 system prefix + 只 prefill user B → 生成
9 ↑ 省下 system prompt 的 prefill 算力

效益對應的場景：

場景	效益
同 system prompt、不同 user message	prefill 算力大幅省
同 few-shot 例子、不同 query	prefill 算力大幅省
長 RAG context 共用、不同問題	prefill 算力大幅省
完全獨立的請求（無共用前綴）	無效益

主流推論引擎的支援度（依版本變化）：vLLM、SGLang、llama.cpp 等都有 prefix cache 機制、命名各異。

事實查核註：prefix cache 的命名、設定方式、tenant 隔離預設行為依推論引擎跟版本差異大、引用前以對應引擎的官方文件為準（如 vLLM Automatic Prefix Caching、SGLang RadixAttention 等）。

設計責任

理解 prefix cache 後可以解釋兩個現象：為什麼 production LLM 服務的 latency 在啟用 prefix cache 後大幅下降（system prompt 不再每次重算）、為什麼 prefix cache 在多租戶場景是隱私風險（A 租戶的 prefix 可能被 B 看到、見 llm-multi-tenant-isolation）。

production 設計時、prefix cache 應該按 tenant 分桶、同 tenant 內可共用、跨 tenant 必須隔離。隔離邊界對齊 tenant-boundary 卡片的設計。

8.1 並行處理實戰

Wed, 21 Jan 2026 00:00:00 +0000

本章將入門系列學到的 concurrent.futures 知識，應用於 .claude/lib 中的真實程式碼，展示如何識別並行化機會、實作並行版本，以及測量效能差異。

學習目標

完成本章後，你將能夠：

識別並行化機會：判斷一段程式碼是否適合並行化
應用 ThreadPoolExecutor：將循序處理改寫為並行版本
實作進度報告：使用 as_completed() 追蹤任務完成狀態
處理並行錯誤：避免單一任務失敗影響整體執行
測量效能差異：用數據證明優化效果

先備知識

本章假設你已經讀過入門系列的並行處理章節：

3.7 並行處理 - concurrent.futures 基本用法

如果你對 ThreadPoolExecutor、executor.map()、as_completed() 還不熟悉，建議先閱讀該章節。

識別並行化機會

I/O 密集 vs CPU 密集：快速判斷法

在入門系列中，我們學到 I/O 密集任務適合 ThreadPoolExecutor。但實際程式碼中，如何快速判斷？

問自己這個問題：程式在等什麼？

1# 模式 1：等待外部資源（I/O 密集）
2response = requests.get(url)      # 等網路
3content = file.read()             # 等磁碟
4result = cursor.execute(query)    # 等資料庫
5
6# 模式 2：純計算（CPU 密集）
7result = sum(i * i for i in range(10_000_000))  # 沒有等待，純運算

獨立任務的識別

並行化的前提是任務之間互相獨立。識別方法：

1獨立性檢查清單：
2[ ] 任務之間沒有共享可變狀態？
3[ ] 任務執行順序不影響結果？
4[ ] 任務 B 不依賴任務 A 的輸出？
5
6如果三個都勾選，就適合並行化。

真實案例：markdown_link_checker.py

讓我們看一個真實的例子。以下是 markdown_link_checker.py 中的 check_directory() 方法：

 1# 原始版本：循序處理
 2def check_directory(
 3    self,
 4    dir_path: str,
 5    recursive: bool = True
 6) -> List[LinkCheckResult]:
 7    """檢查目錄下所有 Markdown 檔案"""
 8    dir_path = self._resolve_path(dir_path)
 9
10    # 收集所有 .md 檔案
11    if recursive:
12        md_files = sorted(dir_path.rglob("*.md"))
13    else:
14        md_files = sorted(dir_path.glob("*.md"))
15
16    # 循序檢查每個檔案
17    results = []
18    for md_file in md_files:
19        results.append(self.check_file(str(md_file)))  # 一個接一個
20
21    return results

這段程式碼適合並行化嗎？讓我們用檢查清單分析：

問題	分析	結論
任務之間有共享狀態？	`results` 只在主執行緒操作	沒有
執行順序影響結果？	檢查檔案 A 不影響檔案 B	不影響
任務互相依賴？	每個檔案獨立檢查	不依賴
是 I/O 密集？	`check_file()` 讀取檔案內容	是

結論：非常適合並行化。

ThreadPoolExecutor 實戰

步驟 1：確認可並行化的函式

首先，確認被並行化的函式是「純函式」或至少沒有副作用：

 1def check_file(self, file_path: str) -> LinkCheckResult:
 2    """
 3    檢查單個 Markdown 檔案的連結
 4
 5    特性：
 6    - 輸入：檔案路徑
 7    - 輸出：檢查結果
 8    - 沒有修改外部狀態
 9    - 沒有依賴執行順序
10    """
11    # ... 實作省略

check_file() 滿足條件：

只讀取檔案，不修改
返回獨立的結果物件
不依賴其他檔案的結果

步驟 2：改寫為並行版本

 1from concurrent.futures import ThreadPoolExecutor, as_completed
 2
 3def check_directory_parallel(
 4    self,
 5    dir_path: str,
 6    recursive: bool = True,
 7    max_workers: int = 8
 8) -> List[LinkCheckResult]:
 9    """並行檢查目錄下所有 Markdown 檔案"""
10    dir_path = self._resolve_path(dir_path)
11
12    # 收集所有 .md 檔案
13    if recursive:
14        md_files = sorted(dir_path.rglob("*.md"))
15    else:
16        md_files = sorted(dir_path.glob("*.md"))
17
18    # 並行檢查
19    results = []
20    with ThreadPoolExecutor(max_workers=max_workers) as executor:
21        # 提交所有任務
22        futures = {
23            executor.submit(self.check_file, str(md_file)): md_file
24            for md_file in md_files
25        }
26
27        # 收集結果
28        for future in as_completed(futures):
29            results.append(future.result())
30
31    return results

步驟 3：選擇 max_workers

max_workers 的選擇影響效能：

 1import os
 2
 3# I/O 密集任務：可以設定較高
 4# 經驗法則：CPU 核心數的 2-4 倍
 5max_workers = min(32, (os.cpu_count() or 1) + 4)
 6
 7# 或根據檔案數量動態調整
 8def get_optimal_workers(file_count: int) -> int:
 9    """根據檔案數量決定 worker 數量"""
10    cpu_count = os.cpu_count() or 1
11
12    # 檔案少時不需要太多 worker
13    if file_count < 10:
14        return min(file_count, cpu_count)
15
16    # 檔案多時，I/O 密集可以多開一些
17    return min(32, cpu_count * 2)

為什麼 I/O 密集可以超過 CPU 核心數？

因為執行緒在等待 I/O 時會釋放 GIL，其他執行緒可以繼續執行。如果有 8 個核心，但每個任務有 80% 時間在等待 I/O，那開 16-32 個 worker 可以更充分利用 CPU。

進度報告與錯誤處理

使用 as_completed() 報告進度

as_completed() 返回一個迭代器，任務完成時立即 yield，適合顯示進度：

 1from concurrent.futures import ThreadPoolExecutor, as_completed
 2from typing import Callable, Optional
 3
 4def check_directory_with_progress(
 5    self,
 6    dir_path: str,
 7    recursive: bool = True,
 8    max_workers: int = 8,
 9    progress_callback: Optional[Callable[[int, int, str], None]] = None
10) -> List[LinkCheckResult]:
11    """
12    並行檢查目錄，支援進度回報
13
14    Args:
15        progress_callback: 回呼函式 (completed, total, current_file)
16    """
17    dir_path = self._resolve_path(dir_path)
18
19    if recursive:
20        md_files = list(dir_path.rglob("*.md"))
21    else:
22        md_files = list(dir_path.glob("*.md"))
23
24    total = len(md_files)
25    results = []
26
27    with ThreadPoolExecutor(max_workers=max_workers) as executor:
28        # 建立 future -> 檔案 的映射
29        futures = {
30            executor.submit(self.check_file, str(f)): f
31            for f in md_files
32        }
33
34        completed = 0
35        for future in as_completed(futures):
36            completed += 1
37            current_file = futures[future]
38
39            # 回報進度
40            if progress_callback:
41                progress_callback(completed, total, str(current_file))
42
43            results.append(future.result())
44
45    return results
46
47# 使用範例
48def print_progress(completed: int, total: int, current_file: str):
49    percent = (completed / total) * 100
50    print(f"\r[{completed}/{total}] {percent:.1f}% - {current_file}", end="")
51
52checker = MarkdownLinkChecker()
53results = checker.check_directory_with_progress(
54    "docs/",
55    progress_callback=print_progress
56)
57print()  # 換行

錯誤處理：不讓單一失敗拖垮全部

並行處理時，單一任務的異常不應該中斷其他任務：

 1def check_directory_robust(
 2    self,
 3    dir_path: str,
 4    max_workers: int = 8
 5) -> Tuple[List[LinkCheckResult], List[Dict]]:
 6    """
 7    並行檢查，分開返回成功結果和錯誤
 8
 9    Returns:
10        (成功的結果列表, 錯誤資訊列表)
11    """
12    dir_path = self._resolve_path(dir_path)
13    md_files = list(dir_path.rglob("*.md"))
14
15    results = []
16    errors = []
17
18    with ThreadPoolExecutor(max_workers=max_workers) as executor:
19        futures = {
20            executor.submit(self.check_file, str(f)): f
21            for f in md_files
22        }
23
24        for future in as_completed(futures):
25            file_path = futures[future]
26            try:
27                result = future.result()
28                results.append(result)
29            except Exception as e:
30                # 記錄錯誤，繼續處理其他檔案
31                errors.append({
32                    "file": str(file_path),
33                    "error": str(e),
34                    "type": type(e).__name__
35                })
36
37    return results, errors
38
39# 使用範例
40results, errors = checker.check_directory_robust("docs/")
41
42print(f"成功檢查 {len(results)} 個檔案")
43if errors:
44    print(f"有 {len(errors)} 個錯誤：")
45    for err in errors:
46        print(f"  {err['file']}: {err['error']}")

效能測量

使用 timeit 比較效能

理論上並行會更快，但「更快多少」需要測量：

 1import timeit
 2from pathlib import Path
 3
 4# 準備測試資料
 5test_dir = Path("docs/")  # 假設有 50+ 個 .md 檔案
 6checker = MarkdownLinkChecker()
 7
 8# 測量循序版本
 9def test_sequential():
10    return checker.check_directory(str(test_dir))
11
12sequential_time = timeit.timeit(test_sequential, number=3) / 3
13
14# 測量並行版本
15def test_parallel():
16    return checker.check_directory_parallel(str(test_dir), max_workers=8)
17
18parallel_time = timeit.timeit(test_parallel, number=3) / 3
19
20# 計算加速比
21speedup = sequential_time / parallel_time
22
23print(f"循序版本：{sequential_time:.2f} 秒")
24print(f"並行版本：{parallel_time:.2f} 秒")
25print(f"加速比：{speedup:.2f}x")

真實測試結果參考

以下是在不同檔案數量下的測試結果（供參考）：

檔案數量	循序時間	並行時間 (8 workers)	加速比
10	0.15s	0.08s	1.9x
50	0.72s	0.18s	4.0x
100	1.45s	0.32s	4.5x
200	2.91s	0.58s	5.0x

觀察：

檔案越多，並行效益越明顯
加速比不會無限增長（受限於 I/O 頻寬和 GIL）
檔案少於 10 個時，並行的額外開銷可能抵消效益

完整的效能測試腳本

 1#!/usr/bin/env python3
 2"""效能比較測試腳本"""
 3
 4import os
 5import sys
 6import time
 7from pathlib import Path
 8from concurrent.futures import ThreadPoolExecutor, as_completed
 9
10# 假設這是 markdown_link_checker 的簡化版
11class MarkdownChecker:
12    def check_file(self, file_path: str) -> dict:
13        """模擬檔案檢查（包含 I/O 延遲）"""
14        path = Path(file_path)
15        content = path.read_text(encoding="utf-8")
16        # 模擬一些處理時間
17        time.sleep(0.01)  # 10ms I/O 延遲
18        return {
19            "file": file_path,
20            "lines": len(content.splitlines()),
21            "chars": len(content)
22        }
23
24    def check_sequential(self, files: list) -> list:
25        """循序檢查"""
26        return [self.check_file(f) for f in files]
27
28    def check_parallel(self, files: list, max_workers: int = 8) -> list:
29        """並行檢查"""
30        results = []
31        with ThreadPoolExecutor(max_workers=max_workers) as executor:
32            futures = {executor.submit(self.check_file, f): f for f in files}
33            for future in as_completed(futures):
34                results.append(future.result())
35        return results
36
37def benchmark(func, *args, iterations: int = 3) -> float:
38    """測量函式執行時間"""
39    times = []
40    for _ in range(iterations):
41        start = time.perf_counter()
42        func(*args)
43        elapsed = time.perf_counter() - start
44        times.append(elapsed)
45    return sum(times) / len(times)
46
47def main():
48    # 收集測試檔案
49    test_dir = Path(".")  # 替換為你的目錄
50    files = list(test_dir.rglob("*.md"))[:100]  # 取前 100 個
51
52    if len(files) < 10:
53        print("需要至少 10 個 .md 檔案來測試")
54        sys.exit(1)
55
56    print(f"測試檔案數量：{len(files)}")
57
58    checker = MarkdownChecker()
59
60    # 測試不同 worker 數量
61    print("\n效能比較：")
62    print("-" * 50)
63
64    seq_time = benchmark(checker.check_sequential, files)
65    print(f"循序版本：{seq_time:.3f} 秒")
66
67    for workers in [2, 4, 8, 16]:
68        par_time = benchmark(checker.check_parallel, files, workers)
69        speedup = seq_time / par_time
70        print(f"並行 ({workers:2d} workers)：{par_time:.3f} 秒 ({speedup:.2f}x)")
71
72if __name__ == "__main__":
73    main()

什麼時候不該用並行？

反模式 1：檔案數量太少

1# 不好：只有 3 個檔案還用並行
2files = ["a.md", "b.md", "c.md"]
3with ThreadPoolExecutor(max_workers=8) as executor:
4    results = list(executor.map(check_file, files))
5
6# 問題：建立執行緒池的開銷可能比省下的時間還多

建議：檔案少於 5-10 個時，直接循序處理。

1def check_files_smart(files: list) -> list:
2    """根據檔案數量選擇處理方式"""
3    if len(files) < 10:
4        # 少量檔案：循序處理
5        return [check_file(f) for f in files]
6    else:
7        # 大量檔案：並行處理
8        with ThreadPoolExecutor(max_workers=8) as executor:
9            return list(executor.map(check_file, files))

反模式 2：任務之間有依賴

1# 不好：任務 B 依賴任務 A 的結果
2def process_a():
3    return fetch_config()
4
5def process_b(config):  # 需要 A 的結果
6    return validate(config)
7
8# 強行並行化會出錯或需要額外同步

反模式 3：共享可變狀態

 1# 不好：多個執行緒修改同一個列表
 2shared_results = []
 3
 4def bad_worker(file):
 5    result = check_file(file)
 6    shared_results.append(result)  # 競爭條件！
 7
 8# 正確做法：讓 worker 返回結果，由主執行緒收集
 9def good_worker(file):
10    return check_file(file)
11
12with ThreadPoolExecutor() as executor:
13    results = list(executor.map(good_worker, files))

反模式 4：CPU 密集任務用 ThreadPoolExecutor

 1# 不好：CPU 密集任務受 GIL 限制
 2def compute_heavy(n):
 3    return sum(i * i for i in range(n))
 4
 5# ThreadPoolExecutor 對 CPU 密集任務沒有加速效果
 6with ThreadPoolExecutor(max_workers=8) as executor:
 7    results = list(executor.map(compute_heavy, [10_000_000] * 8))
 8
 9# 正確：CPU 密集應該用 ProcessPoolExecutor
10from concurrent.futures import ProcessPoolExecutor
11
12with ProcessPoolExecutor(max_workers=8) as executor:
13    results = list(executor.map(compute_heavy, [10_000_000] * 8))

快速決策表

情境	推薦做法
< 10 個檔案	循序處理
10-100 個檔案，I/O 密集	ThreadPoolExecutor
> 100 個檔案，I/O 密集	ThreadPoolExecutor + 進度報告
CPU 密集計算	ProcessPoolExecutor
任務有依賴關係	重新設計，或用 asyncio

思考題

為什麼 check_directory_parallel() 中使用 as_completed() 而不是 executor.map()？ 提示：思考兩者在「錯誤處理」和「進度報告」上的差異。
如果 check_file() 除了讀檔還會寫入日誌檔，還適合並行化嗎？需要什麼額外措施？ 提示：考慮日誌寫入的執行緒安全性。
在 8 核心的機器上，為什麼 I/O 密集任務開 16 個 worker 可能比 8 個更快？ 提示：思考 GIL 和 I/O 等待時間的關係。

實作練習

修改 hook_validator.py：將 validate_all_hooks() 改寫為並行版本，測量效能差異。
實作超時機制：如果單一檔案檢查超過 5 秒，自動跳過並記錄警告。提示：查看 future.result(timeout=5)。
實作批次處理：當檔案超過 1000 個時，分批處理（每批 100 個），避免記憶體壓力。

案例：並行檔案檢查

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/markdown_link_checker.py，展示如何用 ThreadPoolExecutor 加速 I/O 密集的檔案檢查任務。

先備知識

8.1 並行處理實戰

問題背景

現有設計

markdown_link_checker.py 的 check_directory() 方法檢查目錄下所有 Markdown 檔案的內部連結：

 1def check_directory(
 2    self,
 3    dir_path: str,
 4    recursive: bool = True
 5) -> List[LinkCheckResult]:
 6    """
 7    檢查目錄下所有 Markdown 檔案
 8
 9    Args:
10        dir_path: 目錄路徑
11        recursive: 是否遞迴檢查子目錄
12
13    Returns:
14        list[LinkCheckResult]: 所有檔案的檢查結果
15    """
16    dir_path = self._resolve_path(dir_path)
17
18    if not dir_path.is_dir():
19        return [
20            LinkCheckResult(
21                file_path=str(dir_path),
22                total_links=0,
23                broken_links=[
24                    BrokenLink(
25                        file=str(dir_path),
26                        line=0,
27                        link_text="",
28                        link_target="",
29                        suggestion=f"目錄不存在: {dir_path}"
30                    )
31                ]
32            )
33        ]
34
35    # 收集所有 .md 檔案
36    if recursive:
37        md_files = sorted(dir_path.rglob("*.md"))
38    else:
39        md_files = sorted(dir_path.glob("*.md"))
40
41    # 循序檢查每個檔案
42    results = []
43    for md_file in md_files:
44        results.append(self.check_file(str(md_file)))
45
46    return results

這個設計的優點

簡單直覺：循序執行，程式碼容易理解
結果有序：檔案按排序順序處理，結果也按順序返回
除錯容易：問題發生時，可以精確定位到哪個檔案

效能瓶頸分析

讓我們分析 check_file() 方法的執行時間組成：

 1def check_file(self, file_path: str) -> LinkCheckResult:
 2    """檢查單個 Markdown 檔案的連結"""
 3    file_path = self._resolve_path(file_path)
 4
 5    # 1. 檢查檔案是否存在（I/O）
 6    if not file_path.exists():
 7        return LinkCheckResult(...)
 8
 9    # 2. 讀取檔案內容（I/O - 主要瓶頸）
10    try:
11        content = file_path.read_text(encoding="utf-8")
12    except Exception as e:
13        return LinkCheckResult(...)
14
15    # 3. 解析連結（CPU - 很快）
16    links = self.parse_markdown_links(content)
17
18    # 4. 過濾內部連結（CPU - 很快）
19    internal_links = self._filter_internal_links(links)
20
21    # 5. 檢查每個連結（I/O - 檔案系統檢查）
22    broken_links = []
23    for link in internal_links:
24        is_valid, suggestion = self._check_link(
25            link["target"],
26            file_path.parent
27        )
28        if not is_valid:
29            broken_links.append(...)
30
31    return LinkCheckResult(...)

時間分布估計：

1操作              | 類型  | 每檔案耗時
2-----------------|-------|----------
3read_text()      | I/O   | 1-5 ms
4parse_links()    | CPU   | 0.1 ms
5filter_links()   | CPU   | 0.01 ms
6check_link() x N | I/O   | N * 0.5 ms
7-----------------|-------|----------
8總計（10 連結）  |       | ~7 ms

對於 100 個檔案的專案：

1# 循序執行
2total_time = 100 * 7ms = 700ms = 0.7 秒
3
4# 這看起來不長，但如果：
5# - 檔案更多（500+ 個）
6# - 每個檔案連結更多
7# - 網路檔案系統（NFS）
8# 時間會快速增長

為什麼適合並行化？

I/O 密集：大部分時間花在檔案讀取和存在性檢查
任務獨立：每個檔案的檢查互不依賴
無共享狀態：不需要同步機制

進階解決方案

設計目標

提升效能：利用並行化加速 I/O 操作
保持 API 相容：不改變方法簽名和返回值
可配置：允許調整並行度

實作步驟

步驟 1：識別獨立任務

每個檔案的檢查是完全獨立的：

1# 這些操作可以同時執行
2result_1 = checker.check_file("doc1.md")  # 獨立
3result_2 = checker.check_file("doc2.md")  # 獨立
4result_3 = checker.check_file("doc3.md")  # 獨立

步驟 2：使用 ThreadPoolExecutor

 1from concurrent.futures import ThreadPoolExecutor, as_completed
 2from typing import List, Optional
 3
 4def check_directory_parallel(
 5    self,
 6    dir_path: str,
 7    recursive: bool = True,
 8    max_workers: Optional[int] = None
 9) -> List[LinkCheckResult]:
10    """
11    並行檢查目錄下所有 Markdown 檔案
12
13    Args:
14        dir_path: 目錄路徑
15        recursive: 是否遞迴檢查子目錄
16        max_workers: 最大工作執行緒數，預設為 CPU 核心數
17
18    Returns:
19        list[LinkCheckResult]: 所有檔案的檢查結果
20    """
21    dir_path = self._resolve_path(dir_path)
22
23    if not dir_path.is_dir():
24        return [self._create_error_result(dir_path, "目錄不存在")]
25
26    # 收集所有 .md 檔案
27    pattern = "**/*.md" if recursive else "*.md"
28    md_files = sorted(dir_path.glob(pattern) if not recursive
29                      else dir_path.rglob("*.md"))
30
31    if not md_files:
32        return []
33
34    # 使用 ThreadPoolExecutor 並行處理
35    results = []
36    with ThreadPoolExecutor(max_workers=max_workers) as executor:
37        # 提交所有任務
38        future_to_file = {
39            executor.submit(self.check_file, str(md_file)): md_file
40            for md_file in md_files
41        }
42
43        # 收集結果
44        for future in as_completed(future_to_file):
45            result = future.result()
46            results.append(result)
47
48    # 按檔案路徑排序（保持一致的輸出順序）
49    results.sort(key=lambda r: r.file_path)
50
51    return results

步驟 3：選擇 max_workers

max_workers 的選擇影響效能：

 1import os
 2
 3# 預設值：min(32, os.cpu_count() + 4)
 4# 這是 Python 3.8+ 的預設行為
 5
 6# 對於 I/O 密集任務，可以設定更高
 7def get_optimal_workers(file_count: int) -> int:
 8    """
 9    根據檔案數量計算最佳工作執行緒數
10
11    經驗法則：
12    - 檔案數 < 10: 使用檔案數
13    - 檔案數 >= 10: 使用 CPU 核心數 * 2，但不超過 32
14    """
15    cpu_count = os.cpu_count() or 4
16
17    if file_count < 10:
18        return file_count
19
20    return min(32, cpu_count * 2, file_count)

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3並行 Markdown 連結檢查器
  4
  5基於 markdown_link_checker.py，展示如何用 ThreadPoolExecutor 加速檔案檢查。
  6"""
  7
  8import os
  9import re
 10from concurrent.futures import ThreadPoolExecutor, as_completed
 11from dataclasses import dataclass, field
 12from pathlib import Path
 13from typing import Dict, List, Optional, Tuple
 14
 15@dataclass
 16class BrokenLink:
 17    """失效連結描述"""
 18    file: str
 19    line: int
 20    link_text: str
 21    link_target: str
 22    suggestion: str = ""
 23
 24@dataclass
 25class LinkCheckResult:
 26    """單個檔案的連結檢查結果"""
 27    file_path: str
 28    total_links: int
 29    broken_links: List[BrokenLink] = field(default_factory=list)
 30    is_valid: bool = True
 31
 32    def __post_init__(self):
 33        self.is_valid = len(self.broken_links) == 0
 34
 35class ParallelMarkdownLinkChecker:
 36    """
 37    並行 Markdown 連結檢查器
 38
 39    相較於原版的改進：
 40    - check_directory() 使用 ThreadPoolExecutor 並行處理
 41    - 支援自訂 max_workers
 42    - 保持 API 相容性
 43    """
 44
 45    INLINE_LINK_PATTERN = re.compile(r'(?)
 46    EXTERNAL_PATTERNS = [r'^https?://', r'^mailto:', r'^tel:', r'^ftp://']
 47
 48    def __init__(self, project_root: Optional[str] = None):
 49        if project_root is None:
 50            project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 51        self.project_root = Path(project_root)
 52
 53    # ===== 核心方法 =====
 54
 55    def check_file(self, file_path: str) -> LinkCheckResult:
 56        """
 57        檢查單個 Markdown 檔案的連結
 58
 59        這個方法是執行緒安全的，可以並行呼叫。
 60        """
 61        file_path = self._resolve_path(file_path)
 62
 63        if not file_path.exists():
 64            return LinkCheckResult(
 65                file_path=str(file_path),
 66                total_links=0,
 67                broken_links=[
 68                    BrokenLink(
 69                        file=str(file_path), line=0,
 70                        link_text="", link_target="",
 71                        suggestion=f"檔案不存在: {file_path}"
 72                    )
 73                ]
 74            )
 75
 76        try:
 77            content = file_path.read_text(encoding="utf-8")
 78        except Exception as e:
 79            return LinkCheckResult(
 80                file_path=str(file_path),
 81                total_links=0,
 82                broken_links=[
 83                    BrokenLink(
 84                        file=str(file_path), line=0,
 85                        link_text="", link_target="",
 86                        suggestion=f"無法讀取檔案: {e}"
 87                    )
 88                ]
 89            )
 90
 91        links = self._parse_links(content)
 92        internal_links = self._filter_internal_links(links)
 93
 94        broken_links = []
 95        for link in internal_links:
 96            is_valid, suggestion = self._check_link(
 97                link["target"], file_path.parent
 98            )
 99            if not is_valid:
100                broken_links.append(
101                    BrokenLink(
102                        file=str(file_path),
103                        line=link["line"],
104                        link_text=link["text"],
105                        link_target=link["target"],
106                        suggestion=suggestion
107                    )
108                )
109
110        return LinkCheckResult(
111            file_path=str(file_path),
112            total_links=len(internal_links),
113            broken_links=broken_links
114        )
115
116    def check_directory(
117        self,
118        dir_path: str,
119        recursive: bool = True,
120        max_workers: Optional[int] = None
121    ) -> List[LinkCheckResult]:
122        """
123        並行檢查目錄下所有 Markdown 檔案
124
125        Args:
126            dir_path: 目錄路徑
127            recursive: 是否遞迴檢查子目錄
128            max_workers: 最大工作執行緒數，None 表示使用預設值
129
130        Returns:
131            list[LinkCheckResult]: 所有檔案的檢查結果（按路徑排序）
132        """
133        dir_path = self._resolve_path(dir_path)
134
135        if not dir_path.is_dir():
136            return [
137                LinkCheckResult(
138                    file_path=str(dir_path),
139                    total_links=0,
140                    broken_links=[
141                        BrokenLink(
142                            file=str(dir_path), line=0,
143                            link_text="", link_target="",
144                            suggestion=f"目錄不存在: {dir_path}"
145                        )
146                    ]
147                )
148            ]
149
150        # 收集所有 .md 檔案
151        if recursive:
152            md_files = list(dir_path.rglob("*.md"))
153        else:
154            md_files = list(dir_path.glob("*.md"))
155
156        if not md_files:
157            return []
158
159        # 計算最佳工作執行緒數
160        if max_workers is None:
161            max_workers = self._get_optimal_workers(len(md_files))
162
163        # 並行處理
164        results: List[LinkCheckResult] = []
165
166        with ThreadPoolExecutor(max_workers=max_workers) as executor:
167            # 提交所有任務
168            future_to_file = {
169                executor.submit(self.check_file, str(f)): f
170                for f in md_files
171            }
172
173            # 收集結果（as_completed 提供最快的回應）
174            for future in as_completed(future_to_file):
175                try:
176                    result = future.result()
177                    results.append(result)
178                except Exception as e:
179                    # 處理意外錯誤
180                    md_file = future_to_file[future]
181                    results.append(
182                        LinkCheckResult(
183                            file_path=str(md_file),
184                            total_links=0,
185                            broken_links=[
186                                BrokenLink(
187                                    file=str(md_file), line=0,
188                                    link_text="", link_target="",
189                                    suggestion=f"檢查失敗: {e}"
190                                )
191                            ]
192                        )
193                    )
194
195        # 排序以保持一致的輸出順序
196        results.sort(key=lambda r: r.file_path)
197
198        return results
199
200    # ===== 循序版本（用於比較）=====
201
202    def check_directory_sequential(
203        self,
204        dir_path: str,
205        recursive: bool = True
206    ) -> List[LinkCheckResult]:
207        """循序版本，用於效能比較"""
208        dir_path = self._resolve_path(dir_path)
209
210        if not dir_path.is_dir():
211            return [
212                LinkCheckResult(
213                    file_path=str(dir_path),
214                    total_links=0,
215                    broken_links=[
216                        BrokenLink(
217                            file=str(dir_path), line=0,
218                            link_text="", link_target="",
219                            suggestion=f"目錄不存在: {dir_path}"
220                        )
221                    ]
222                )
223            ]
224
225        if recursive:
226            md_files = sorted(dir_path.rglob("*.md"))
227        else:
228            md_files = sorted(dir_path.glob("*.md"))
229
230        results = []
231        for md_file in md_files:
232            results.append(self.check_file(str(md_file)))
233
234        return results
235
236    # ===== 私有方法 =====
237
238    def _resolve_path(self, path: str) -> Path:
239        p = Path(path)
240        return p if p.is_absolute() else self.project_root / p
241
242    def _parse_links(self, content: str) -> List[Dict]:
243        links = []
244        in_code_block = False
245
246        for line_num, line in enumerate(content.split('\n'), start=1):
247            if line.strip().startswith("```"):
248                in_code_block = not in_code_block
249                continue
250
251            if in_code_block:
252                continue
253
254            for match in self.INLINE_LINK_PATTERN.finditer(line):
255                links.append({
256                    "text": match.group(1),
257                    "target": match.group(2),
258                    "line": line_num
259                })
260
261        return links
262
263    def _filter_internal_links(self, links: List[Dict]) -> List[Dict]:
264        internal = []
265        for link in links:
266            target = link["target"]
267            if target.startswith("#"):
268                continue
269            if any(re.match(p, target) for p in self.EXTERNAL_PATTERNS):
270                continue
271            internal.append(link)
272        return internal
273
274    def _check_link(
275        self,
276        target: str,
277        base_dir: Path
278    ) -> Tuple[bool, str]:
279        target_path = target.split("#")[0]
280        if not target_path:
281            return True, ""
282
283        resolved = (base_dir / target_path).resolve()
284        if resolved.exists():
285            return True, ""
286        else:
287            return False, f"檔案不存在: {target_path}"
288
289    def _get_optimal_workers(self, file_count: int) -> int:
290        """計算最佳工作執行緒數"""
291        cpu_count = os.cpu_count() or 4
292        if file_count < 10:
293            return file_count
294        return min(32, cpu_count * 2, file_count)
295
296# ===== 效能測量工具 =====
297
298def benchmark_checker(
299    dir_path: str,
300    iterations: int = 3
301) -> Dict[str, float]:
302    """
303    比較循序與並行版本的效能
304
305    Args:
306        dir_path: 要檢查的目錄
307        iterations: 執行次數（取平均）
308
309    Returns:
310        dict: {'sequential': 秒數, 'parallel': 秒數, 'speedup': 加速比}
311    """
312    import time
313
314    checker = ParallelMarkdownLinkChecker()
315
316    # 預熱（讓檔案系統快取生效）
317    checker.check_directory(dir_path)
318
319    # 測量循序版本
320    seq_times = []
321    for _ in range(iterations):
322        start = time.perf_counter()
323        checker.check_directory_sequential(dir_path)
324        seq_times.append(time.perf_counter() - start)
325
326    # 測量並行版本
327    par_times = []
328    for _ in range(iterations):
329        start = time.perf_counter()
330        checker.check_directory(dir_path)
331        par_times.append(time.perf_counter() - start)
332
333    seq_avg = sum(seq_times) / len(seq_times)
334    par_avg = sum(par_times) / len(par_times)
335
336    return {
337        "sequential": seq_avg,
338        "parallel": par_avg,
339        "speedup": seq_avg / par_avg if par_avg > 0 else 0
340    }
341
342# ===== 示範 =====
343
344if __name__ == "__main__":
345    import sys
346
347    # 預設檢查當前目錄
348    target_dir = sys.argv[1] if len(sys.argv) > 1 else "."
349
350    print(f"=== 並行 Markdown 連結檢查示範 ===\n")
351    print(f"目標目錄: {target_dir}\n")
352
353    checker = ParallelMarkdownLinkChecker()
354
355    # 執行檢查
356    results = checker.check_directory(target_dir)
357
358    # 統計
359    total_files = len(results)
360    total_links = sum(r.total_links for r in results)
361    broken_count = sum(len(r.broken_links) for r in results)
362    invalid_files = sum(1 for r in results if not r.is_valid)
363
364    print(f"檔案數: {total_files}")
365    print(f"連結數: {total_links}")
366    print(f"失效連結: {broken_count}")
367    print(f"有問題的檔案: {invalid_files}")
368
369    # 顯示失效連結
370    if broken_count > 0:
371        print(f"\n失效連結詳情:")
372        for result in results:
373            if not result.is_valid:
374                print(f"\n  {result.file_path}:")
375                for link in result.broken_links:
376                    print(f"    Line {link.line}: [{link.link_text}](/python-advanced/08-practical-optimization/case-studies/parallel-file-check/{link.link_target})")
377
378    # 效能比較
379    if total_files >= 5:
380        print(f"\n=== 效能比較 ===\n")
381        benchmark = benchmark_checker(target_dir)
382        print(f"循序版本: {benchmark['sequential']:.3f} 秒")
383        print(f"並行版本: {benchmark['parallel']:.3f} 秒")
384        print(f"加速比: {benchmark['speedup']:.2f}x")

效能測量

使用 timeit 比較前後效能：

 1import timeit
 2from parallel_link_checker import ParallelMarkdownLinkChecker
 3
 4def measure_performance(dir_path: str, num_runs: int = 5):
 5    """測量並比較循序與並行版本的效能"""
 6    checker = ParallelMarkdownLinkChecker()
 7
 8    # 循序版本
 9    seq_time = timeit.timeit(
10        lambda: checker.check_directory_sequential(dir_path),
11        number=num_runs
12    ) / num_runs
13
14    # 並行版本
15    par_time = timeit.timeit(
16        lambda: checker.check_directory(dir_path),
17        number=num_runs
18    ) / num_runs
19
20    print(f"目錄: {dir_path}")
21    print(f"循序版本: {seq_time:.4f} 秒")
22    print(f"並行版本: {par_time:.4f} 秒")
23    print(f"加速比: {seq_time / par_time:.2f}x")
24
25# 實際測試結果（範例）
26# 目錄: ./docs （50 個 .md 檔案）
27# 循序版本: 0.3521 秒
28# 並行版本: 0.0892 秒
29# 加速比: 3.95x

不同規模的預期加速比：

檔案數	循序時間	並行時間	加速比
10	70 ms	25 ms	2.8x
50	350 ms	90 ms	3.9x
100	700 ms	160 ms	4.4x
500	3.5 s	750 ms	4.7x

注意：實際加速比取決於檔案大小、連結數量、磁碟速度等因素。

設計權衡

面向	循序版本	並行版本
效能	較慢，線性增長	快 3-5 倍
複雜度	簡單	需要理解執行緒池
除錯	容易	需要注意執行緒安全
記憶體	較低	較高（執行緒開銷）
結果順序	保證有序	需要額外排序
錯誤處理	直接	需要處理 Future 例外

執行緒安全考量

check_file() 方法是執行緒安全的，因為：

無共享狀態：每次呼叫都獨立處理一個檔案
唯讀操作：只讀取檔案，不修改
獨立返回值：每個呼叫返回獨立的 LinkCheckResult

1# 這是安全的
2def check_file(self, file_path: str) -> LinkCheckResult:
3    # 所有變數都是區域變數
4    file_path = self._resolve_path(file_path)  # 新物件
5    content = file_path.read_text()            # 區域變數
6    links = self._parse_links(content)         # 區域變數
7    # ...
8    return LinkCheckResult(...)                # 新物件

什麼時候該用這個技術？

適合使用

多檔案處理：需要處理大量獨立檔案
I/O 密集：主要時間花在檔案讀寫
任務獨立：每個任務不依賴其他任務的結果
可接受亂序：或願意在最後排序

不建議使用

檔案很少：少於 5 個檔案，並行開銷可能大於收益
CPU 密集：如果主要時間花在計算，應考慮 ProcessPoolExecutor
有依賴關係：後續檔案依賴前面檔案的結果
記憶體受限：並行版本會同時載入多個檔案

練習

基礎練習

練習 1：加入進度回報

 1def check_directory_with_progress(
 2    self,
 3    dir_path: str,
 4    callback: callable = None
 5) -> List[LinkCheckResult]:
 6    """
 7    並行檢查，並在每個檔案完成時呼叫 callback
 8
 9    callback 簽名: callback(completed: int, total: int, result: LinkCheckResult)
10
11    提示：使用 as_completed() 在每個任務完成時觸發回報
12    """
13    # Your implementation here
14    pass

練習 2：支援取消

 1def check_directory_cancellable(
 2    self,
 3    dir_path: str,
 4    cancel_event: threading.Event = None
 5) -> List[LinkCheckResult]:
 6    """
 7    可取消的並行檢查
 8
 9    當 cancel_event.is_set() 時，停止提交新任務並返回已完成的結果
10
11    提示：在迴圈中檢查 cancel_event
12    """
13    # Your implementation here
14    pass

進階練習

練習 3：批次處理大型目錄

 1def check_directory_batched(
 2    self,
 3    dir_path: str,
 4    batch_size: int = 100
 5) -> List[LinkCheckResult]:
 6    """
 7    分批處理大型目錄
 8
 9    避免一次提交太多任務導致記憶體問題
10
11    提示：將檔案列表分成多個批次，依序處理每批
12    """
13    # Your implementation here
14    pass

練習 4：加入重試機制

 1def check_file_with_retry(
 2    self,
 3    file_path: str,
 4    max_retries: int = 3
 5) -> LinkCheckResult:
 6    """
 7    帶重試的檔案檢查
 8
 9    當檔案被鎖定或暫時不可用時自動重試
10
11    提示：捕捉特定例外，使用指數退避
12    """
13    # Your implementation here
14    pass

挑戰題

練習 5：實作並行度自動調整

 1class AdaptiveParallelChecker:
 2    """
 3    自動調整並行度的檢查器
 4
 5    根據系統負載和檢查速度動態調整 max_workers
 6
 7    功能：
 8    - 初始使用保守的 max_workers
 9    - 如果任務完成很快，增加 max_workers
10    - 如果系統負載高，減少 max_workers
11    - 記錄最佳 max_workers 供下次使用
12    """
13    # Your implementation here
14    pass

延伸閱讀

下一章：並行 Hook 驗證

2.2 微積分與最佳化

Mon, 11 May 2026 00:00:00 +0000

LLM 訓練的本質是「最佳化問題」：給定 loss function（預訓練用 cross-entropy、推導見 2.1 機率與資訊論）、找一組權重讓 loss 最小。微積分提供工具回答「往哪個方向調權重能讓 loss 變小」、最佳化演算法回答「具體怎麼一步一步調」。

寫 code 場景的使用者通常無需親自訓練、但理解這條鏈能解釋「為什麼 fine-tuning 要這麼多 GPU」「為什麼 learning rate 是關鍵 hyperparameter」「為什麼 gradient explosion 是常見問題」。本章整理核心概念、不展開完整推導。

本章目標

讀完本章後、你應該能：

解釋 gradient 在訓練中扮演的角色。
看到「learning rate = 1e-4」設定時、知道它控制什麼。
區分 SGD、Adam、AdamW 在訓練 LLM 時的取捨。
看到 gradient explosion / vanishing 報告時、知道發生在哪一層。

偏導數與 gradient：往哪個方向走 loss 變小

偏導數（partial derivative）的核心定義是「對多變數函式中的一個變數微分、其他變數視為常數」。記號 ∂f / ∂xᵢ。

Gradient（梯度）的核心定義是「所有偏導數打包成的向量」：

1∇f = (∂f/∂x₁, ∂f/∂x₂, ..., ∂f/∂xₙ)

幾何意義：gradient 指向「函式增加最快的方向」、長度等於該方向的變化率。要讓函式變小、就往 gradient 的反方向走。

LLM 訓練的核心步驟：

把訓練資料丟進模型、跑 forward pass、得到預測。
算 loss（預測跟真實答案的差距）。
對所有權重算 gradient：∇_W loss。
更新權重：W ← W - α · ∇_W loss（α 是 learning rate）。
回到第 1 步、重複數百萬次。

第 4 步的更新公式就是 gradient descent。整個流程的關鍵在 gradient 怎麼算出來。

Chain rule：把 gradient 從輸出傳到所有權重

Chain rule（連鎖律）的核心定義是「複合函式的導數等於各層導數的乘積」。一變數情況：

1若 z = f(g(x))、則 dz/dx = (df/dg) × (dg/dx)

多變數情況推廣到 chain rule 的矩陣形式（Jacobian）。

LLM 有數十億參數、每個參數都要算 gradient。Chain rule 讓「從 loss 倒推每個權重的 gradient」變成可計算的問題：

1loss
2 ↑ ∂loss/∂output
3output (last layer)
4 ↑ ∂output/∂layer_N_input × chain rule
5layer N
6 ↑ ...
7layer 1
8 ↑ ∂layer_1_input/∂W₁
9weights W₁

每層算「local gradient」（output 對 input 的導數）、chain rule 把它們乘起來、最終得到 loss 對每個權重的 gradient。這個流程叫 backpropagation（反向傳播）。

詳細展開見 3.0 神經網路基礎。

Learning Rate：每步走多遠

Learning rate（學習率）的核心定義是「gradient descent 每步更新的幅度」、記號 α 或 η。權重更新：

1W_new = W_old - learning_rate × gradient

Learning rate 的影響：

Learning rate	效果
太大	跨過最佳解、loss 震盪不收斂、甚至發散
適中	穩定下降、合理時間內收斂
太小	收斂太慢、訓練時間爆增、可能卡在 local minimum

LLM 訓練常用 learning rate：

預訓練（pre-training）：1e-4 ~ 3e-4、有 warmup 後線性衰減
Fine-tuning：1e-5 ~ 5e-5、較小避免破壞 pre-trained 權重
LoRA：1e-4 ~ 1e-3、只更新少量參數可較大

Learning rate 是訓練 LLM 最關鍵的 hyperparameter、設錯時整個訓練容易失敗、實務上極難救回。實務上常用 learning rate scheduler 動態調整：warmup + cosine decay 是最主流的組合。

SGD：最基本的最佳化演算法

SGD（Stochastic Gradient Descent、隨機梯度下降）的核心定義是「每次只用一小批資料（mini-batch）算 gradient、更新權重」。對應 vanilla gradient descent（用全部資料算一次）的計算成本問題：

Batch GD：每步用全部訓練資料、gradient 準但每步成本高、適合小資料集
SGD（mini-batch）：每步用 32 ~ 256 筆、gradient 有 noise 但平均下來方向對、適合大資料集

LLM 預訓練資料動輒 TB 級、每步只能用 mini-batch；每個 token 算一次 forward + backward、跑數兆 token、總更新數十萬到數百萬步。

Vanilla SGD 在 LLM 場景的缺點：

對 learning rate 敏感、不同 layer / 不同參數可能需要不同 learning rate。
在「狹長 loss surface」上震盪、收斂慢。
不利用過去 gradient 資訊。

SGD-with-momentum 在 vanilla SGD 上補了「過去 gradient 累積成 velocity」、處理震盪問題、在 vision（ResNet、ImageNet 訓練）跟小規模 fine-tune 仍是合理選擇；Adam / AdamW 在 LLM 預訓練成主流的原因是「自適應 learning rate + per-parameter scale」更能對付 Transformer 的高維、稀疏 gradient 結構、大規模 transformer 預訓練幾乎全部用 AdamW。

Adam 與 AdamW：適應性最佳化

Adam（Adaptive Moment Estimation）的核心定義是「每個參數有自己的有效 learning rate、根據過去 gradient 的一階矩跟二階矩自動調整」。簡化版本：

1m_t = β₁ × m_{t-1} + (1 - β₁) × gradient   ← 一階矩（gradient 的指數移動平均）
2v_t = β₂ × v_{t-1} + (1 - β₂) × gradient²  ← 二階矩（gradient 平方的指數移動平均）
3update = learning_rate × m_t / (sqrt(v_t) + ε)

直覺：

一階矩 m：類似動量、讓更新方向有慣性、減少震盪。
二階矩 v：估計 gradient 大小、把更新除以 sqrt(v)、自動調整每個參數的有效步幅。
結果：高 gradient 的參數步小、低 gradient 的參數步大、整體穩定收斂。

AdamW 是 Adam 的改進版、把 weight decay（L2 正則化）跟 gradient update 解耦。大規模 transformer 預訓練幾乎都用 AdamW、vanilla Adam 已退出 LLM 主流（SGD-with-momentum 在 vision 跟小規模 fine-tune 仍適用）。

代價：Adam / AdamW 需要為每個參數額外存 m（一階矩、gradient 的指數移動平均）跟 v（二階矩、gradient 平方的指數移動平均）、記憶體成本是 SGD 的 3 倍。31B 模型用 AdamW 訓練的 optimizer state 約佔 200GB+ 記憶體、拆解如下（mixed-precision training、batch=1024 / 不含 activation checkpoint 的典型配置）：

fp32 master weights：31B × 4 bytes ≈ 124 GB
m（一階矩）：31B × 4 bytes ≈ 124 GB
v（二階矩）：31B × 4 bytes ≈ 124 GB
總計約 372 GB optimizer state、加上 activation 與 gradient buffer 後實際需求更高

對比推論時 Gemma 4 31B Q4 量化版約 18GB（含 KV cache、見 0.5 Apple Silicon 記憶體預算）、訓練需求是推論的 20 倍以上。這就是為什麼訓練 LLM 需要大量 GPU、推論可以在個人 Mac 上跑。

Gradient Explosion 與 Vanishing

Gradient explosion（梯度爆炸）的核心問題是「gradient 經過多層 chain rule 累積、變成天文數字、權重更新後完全爆掉」。常見於深度網路、特別是 RNN。

Gradient vanishing（梯度消失）的反面問題是「gradient 經過多層後變得幾乎為 0、深層 layer 學不到東西」。常見於用 sigmoid / tanh activation 的深度網路。

Transformer 為什麼能訓練深層網路：

Residual connection：跨層加上 x + f(x)、給 gradient 一條短路、避免 vanishing。
Layer normalization：每層 activation 重新正規化、避免數值爆炸。
適當的權重初始化：Xavier / Kaiming 初始化讓初始 forward pass 不爆。
Gradient clipping：訓練時把 gradient 的 norm 截斷在閾值內、避免 explosion。

詳細展開見 3.3 Transformer 架構。

Backpropagation：chain rule 在多層網路上的演算法名

Backpropagation（反向傳播）就是前面 chain rule 段講的「∂loss/∂W 倒推流程」在實作上的演算法名稱、不是另一個獨立概念。整體流程：forward pass 算 output 與 loss、backward pass 用 chain rule 從 loss 逐層倒推每個權重的 gradient、framework（PyTorch / MLX）的 autograd 自動完成 backward、開發者只需寫 forward。Autograd 跟 chain rule / backprop 是同個概念在不同抽象層級的展開。

為什麼推論不需要 backprop

寫 code 場景用 LLM 是「推論」而非「訓練」。推論只跑 forward pass、不算 gradient、不更新權重。所以：

記憶體需求低得多：推論不用存中間 activation（forward pass 結束就可丟）、不用存 optimizer state。Gemma 4 31B 推論約 18GB、訓練同個模型可能要 200GB+。
算力需求低得多：推論一個 token 要 1 次 forward pass、訓練一個 token 要 forward + backward = 約 3 次 forward 的成本。
沒有 learning rate / optimizer 等 hyperparameter：推論只有 temperature、top-p 等 sampling 參數。

這就是為什麼 32GB Mac 可以推論 31B 模型、訓練同個模型要動用整個 H100 cluster。

想看完整最佳化理論（凸最佳化、二階方法、Hessian、Newton’s method 等）、見 2.4 公開課推薦的 Stanford EE364 / CS229 等課程。

下一章：2.3 數值精度與量化的數學依據。

8.2 效能調優實戰

Wed, 21 Jan 2026 00:00:00 +0000

在入門系列中，我們學習了效能優化的原則和工具。本章將這些知識應用於 .claude/lib 的實際程式碼，展示如何從「發現問題」到「驗證效果」的完整流程。

學習目標

完成本章後，你將能夠：

使用 cProfile 分析真實程式碼的效能瓶頸
判斷哪些程式碼值得優化
應用正則表達式預編譯提升效能
使用 functools.lru_cache 實現有效的快取策略
根據查詢模式選擇適當的資料結構

先備知識

本章假設你已經閱讀：

入門系列 3.8 效能迷思與優化策略 - 效能測量工具與優化原則

如果你還不熟悉 cProfile、timeit 或「過早優化是萬惡之源」這句話的含義，請先閱讀入門系列。

效能分析流程

優化的正確流程是：

11. 測量基準效能
2       ↓
32. 找出瓶頸（cProfile）
4       ↓
53. 針對瓶頸優化
6       ↓
74. 驗證優化效果
8       ↓
95. 評估維護成本

最重要的原則：先測量，後優化。沒有測量數據的優化是盲目的。

真實案例：Hook 驗證器

我們以 .claude/lib/hook_validator.py 為例。這個工具用來驗證 Hook 腳本是否符合專案規範，核心功能是透過正則表達式檢查程式碼內容。

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 共用模組導入模式
 5    HOOK_IO_PATTERNS = [
 6        r"from\s+hook_io\s+import",
 7        r"from\s+lib\.hook_io\s+import",
 8    ]
 9
10    HOOK_LOGGING_PATTERNS = [
11        r"from\s+hook_logging\s+import",
12        r"from\s+lib\.hook_logging\s+import",
13    ]
14
15    # ... 更多模式 ...
16
17    def _has_import(self, content: str, patterns: list[str]) -> bool:
18        """檢查是否有符合任一模式的導入"""
19        return any(
20            re.search(pattern, content)
21            for pattern in patterns
22        )

這段程式碼有什麼效能問題？讓我們用 cProfile 來找出答案。

步驟 1：測量基準效能

首先，建立測試環境並測量原始版本的效能：

 1import cProfile
 2import pstats
 3import re
 4from pstats import SortKey
 5
 6def generate_test_content(num_lines: int = 500) -> str:
 7    """生成測試用的 Hook 腳本內容"""
 8    lines = [
 9        '#!/usr/bin/env python3',
10        '"""Test hook script"""',
11        'import os',
12        'import sys',
13        'from hook_io import read_hook_input, write_hook_output',
14        'from hook_logging import setup_hook_logging',
15        '',
16    ]
17
18    # 加入更多程式碼行
19    for i in range(num_lines):
20        if i % 10 == 0:
21            lines.append(f'def function_{i}():')
22            lines.append(f'    """Function {i}"""')
23        lines.append(f'    x_{i} = {i}')
24
25    return '\n'.join(lines)
26
27def benchmark_original(content: str, iterations: int = 100):
28    """測量原始版本的效能"""
29
30    # 原始實作：每次呼叫都重新編譯正則表達式
31    patterns = [
32        r"from\s+hook_io\s+import",
33        r"from\s+lib\.hook_io\s+import",
34    ]
35
36    def has_import_original(content: str, patterns: list[str]) -> bool:
37        return any(
38            re.search(pattern, content)
39            for pattern in patterns
40        )
41
42    # 執行效能分析
43    profiler = cProfile.Profile()
44    profiler.enable()
45
46    for _ in range(iterations):
47        has_import_original(content, patterns)
48
49    profiler.disable()
50
51    stats = pstats.Stats(profiler)
52    stats.sort_stats(SortKey.CUMULATIVE)
53    stats.print_stats(10)
54
55    return stats
56
57# 執行測試
58content = generate_test_content(1000)
59print("=== 原始版本效能 ===")
60benchmark_original(content)

執行後的輸出類似：

1=== 原始版本效能 ===
2         501 function calls in 0.0234 seconds
3
4   Ordered by: cumulative time
5
6   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
7      100    0.001    0.000    0.023    0.000 test.py:30(has_import_original)
8      200    0.022    0.000    0.022    0.000 {method 'search' of 're.Pattern'}
9      100    0.000    0.000    0.000    0.000 {built-in method builtins.any}

觀察結果：re.search 佔用了大部分時間。

步驟 2：找出瓶頸

從 cProfile 結果可以看到，re.search 被呼叫了 200 次（100 次迭代 x 2 個 pattern）。

問題在於：re.search(pattern, content) 每次呼叫時都會重新編譯正則表達式。

雖然 Python 的 re 模組有內部快取（最近使用的 pattern 會被快取），但：

快取有大小限制（預設 512 個）
查詢快取本身也有開銷
在 Hook 驗證器中有多達 20+ 個不同的 pattern

正則表達式預編譯

問題：重複編譯的開銷

來看 hook_validator.py 中的實際程式碼：

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 模式定義為字串列表
 5    HOOK_IO_PATTERNS = [
 6        r"from\s+hook_io\s+import",
 7        r"from\s+lib\.hook_io\s+import",
 8    ]
 9
10    HOOK_LOGGING_PATTERNS = [
11        r"from\s+hook_logging\s+import",
12        r"from\s+lib\.hook_logging\s+import",
13    ]
14
15    CONFIG_LOADER_PATTERNS = [
16        r"from\s+config_loader\s+import",
17        r"from\s+lib\.config_loader\s+import",
18    ]
19
20    GIT_UTILS_PATTERNS = [
21        r"from\s+git_utils\s+import",
22        r"from\s+lib\.git_utils\s+import",
23    ]
24
25    # 輸出函式使用模式
26    OUTPUT_PATTERNS = [
27        r"write_hook_output\s*\(",
28        r"create_pretooluse_output\s*\(",
29        r"create_posttooluse_output\s*\(",
30    ]
31
32    # 不推薦的輸出模式
33    BAD_OUTPUT_PATTERNS = [
34        r'print\s*\(\s*json\.dumps\s*\(',
35        r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\(',
36    ]
37
38    def _has_import(self, content: str, patterns: list[str]) -> bool:
39        """檢查是否有符合任一模式的導入"""
40        return any(
41            re.search(pattern, content)  # 每次都要編譯！
42            for pattern in patterns
43        )

每次呼叫 _has_import 時，所有 pattern 都會被重新處理。

解決方案：預編譯

將字串 pattern 改為預編譯的 re.Pattern 物件：

 1import re
 2from typing import Pattern
 3
 4class HookValidatorOptimized:
 5    """優化版 Hook 驗證器"""
 6
 7    # 預編譯的正則表達式模式
 8    HOOK_IO_PATTERNS: list[Pattern] = [
 9        re.compile(r"from\s+hook_io\s+import"),
10        re.compile(r"from\s+lib\.hook_io\s+import"),
11    ]
12
13    HOOK_LOGGING_PATTERNS: list[Pattern] = [
14        re.compile(r"from\s+hook_logging\s+import"),
15        re.compile(r"from\s+lib\.hook_logging\s+import"),
16    ]
17
18    CONFIG_LOADER_PATTERNS: list[Pattern] = [
19        re.compile(r"from\s+config_loader\s+import"),
20        re.compile(r"from\s+lib\.config_loader\s+import"),
21    ]
22
23    GIT_UTILS_PATTERNS: list[Pattern] = [
24        re.compile(r"from\s+git_utils\s+import"),
25        re.compile(r"from\s+lib\.git_utils\s+import"),
26    ]
27
28    OUTPUT_PATTERNS: list[Pattern] = [
29        re.compile(r"write_hook_output\s*\("),
30        re.compile(r"create_pretooluse_output\s*\("),
31        re.compile(r"create_posttooluse_output\s*\("),
32    ]
33
34    BAD_OUTPUT_PATTERNS: list[Pattern] = [
35        re.compile(r'print\s*\(\s*json\.dumps\s*\('),
36        re.compile(r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\('),
37    ]
38
39    def _has_import(self, content: str, patterns: list[Pattern]) -> bool:
40        """檢查是否有符合任一模式的導入"""
41        return any(
42            pattern.search(content)  # 直接使用預編譯的 pattern
43            for pattern in patterns
44        )

效能測量

比較預編譯和非預編譯的效能差異：

 1import re
 2import time
 3
 4def compare_regex_performance():
 5    """比較預編譯 vs 非預編譯的效能"""
 6
 7    content = generate_test_content(1000)
 8    iterations = 1000
 9
10    # 字串 pattern
11    str_patterns = [
12        r"from\s+hook_io\s+import",
13        r"from\s+lib\.hook_io\s+import",
14    ]
15
16    # 預編譯 pattern
17    compiled_patterns = [re.compile(p) for p in str_patterns]
18
19    # 測試 1：使用字串 pattern
20    start = time.perf_counter()
21    for _ in range(iterations):
22        any(re.search(p, content) for p in str_patterns)
23    str_time = time.perf_counter() - start
24
25    # 測試 2：使用預編譯 pattern
26    start = time.perf_counter()
27    for _ in range(iterations):
28        any(p.search(content) for p in compiled_patterns)
29    compiled_time = time.perf_counter() - start
30
31    print(f"字串 pattern:    {str_time:.4f}s")
32    print(f"預編譯 pattern:  {compiled_time:.4f}s")
33    print(f"加速比:          {str_time / compiled_time:.2f}x")
34
35compare_regex_performance()

典型輸出：

1字串 pattern:    0.1234s
2預編譯 pattern:  0.0987s
3加速比:          1.25x

在這個例子中，預編譯帶來約 20-30% 的效能提升。雖然不是「快 10 倍」的驚人結果，但：

改動成本極低：只需要加上 re.compile()
無風險：行為完全相同
累積效果：當有更多 pattern 時，效果更明顯

快取策略：lru_cache

適用場景

functools.lru_cache 適合用於：

純函式：相同輸入總是產生相同輸出
計算昂貴：函式執行需要較長時間
重複呼叫：同樣的參數會被多次呼叫

實作範例：分支保護檢查

來看 .claude/lib/git_utils.py 中的 is_protected_branch() 函式：

 1import fnmatch
 2
 3# 保護分支列表（支援 glob 模式）
 4PROTECTED_BRANCHES = [
 5    "main",
 6    "master",
 7    "develop",
 8    "release/*",
 9    "production",
10]
11
12def is_protected_branch(branch: str) -> bool:
13    """
14    檢查是否為保護分支
15
16    Args:
17        branch: 分支名稱
18
19    Returns:
20        bool: 如果是保護分支返回 True
21    """
22    for pattern in PROTECTED_BRANCHES:
23        if fnmatch.fnmatch(branch, pattern):
24            return True
25    return False

這個函式：

是純函式：相同的 branch 總是返回相同結果
會被重複呼叫：在 Hook 執行期間可能檢查同一個分支多次

加入 lru_cache

 1from functools import lru_cache
 2import fnmatch
 3
 4PROTECTED_BRANCHES = [
 5    "main",
 6    "master",
 7    "develop",
 8    "release/*",
 9    "production",
10]
11
12@lru_cache(maxsize=128)
13def is_protected_branch(branch: str) -> bool:
14    """
15    檢查是否為保護分支（帶快取）
16
17    Args:
18        branch: 分支名稱
19
20    Returns:
21        bool: 如果是保護分支返回 True
22    """
23    for pattern in PROTECTED_BRANCHES:
24        if fnmatch.fnmatch(branch, pattern):
25            return True
26    return False

快取命中率分析

 1from functools import lru_cache
 2import fnmatch
 3
 4@lru_cache(maxsize=128)
 5def is_protected_branch(branch: str) -> bool:
 6    for pattern in PROTECTED_BRANCHES:
 7        if fnmatch.fnmatch(branch, pattern):
 8            return True
 9    return False
10
11def analyze_cache_performance():
12    """分析快取命中率"""
13
14    # 模擬真實的呼叫模式
15    branches = [
16        "main", "main", "main",  # 重複檢查 main
17        "feat/new-feature",
18        "main",
19        "fix/bug-123",
20        "main",
21        "release/1.0",
22        "feat/new-feature",  # 重複
23    ]
24
25    # 清除快取統計
26    is_protected_branch.cache_clear()
27
28    for branch in branches:
29        result = is_protected_branch(branch)
30        print(f"檢查 {branch}: {result}")
31
32    # 查看快取統計
33    info = is_protected_branch.cache_info()
34    print(f"\n快取統計:")
35    print(f"  命中: {info.hits}")
36    print(f"  未命中: {info.misses}")
37    print(f"  命中率: {info.hits / (info.hits + info.misses) * 100:.1f}%")
38    print(f"  快取大小: {info.currsize}/{info.maxsize}")
39
40analyze_cache_performance()

輸出：

 1檢查 main: True
 2檢查 main: True
 3檢查 main: True
 4檢查 feat/new-feature: False
 5檢查 main: True
 6檢查 fix/bug-123: False
 7檢查 main: True
 8檢查 release/1.0: True
 9檢查 feat/new-feature: False
10
11快取統計:
12  命中: 5
13  未命中: 4
14  命中率: 55.6%
15  快取大小: 4/128

lru_cache 的注意事項

 1# 1. 參數必須是可雜湊的（hashable）
 2@lru_cache
 3def process(data: list):  # 錯誤！list 不可雜湊
 4    pass
 5
 6@lru_cache
 7def process(data: tuple):  # 正確，tuple 可雜湊
 8    pass
 9
10# 2. 注意快取大小
11@lru_cache(maxsize=None)  # 無限制，可能耗盡記憶體
12def expensive_function(x):
13    pass
14
15@lru_cache(maxsize=128)  # 建議設定合理上限
16def expensive_function(x):
17    pass
18
19# 3. 可以手動清除快取
20expensive_function.cache_clear()
21
22# 4. 查看快取統計
23info = expensive_function.cache_info()
24# CacheInfo(hits=10, misses=5, maxsize=128, currsize=5)

資料結構選擇

O(n) vs O(1) 的差異

在 hook_validator.py 中，檢查測試檔案是否存在：

 1def check_test_exists(self, hook_path: Path) -> list[ValidationIssue]:
 2    """檢查對應的測試檔案是否存在"""
 3    issues = []
 4
 5    hook_name = hook_path.stem
 6    test_name = f"test_{hook_name.replace('-', '_')}.py"
 7
 8    # 測試檔案可能在這些位置
 9    possible_test_paths = [
10        self.project_root / ".claude" / "lib" / "tests" / test_name,
11        self.project_root / ".claude" / "hooks" / "tests" / test_name,
12    ]
13
14    test_exists = any(p.exists() for p in possible_test_paths)
15    # ...

如果需要檢查多個檔案是否在某個集合中：

 1# 不好的做法：用 list，O(n) 查詢
 2existing_tests = [
 3    "test_branch_verify.py",
 4    "test_hook_io.py",
 5    "test_config_loader.py",
 6    # ... 可能有幾十個
 7]
 8
 9def has_test_slow(test_name: str) -> bool:
10    return test_name in existing_tests  # O(n)
11
12# 好的做法：用 set，O(1) 查詢
13existing_tests_set = {
14    "test_branch_verify.py",
15    "test_hook_io.py",
16    "test_config_loader.py",
17    # ...
18}
19
20def has_test_fast(test_name: str) -> bool:
21    return test_name in existing_tests_set  # O(1)

真實案例：測試檔案存在性檢查

 1import time
 2from pathlib import Path
 3
 4def compare_data_structures():
 5    """比較 list vs set 的查詢效能"""
 6
 7    # 模擬測試檔案列表
 8    test_files_list = [f"test_hook_{i}.py" for i in range(100)]
 9    test_files_set = set(test_files_list)
10
11    # 要查詢的檔案
12    queries = [f"test_hook_{i}.py" for i in range(50, 150)]  # 50 個存在，50 個不存在
13
14    iterations = 10000
15
16    # 測試 list
17    start = time.perf_counter()
18    for _ in range(iterations):
19        for q in queries:
20            _ = q in test_files_list
21    list_time = time.perf_counter() - start
22
23    # 測試 set
24    start = time.perf_counter()
25    for _ in range(iterations):
26        for q in queries:
27            _ = q in test_files_set
28    set_time = time.perf_counter() - start
29
30    print(f"List 查詢: {list_time:.4f}s")
31    print(f"Set 查詢:  {set_time:.4f}s")
32    print(f"加速比:    {list_time / set_time:.1f}x")
33
34compare_data_structures()

輸出：

1List 查詢: 0.8234s
2Set 查詢:  0.0123s
3加速比:    66.9x

當資料量為 100 個元素時，set 比 list 快約 60-70 倍。隨著資料量增加，差距會更大。

何時使用哪種資料結構

操作	list	set	dict
查詢元素是否存在	O(n)	O(1)	O(1)
依索引存取	O(1)	N/A	N/A
依鍵存取	N/A	N/A	O(1)
保持順序	Yes	No*	Yes**
允許重複	Yes	No	Keys: No

* Python 3.7+ 的 set 實際上保持插入順序，但這是實作細節，不是語言保證。 ** Python 3.7+ 的 dict 保證保持插入順序。

選擇指南：

需要頻繁查詢「是否存在」→ 用 set
需要依索引存取 → 用 list
需要鍵值對應 → 用 dict
需要去重 → 用 set

優化的代價

每個優化都有代價，需要評估是否值得。

維護成本

優化技術	效能提升	程式碼複雜度	維護成本
正則表達式預編譯	20-30%	低	低
lru_cache	視命中率而定	低	中（需注意快取失效）
list → set	數十倍	低	低
自訂資料結構	視情況	高	高

何時不該優化

 1# 不值得優化的情況
 2
 3# 1. 執行次數很少
 4def setup_once():
 5    """只在程式啟動時執行一次"""
 6    config = load_all_configs()  # 即使慢也只執行一次
 7    return config
 8
 9# 2. 已經夠快了
10def check_single_file(path: str) -> bool:
11    """檢查單一檔案是否存在"""
12    return Path(path).exists()  # 0.0001s，不需要優化
13
14# 3. I/O 才是真正的瓶頸
15def process_files(paths: list[str]):
16    for path in paths:
17        content = Path(path).read_text()  # 瓶頸在這裡
18        result = process(content)  # 這裡快 10 倍也沒用

優化前檢查清單

在優化之前，問自己：

這段程式碼是瓶頸嗎？ - 用 cProfile 確認
執行頻率高嗎？ - 每秒執行一次 vs 每天執行一次
優化後維護成本增加多少？ - 複雜度 vs 效能
有更簡單的解決方案嗎？ - 演算法改進 vs 微優化

思考題

在什麼情況下，預編譯正則表達式反而可能降低效能？
lru_cache 不適合用在什麼樣的函式上？
如果一個函式既需要快取，又需要在某些條件下強制重新計算，你會如何設計？
為什麼說「先測量，後優化」很重要？能舉一個反例嗎？

實作練習

練習 1：分析現有程式碼

用 cProfile 分析你自己專案中的一段程式碼，找出效能瓶頸。

 1import cProfile
 2import pstats
 3from pstats import SortKey
 4
 5# 替換為你要分析的函式
 6def your_function():
 7    pass
 8
 9profiler = cProfile.Profile()
10profiler.enable()
11
12# 執行多次以獲得可靠數據
13for _ in range(100):
14    your_function()
15
16profiler.disable()
17stats = pstats.Stats(profiler)
18stats.sort_stats(SortKey.CUMULATIVE)
19stats.print_stats(10)

練習 2：實作帶統計的快取

擴展 lru_cache，加入更詳細的統計資訊：

 1from functools import wraps
 2from typing import Callable, TypeVar
 3from collections import defaultdict
 4import time
 5
 6T = TypeVar('T')
 7
 8def cached_with_stats(maxsize: int = 128):
 9    """
10    帶統計資訊的快取裝飾器
11
12    統計項目：
13    - 命中/未命中次數
14    - 平均執行時間
15    - 各參數的呼叫次數
16    """
17    def decorator(func: Callable[..., T]) -> Callable[..., T]:
18        # 你的實作
19        pass
20    return decorator

練習 3：效能比較

比較以下三種檢查字串是否包含多個關鍵字的方法：

 1keywords = ["error", "warning", "critical", "fatal"]
 2
 3# 方法 1：多個 in 檢查
 4def method1(text: str) -> bool:
 5    return any(kw in text for kw in keywords)
 6
 7# 方法 2：正則表達式
 8import re
 9pattern = re.compile("|".join(keywords))
10def method2(text: str) -> bool:
11    return bool(pattern.search(text))
12
13# 方法 3：set 交集
14keywords_set = set(keywords)
15def method3(text: str) -> bool:
16    words = set(text.lower().split())
17    return bool(words & keywords_set)
18
19# 測試並比較效能
20# ...

案例：並行 Hook 驗證

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_validator.py 的 validate_all_hooks() 方法，展示如何使用 ThreadPoolExecutor 配合 submit() + as_completed() 實現並行驗證，並加入即時進度報告功能。

先備知識

入門系列 3.7 並行處理
案例：並行檔案檢查（使用 map() 的基本並行模式）

問題背景

現有設計

hook_validator.py 的 validate_all_hooks() 方法需要驗證多個 Hook 檔案：

  1from dataclasses import dataclass, field
  2from pathlib import Path
  3from typing import Optional, List
  4import re
  5
  6@dataclass
  7class ValidationIssue:
  8    """驗證問題描述"""
  9    level: str  # "error" | "warning" | "info"
 10    message: str
 11    line: Optional[int] = None
 12    suggestion: Optional[str] = None
 13
 14@dataclass
 15class ValidationResult:
 16    """單個 Hook 的驗證結果"""
 17    hook_path: str
 18    issues: List[ValidationIssue] = field(default_factory=list)
 19    is_compliant: bool = True
 20
 21    def __post_init__(self):
 22        self.is_compliant = not any(
 23            issue.level == "error" for issue in self.issues
 24        )
 25
 26class HookValidator:
 27    """Hook 合規性驗證器"""
 28
 29    def validate_hook(self, hook_path: str) -> ValidationResult:
 30        """
 31        驗證單個 Hook 檔案
 32
 33        驗證項目：
 34        - 命名規範檢查
 35        - 共用模組導入檢查
 36        - 輸出格式檢查
 37        - 測試存在性檢查
 38        """
 39        hook_path = self._resolve_path(hook_path)
 40
 41        if not hook_path.exists():
 42            return ValidationResult(
 43                hook_path=str(hook_path),
 44                issues=[
 45                    ValidationIssue(
 46                        level="error",
 47                        message=f"Hook 檔案不存在: {hook_path}"
 48                    )
 49                ]
 50            )
 51
 52        # 讀取檔案並執行各項檢查
 53        try:
 54            with open(hook_path, "r", encoding="utf-8") as f:
 55                content = f.read()
 56        except Exception as e:
 57            return ValidationResult(
 58                hook_path=str(hook_path),
 59                issues=[
 60                    ValidationIssue(
 61                        level="error",
 62                        message=f"無法讀取 Hook 檔案: {e}"
 63                    )
 64                ]
 65            )
 66
 67        issues = []
 68        issues.extend(self.check_naming_convention(hook_path))
 69        issues.extend(self.check_lib_imports(content, hook_path))
 70        issues.extend(self.check_output_format(content))
 71        issues.extend(self.check_test_exists(hook_path))
 72
 73        return ValidationResult(hook_path=str(hook_path), issues=issues)
 74
 75    def validate_all_hooks(
 76        self,
 77        hooks_dir: Optional[str] = None
 78    ) -> List[ValidationResult]:
 79        """
 80        同步版本：依序驗證所有 Hook 檔案
 81        """
 82        if hooks_dir is None:
 83            hooks_dir = str(self.project_root / ".claude" / "hooks")
 84
 85        hooks_dir = self._resolve_path(hooks_dir)
 86
 87        if not hooks_dir.is_dir():
 88            return [
 89                ValidationResult(
 90                    hook_path=str(hooks_dir),
 91                    issues=[
 92                        ValidationIssue(
 93                            level="error",
 94                            message=f"Hook 目錄不存在: {hooks_dir}"
 95                        )
 96                    ]
 97                )
 98            ]
 99
100        # 找出所有 .py 檔案並依序驗證
101        results = []
102        for hook_file in sorted(hooks_dir.glob("*.py")):
103            if hook_file.name.startswith("_"):
104                continue
105            results.append(self.validate_hook(str(hook_file)))
106
107        return results

這個設計的優點

簡單直覺：循序執行，易於理解和除錯
結果有序：按檔案名稱排序，輸出一致
錯誤處理明確：每個驗證結果立即可用

這個設計的限制

當 Hook 數量增加時：

執行時間線性增長：20 個 Hook，每個 0.1 秒 = 2 秒
無法利用 I/O 等待時間：讀取檔案時 CPU 閒置
使用者體驗差：大量 Hook 時沒有進度回饋

 1import time
 2
 3def benchmark_sync(hook_files: list[Path]) -> float:
 4    """測量同步版本的執行時間"""
 5    validator = HookValidator()
 6    start = time.perf_counter()
 7
 8    for hook_file in hook_files:
 9        validator.validate_hook(str(hook_file))
10
11    return time.perf_counter() - start
12
13# 20 個 Hook，每個 0.1 秒
14# 總計：20 * 0.1 = 2.0 秒

進階解決方案

map() vs submit() + as_completed()

在「並行檔案檢查」案例中，我們使用 executor.map() 實現並行：

 1from concurrent.futures import ThreadPoolExecutor
 2
 3def validate_all_hooks_map(hook_files: list[Path]) -> list[ValidationResult]:
 4    """
 5    使用 map() 的並行版本
 6
 7    特點：
 8    - 結果按輸入順序返回
 9    - 必須等所有任務完成才能取得結果
10    - 無法即時報告進度
11    """
12    validator = HookValidator()
13
14    with ThreadPoolExecutor(max_workers=4) as executor:
15        results = list(executor.map(
16            validator.validate_hook,
17            [str(f) for f in hook_files]
18        ))
19
20    return results

map() 的限制：

無法即時取得結果：必須等待所有任務完成
無法追蹤進度：不知道哪些任務已完成
異常處理受限：遇到第一個異常就停止迭代

submit() + as_completed() 的優勢：

即時取得完成的結果：任務完成就能處理
支援進度報告：可以計算已完成數量
更靈活的異常處理：可以逐一處理每個任務的異常

 1from concurrent.futures import ThreadPoolExecutor, as_completed, Future
 2
 3def validate_all_hooks_async(
 4    hook_files: list[Path]
 5) -> list[ValidationResult]:
 6    """
 7    使用 submit() + as_completed() 的並行版本
 8
 9    特點：
10    - 結果按完成順序返回
11    - 可以即時報告進度
12    - 更完善的錯誤處理
13    """
14    validator = HookValidator()
15    results: list[ValidationResult] = []
16
17    with ThreadPoolExecutor(max_workers=4) as executor:
18        # 提交所有任務
19        future_to_path: dict[Future, Path] = {
20            executor.submit(validator.validate_hook, str(f)): f
21            for f in hook_files
22        }
23
24        # 依完成順序處理結果
25        for future in as_completed(future_to_path):
26            path = future_to_path[future]
27            try:
28                result = future.result()
29                results.append(result)
30            except Exception as e:
31                # 個別任務失敗不影響其他任務
32                results.append(ValidationResult(
33                    hook_path=str(path),
34                    issues=[ValidationIssue(
35                        level="error",
36                        message=f"驗證失敗: {e}"
37                    )]
38                ))
39
40    return results

實作進度報告

as_completed() 的核心優勢是支援即時進度報告：

 1from concurrent.futures import ThreadPoolExecutor, as_completed, Future
 2from typing import Callable, Optional
 3import sys
 4
 5def validate_all_hooks_with_progress(
 6    hook_files: list[Path],
 7    progress_callback: Optional[Callable[[int, int, str], None]] = None
 8) -> list[ValidationResult]:
 9    """
10    帶進度報告的並行驗證
11
12    Args:
13        hook_files: Hook 檔案列表
14        progress_callback: 進度回調函式
15            - 參數: (已完成數, 總數, 當前檔案名)
16
17    Returns:
18        list[ValidationResult]: 驗證結果列表
19    """
20    validator = HookValidator()
21    results: list[ValidationResult] = []
22    total = len(hook_files)
23
24    with ThreadPoolExecutor(max_workers=4) as executor:
25        # 提交所有任務，記錄 Future 到路徑的映射
26        future_to_path: dict[Future, Path] = {
27            executor.submit(validator.validate_hook, str(f)): f
28            for f in hook_files
29        }
30
31        # 依完成順序處理結果
32        for completed_count, future in enumerate(
33            as_completed(future_to_path),
34            start=1
35        ):
36            path = future_to_path[future]
37
38            try:
39                result = future.result()
40                results.append(result)
41            except Exception as e:
42                results.append(ValidationResult(
43                    hook_path=str(path),
44                    issues=[ValidationIssue(
45                        level="error",
46                        message=f"驗證失敗: {e}"
47                    )]
48                ))
49
50            # 呼叫進度回調
51            if progress_callback:
52                progress_callback(completed_count, total, path.name)
53
54    return results
55
56def print_progress(completed: int, total: int, filename: str) -> None:
57    """簡單的進度顯示"""
58    percentage = (completed / total) * 100
59    bar_length = 30
60    filled = int(bar_length * completed / total)
61    bar = "=" * filled + "-" * (bar_length - filled)
62
63    # \r 回到行首覆蓋顯示
64    sys.stdout.write(
65        f"\r[{bar}] {completed}/{total} ({percentage:.0f}%) - {filename}"
66    )
67    sys.stdout.flush()
68
69    if completed == total:
70        print()  # 完成後換行
71
72# 使用範例
73def demo_progress():
74    hooks_dir = Path(".claude/hooks")
75    hook_files = sorted(hooks_dir.glob("*.py"))
76
77    print("開始驗證 Hook 檔案...")
78    results = validate_all_hooks_with_progress(
79        hook_files,
80        progress_callback=print_progress
81    )
82
83    # 統計結果
84    compliant = sum(1 for r in results if r.is_compliant)
85    print(f"\n合規: {compliant}/{len(results)}")

進度報告的變體：

 1from dataclasses import dataclass
 2from datetime import datetime
 3from typing import Optional
 4
 5@dataclass
 6class ProgressInfo:
 7    """進度資訊"""
 8    completed: int
 9    total: int
10    current_file: str
11    elapsed_seconds: float
12    estimated_remaining: float
13
14class ProgressTracker:
15    """進度追蹤器"""
16
17    def __init__(self, total: int):
18        self.total = total
19        self.completed = 0
20        self.start_time = datetime.now()
21
22    def update(self, filename: str) -> ProgressInfo:
23        """更新進度並返回資訊"""
24        self.completed += 1
25        elapsed = (datetime.now() - self.start_time).total_seconds()
26
27        # 估算剩餘時間
28        if self.completed > 0:
29            avg_time = elapsed / self.completed
30            remaining = avg_time * (self.total - self.completed)
31        else:
32            remaining = 0
33
34        return ProgressInfo(
35            completed=self.completed,
36            total=self.total,
37            current_file=filename,
38            elapsed_seconds=elapsed,
39            estimated_remaining=remaining
40        )
41
42def validate_with_rich_progress(hook_files: list[Path]) -> list[ValidationResult]:
43    """
44    帶詳細進度資訊的驗證
45
46    顯示：完成數、百分比、已用時間、預估剩餘時間
47    """
48    validator = HookValidator()
49    results: list[ValidationResult] = []
50    tracker = ProgressTracker(len(hook_files))
51
52    with ThreadPoolExecutor(max_workers=4) as executor:
53        future_to_path = {
54            executor.submit(validator.validate_hook, str(f)): f
55            for f in hook_files
56        }
57
58        for future in as_completed(future_to_path):
59            path = future_to_path[future]
60
61            try:
62                result = future.result()
63                results.append(result)
64            except Exception as e:
65                results.append(ValidationResult(
66                    hook_path=str(path),
67                    issues=[ValidationIssue(
68                        level="error",
69                        message=f"驗證失敗: {e}"
70                    )]
71                ))
72
73            # 更新並顯示進度
74            info = tracker.update(path.name)
75            print_rich_progress(info)
76
77    return results
78
79def print_rich_progress(info: ProgressInfo) -> None:
80    """顯示詳細進度"""
81    percentage = (info.completed / info.total) * 100
82    bar_length = 20
83    filled = int(bar_length * info.completed / info.total)
84    bar = "=" * filled + "-" * (bar_length - filled)
85
86    elapsed_str = f"{info.elapsed_seconds:.1f}s"
87    remaining_str = f"{info.estimated_remaining:.1f}s"
88
89    sys.stdout.write(
90        f"\r[{bar}] {info.completed}/{info.total} "
91        f"({percentage:.0f}%) | "
92        f"已用: {elapsed_str} | "
93        f"剩餘: {remaining_str} | "
94        f"{info.current_file[:20]:<20}"
95    )
96    sys.stdout.flush()
97
98    if info.completed == info.total:
99        print()

錯誤處理策略

submit() + as_completed() 提供更細緻的錯誤處理：

  1from concurrent.futures import (
  2    ThreadPoolExecutor,
  3    as_completed,
  4    Future,
  5    TimeoutError as FuturesTimeoutError
  6)
  7from enum import Enum
  8from typing import Optional
  9
 10class ValidationStatus(Enum):
 11    SUCCESS = "success"
 12    FAILED = "failed"
 13    TIMEOUT = "timeout"
 14    CANCELLED = "cancelled"
 15
 16@dataclass
 17class DetailedResult:
 18    """包含狀態的詳細結果"""
 19    path: str
 20    status: ValidationStatus
 21    result: Optional[ValidationResult] = None
 22    error: Optional[str] = None
 23
 24def validate_with_error_handling(
 25    hook_files: list[Path],
 26    timeout_per_file: float = 5.0
 27) -> list[DetailedResult]:
 28    """
 29    帶完善錯誤處理的並行驗證
 30
 31    處理的錯誤類型：
 32    - 驗證邏輯錯誤
 33    - 單一任務超時
 34    - 任務被取消
 35
 36    Args:
 37        hook_files: Hook 檔案列表
 38        timeout_per_file: 單一檔案的超時秒數
 39
 40    Returns:
 41        list[DetailedResult]: 包含狀態的詳細結果
 42    """
 43    validator = HookValidator()
 44    detailed_results: list[DetailedResult] = []
 45
 46    with ThreadPoolExecutor(max_workers=4) as executor:
 47        future_to_path: dict[Future, Path] = {
 48            executor.submit(validator.validate_hook, str(f)): f
 49            for f in hook_files
 50        }
 51
 52        for future in as_completed(future_to_path):
 53            path = future_to_path[future]
 54
 55            try:
 56                # 設定單一結果的超時
 57                result = future.result(timeout=timeout_per_file)
 58                detailed_results.append(DetailedResult(
 59                    path=str(path),
 60                    status=ValidationStatus.SUCCESS,
 61                    result=result
 62                ))
 63
 64            except FuturesTimeoutError:
 65                detailed_results.append(DetailedResult(
 66                    path=str(path),
 67                    status=ValidationStatus.TIMEOUT,
 68                    error=f"驗證超時 ({timeout_per_file}s)"
 69                ))
 70
 71            except Exception as e:
 72                detailed_results.append(DetailedResult(
 73                    path=str(path),
 74                    status=ValidationStatus.FAILED,
 75                    error=str(e)
 76                ))
 77
 78    return detailed_results
 79
 80def summarize_results(results: list[DetailedResult]) -> dict:
 81    """彙總驗證結果"""
 82    summary = {
 83        "total": len(results),
 84        "success": 0,
 85        "failed": 0,
 86        "timeout": 0,
 87        "compliant": 0,
 88        "non_compliant": 0,
 89        "errors": []
 90    }
 91
 92    for r in results:
 93        if r.status == ValidationStatus.SUCCESS:
 94            summary["success"] += 1
 95            if r.result and r.result.is_compliant:
 96                summary["compliant"] += 1
 97            else:
 98                summary["non_compliant"] += 1
 99        elif r.status == ValidationStatus.TIMEOUT:
100            summary["timeout"] += 1
101            summary["errors"].append(f"{r.path}: {r.error}")
102        else:
103            summary["failed"] += 1
104            summary["errors"].append(f"{r.path}: {r.error}")
105
106    return summary

錯誤處理模式比較：

模式	`map()`	`as_completed()`
異常傳播	第一個異常就停止	可逐一處理
超時控制	只能設定全域超時	可設定單一任務超時
取消處理	較難實現	可以取消個別任務
部分結果	異常後無法取得	已完成的結果仍可取得

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3並行 Hook 驗證工具 - 完整範例
  4
  5展示如何用 ThreadPoolExecutor + as_completed 實現：
  6- 並行驗證多個 Hook 檔案
  7- 即時進度報告
  8- 完善的錯誤處理
  9"""
 10
 11from concurrent.futures import (
 12    ThreadPoolExecutor,
 13    as_completed,
 14    Future,
 15    TimeoutError as FuturesTimeoutError
 16)
 17from dataclasses import dataclass, field
 18from datetime import datetime
 19from enum import Enum
 20from pathlib import Path
 21from typing import Optional, List, Callable
 22import re
 23import sys
 24import time
 25
 26# ===== 資料結構 =====
 27
 28@dataclass
 29class ValidationIssue:
 30    """驗證問題描述"""
 31    level: str  # "error" | "warning" | "info"
 32    message: str
 33    line: Optional[int] = None
 34    suggestion: Optional[str] = None
 35
 36@dataclass
 37class ValidationResult:
 38    """單個 Hook 的驗證結果"""
 39    hook_path: str
 40    issues: List[ValidationIssue] = field(default_factory=list)
 41    is_compliant: bool = True
 42
 43    def __post_init__(self):
 44        self.is_compliant = not any(
 45            issue.level == "error" for issue in self.issues
 46        )
 47
 48class ValidationStatus(Enum):
 49    SUCCESS = "success"
 50    FAILED = "failed"
 51    TIMEOUT = "timeout"
 52
 53@dataclass
 54class DetailedResult:
 55    """包含狀態的詳細結果"""
 56    path: str
 57    status: ValidationStatus
 58    result: Optional[ValidationResult] = None
 59    error: Optional[str] = None
 60
 61# ===== 驗證器 =====
 62
 63class HookValidator:
 64    """Hook 合規性驗證器（簡化版）"""
 65
 66    HOOK_IO_PATTERNS = [
 67        r"from\s+hook_io\s+import",
 68        r"from\s+lib\.hook_io\s+import",
 69    ]
 70
 71    VALID_NAME_PATTERNS = [
 72        r"^[a-z0-9](/python-advanced/08-practical-optimization/case-studies/parallel-hook-validation/[a-z0-9\-_]*[a-z0-9])?\.py$",
 73    ]
 74
 75    def __init__(self, project_root: Optional[str] = None):
 76        if project_root is None:
 77            project_root = Path.cwd()
 78        self.project_root = Path(project_root)
 79
 80    def validate_hook(self, hook_path: str) -> ValidationResult:
 81        """驗證單個 Hook 檔案"""
 82        path = Path(hook_path)
 83
 84        if not path.exists():
 85            return ValidationResult(
 86                hook_path=str(path),
 87                issues=[
 88                    ValidationIssue(
 89                        level="error",
 90                        message=f"Hook 檔案不存在: {path}"
 91                    )
 92                ]
 93            )
 94
 95        try:
 96            with open(path, "r", encoding="utf-8") as f:
 97                content = f.read()
 98        except Exception as e:
 99            return ValidationResult(
100                hook_path=str(path),
101                issues=[
102                    ValidationIssue(
103                        level="error",
104                        message=f"無法讀取 Hook 檔案: {e}"
105                    )
106                ]
107            )
108
109        issues = []
110        issues.extend(self._check_naming(path))
111        issues.extend(self._check_imports(content))
112
113        return ValidationResult(hook_path=str(path), issues=issues)
114
115    def _check_naming(self, path: Path) -> List[ValidationIssue]:
116        """檢查命名規範"""
117        issues = []
118        if not any(
119            re.match(p, path.name)
120            for p in self.VALID_NAME_PATTERNS
121        ):
122            issues.append(ValidationIssue(
123                level="warning",
124                message=f"檔案名稱不符合規範: {path.name}"
125            ))
126        return issues
127
128    def _check_imports(self, content: str) -> List[ValidationIssue]:
129        """檢查導入規範"""
130        issues = []
131        if not any(
132            re.search(p, content)
133            for p in self.HOOK_IO_PATTERNS
134        ):
135            issues.append(ValidationIssue(
136                level="warning",
137                message="未導入 hook_io 模組"
138            ))
139        return issues
140
141# ===== 並行驗證 =====
142
143def validate_all_hooks_sync(
144    hook_files: List[Path]
145) -> List[ValidationResult]:
146    """
147    同步版本（基準對照）
148    """
149    validator = HookValidator()
150    results = []
151
152    for hook_file in hook_files:
153        results.append(validator.validate_hook(str(hook_file)))
154
155    return results
156
157def validate_all_hooks_map(
158    hook_files: List[Path],
159    max_workers: int = 4
160) -> List[ValidationResult]:
161    """
162    使用 map() 的並行版本
163    """
164    validator = HookValidator()
165
166    with ThreadPoolExecutor(max_workers=max_workers) as executor:
167        results = list(executor.map(
168            validator.validate_hook,
169            [str(f) for f in hook_files]
170        ))
171
172    return results
173
174def validate_all_hooks_async(
175    hook_files: List[Path],
176    max_workers: int = 4,
177    progress_callback: Optional[Callable[[int, int, str], None]] = None
178) -> List[ValidationResult]:
179    """
180    使用 submit() + as_completed() 的並行版本
181
182    Args:
183        hook_files: Hook 檔案列表
184        max_workers: 最大執行緒數
185        progress_callback: 進度回調 (completed, total, filename)
186
187    Returns:
188        驗證結果列表
189    """
190    validator = HookValidator()
191    results: List[ValidationResult] = []
192    total = len(hook_files)
193
194    with ThreadPoolExecutor(max_workers=max_workers) as executor:
195        # 提交所有任務
196        future_to_path: dict[Future, Path] = {
197            executor.submit(validator.validate_hook, str(f)): f
198            for f in hook_files
199        }
200
201        # 依完成順序處理
202        for completed, future in enumerate(
203            as_completed(future_to_path),
204            start=1
205        ):
206            path = future_to_path[future]
207
208            try:
209                result = future.result()
210                results.append(result)
211            except Exception as e:
212                results.append(ValidationResult(
213                    hook_path=str(path),
214                    issues=[ValidationIssue(
215                        level="error",
216                        message=f"驗證失敗: {e}"
217                    )]
218                ))
219
220            if progress_callback:
221                progress_callback(completed, total, path.name)
222
223    return results
224
225def validate_with_error_handling(
226    hook_files: List[Path],
227    max_workers: int = 4,
228    timeout_per_file: float = 5.0
229) -> List[DetailedResult]:
230    """
231    帶完善錯誤處理的並行驗證
232    """
233    validator = HookValidator()
234    detailed_results: List[DetailedResult] = []
235
236    with ThreadPoolExecutor(max_workers=max_workers) as executor:
237        future_to_path: dict[Future, Path] = {
238            executor.submit(validator.validate_hook, str(f)): f
239            for f in hook_files
240        }
241
242        for future in as_completed(future_to_path):
243            path = future_to_path[future]
244
245            try:
246                result = future.result(timeout=timeout_per_file)
247                detailed_results.append(DetailedResult(
248                    path=str(path),
249                    status=ValidationStatus.SUCCESS,
250                    result=result
251                ))
252            except FuturesTimeoutError:
253                detailed_results.append(DetailedResult(
254                    path=str(path),
255                    status=ValidationStatus.TIMEOUT,
256                    error=f"驗證超時 ({timeout_per_file}s)"
257                ))
258            except Exception as e:
259                detailed_results.append(DetailedResult(
260                    path=str(path),
261                    status=ValidationStatus.FAILED,
262                    error=str(e)
263                ))
264
265    return detailed_results
266
267# ===== 進度顯示 =====
268
269def print_progress(completed: int, total: int, filename: str) -> None:
270    """進度條顯示"""
271    percentage = (completed / total) * 100
272    bar_length = 30
273    filled = int(bar_length * completed / total)
274    bar = "=" * filled + "-" * (bar_length - filled)
275
276    sys.stdout.write(
277        f"\r[{bar}] {completed}/{total} ({percentage:.0f}%) - {filename:<30}"
278    )
279    sys.stdout.flush()
280
281    if completed == total:
282        print()
283
284# ===== 效能測試 =====
285
286def benchmark(hook_files: List[Path], iterations: int = 3) -> dict:
287    """
288    比較不同策略的執行時間
289    """
290    results = {}
291
292    # 同步版本
293    times = []
294    for _ in range(iterations):
295        start = time.perf_counter()
296        validate_all_hooks_sync(hook_files)
297        times.append(time.perf_counter() - start)
298    results["sync"] = sum(times) / len(times)
299
300    # map() 版本
301    times = []
302    for _ in range(iterations):
303        start = time.perf_counter()
304        validate_all_hooks_map(hook_files)
305        times.append(time.perf_counter() - start)
306    results["map"] = sum(times) / len(times)
307
308    # as_completed() 版本
309    times = []
310    for _ in range(iterations):
311        start = time.perf_counter()
312        validate_all_hooks_async(hook_files)
313        times.append(time.perf_counter() - start)
314    results["as_completed"] = sum(times) / len(times)
315
316    return results
317
318# ===== 示範 =====
319
320def demo():
321    """示範並行 Hook 驗證"""
322    print("=== 並行 Hook 驗證示範 ===\n")
323
324    # 建立測試用的 Hook 檔案
325    test_dir = Path("/tmp/test_hooks")
326    test_dir.mkdir(exist_ok=True)
327
328    hook_files = []
329    for i in range(20):
330        hook_file = test_dir / f"hook-{i:02d}.py"
331        hook_file.write_text(f'''#!/usr/bin/env python3
332"""Test hook {i}"""
333from hook_io import read_hook_input, write_hook_output
334
335def main():
336    data = read_hook_input()
337    write_hook_output({{"status": "ok"}})
338
339if __name__ == "__main__":
340    main()
341''')
342        hook_files.append(hook_file)
343
344    print(f"測試檔案數: {len(hook_files)}\n")
345
346    # 效能比較
347    print("1. 效能比較:")
348    times = benchmark(hook_files)
349    for strategy, elapsed in times.items():
350        print(f"   {strategy}: {elapsed:.3f}s")
351
352    speedup = times["sync"] / times["as_completed"]
353    print(f"   加速比: {speedup:.1f}x\n")
354
355    # 帶進度的驗證
356    print("2. 帶進度報告的驗證:")
357    results = validate_all_hooks_async(
358        hook_files,
359        progress_callback=print_progress
360    )
361
362    compliant = sum(1 for r in results if r.is_compliant)
363    print(f"\n   合規: {compliant}/{len(results)}")
364
365    # 清理測試檔案
366    for f in hook_files:
367        f.unlink()
368    test_dir.rmdir()
369
370if __name__ == "__main__":
371    demo()

效能測量

測試環境

Python 3.11
20 個 Hook 檔案
每個驗證包含：檔案讀取、正則匹配、路徑檢查

測試結果

策略	執行時間	加速比
同步 (基準)	0.85s	1.0x
map()	0.25s	3.4x
as_completed()	0.26s	3.3x
as_completed() + 進度	0.27s	3.1x

觀察：

map() 和 as_completed() 效能相近
進度報告的額外開銷約 3-5%
實際加速比接近 min(hook_count, max_workers)

不同檔案數量的效能

1Hook 數量    同步      並行(4)    加速比
2-----------------------------------------
35           0.21s     0.08s      2.6x
410          0.42s     0.14s      3.0x
520          0.85s     0.26s      3.3x
650          2.10s     0.58s      3.6x
7100         4.25s     1.12s      3.8x

加速比隨檔案數量增加而提升，趨近於 max_workers 數量。

設計權衡

map() vs as_completed() 選擇指南

1需要並行處理多個獨立任務？
2├── 是 → 需要即時進度報告？
3│        ├── 是 → 使用 submit() + as_completed()
4│        └── 否 → 需要細緻的錯誤處理？
5│                 ├── 是 → 使用 submit() + as_completed()
6│                 └── 否 → 使用 map()（更簡潔）
7└── 否 → 直接循序執行

比較表

面向	map()	submit() + as_completed()
程式碼複雜度	低	中
結果順序	保持輸入順序	按完成順序
進度報告	不支援	支援
異常處理	第一個異常就停止	可逐一處理
單一任務超時	不支援	支援
適用場景	批次處理，不需即時回饋	需要進度報告或細緻錯誤處理

進度報告的開銷

進度報告方式	額外開銷
無	0%
簡單計數器	~1%
進度條（無 flush）	~2%
進度條（每次 flush）	~5%
詳細進度（含時間估算）	~8%

對於大量任務（>100），建議每 N 個任務更新一次進度，而非每個任務都更新。

練習

練習 1：加入「跳過已驗證」功能

 1def validate_with_cache(
 2    hook_files: list[Path],
 3    cache: dict[str, ValidationResult]
 4) -> list[ValidationResult]:
 5    """
 6    只驗證快取中沒有的檔案
 7
 8    提示：
 9    - 檢查 cache 中是否已有結果
10    - 只對新檔案提交任務
11    - 合併快取結果和新結果
12    """
13    # Your implementation here
14    pass

練習 2：實作取消機制

 1def validate_with_cancel(
 2    hook_files: list[Path],
 3    should_cancel: Callable[[], bool]
 4) -> list[ValidationResult]:
 5    """
 6    支援取消的並行驗證
 7
 8    當 should_cancel() 返回 True 時，取消所有未完成的任務。
 9
10    提示：
11    - 使用 future.cancel() 取消未開始的任務
12    - 已開始的任務無法取消，需等待完成
13    - 返回已完成的結果
14    """
15    # Your implementation here
16    pass

練習 3：實作優先順序

 1def validate_with_priority(
 2    hook_files: list[Path],
 3    priority_fn: Callable[[Path], int]
 4) -> list[ValidationResult]:
 5    """
 6    按優先順序驗證
 7
 8    高優先順序的檔案先被驗證。
 9
10    提示：
11    - 按優先順序排序後提交
12    - 但 as_completed 仍按完成順序返回
13    - 考慮使用 PriorityQueue 控制提交順序
14    """
15    # Your implementation here
16    pass

挑戰題：實作可暫停/恢復的驗證

 1class PausableValidator:
 2    """
 3    可暫停和恢復的驗證器
 4
 5    使用方式：
 6        validator = PausableValidator(hook_files)
 7        validator.start()
 8        # ...
 9        validator.pause()  # 暫停，已提交的任務會完成
10        # ...
11        validator.resume()  # 恢復
12        results = validator.get_results()
13
14    提示：
15    - 使用 threading.Event 控制暫停
16    - 追蹤已完成和未開始的任務
17    - 恢復時只提交剩餘任務
18    """
19
20    def __init__(self, hook_files: list[Path]):
21        self._hook_files = hook_files
22        self._results: list[ValidationResult] = []
23        self._paused = False
24        # Your implementation here
25
26    def start(self) -> None:
27        pass
28
29    def pause(self) -> None:
30        pass
31
32    def resume(self) -> None:
33        pass
34
35    def get_results(self) -> list[ValidationResult]:
36        pass

延伸閱讀

上一章：並行檔案檢查 下一章：正則表達式預編譯

案例：記憶體優化

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/config_loader.py 的實際程式碼，展示如何用 __slots__ 和 weakref 優化記憶體使用。

先備知識

問題背景

現有設計

config_loader.py 使用全域字典作為快取，這是一個常見的設計模式：

 1# Global cache variables
 2_agents_config_cache: Optional[dict] = None
 3_quality_rules_cache: Optional[dict] = None
 4
 5def load_agents_config() -> dict:
 6    """
 7    載入代理人配置
 8
 9    使用模組層級變數作為快取，避免重複讀取檔案。
10    """
11    global _agents_config_cache
12    if _agents_config_cache is None:
13        try:
14            _agents_config_cache = load_config("agents")
15        except FileNotFoundError:
16            _agents_config_cache = _get_default_agents_config()
17    return _agents_config_cache
18
19def clear_config_cache() -> None:
20    """清除配置快取（用於測試或配置熱更新）"""
21    global _agents_config_cache, _quality_rules_cache
22    _agents_config_cache = None
23    _quality_rules_cache = None

這種設計簡單直觀，但當系統需要快取更複雜的物件時，會遇到記憶體問題。

記憶體問題

當快取大量物件時：

Python 字典有額外開銷：每個字典需要維護 hash table、keys、values
物件的 __dict__ 佔用記憶體：每個實例都有自己的屬性字典
快取可能導致記憶體洩漏：強引用阻止物件被回收

讓我們用一個更複雜的快取場景來說明問題：

 1import sys
 2
 3class ConfigItem:
 4    """配置項目，模擬複雜的快取物件"""
 5    def __init__(self, key: str, value: str, metadata: dict):
 6        self.key = key
 7        self.value = value
 8        self.metadata = metadata
 9        self.access_count = 0
10        self.last_accessed = None
11
12# Create a config item and measure memory
13item = ConfigItem("database.host", "localhost", {"type": "string"})
14
15# Object size
16print(f"ConfigItem size: {sys.getsizeof(item)} bytes")
17# ConfigItem size: 48 bytes
18
19# But the real cost is in __dict__
20print(f"__dict__ size: {sys.getsizeof(item.__dict__)} bytes")
21# __dict__ size: 184 bytes

當快取數萬個這樣的物件時，記憶體開銷會非常可觀。

進階解決方案

優化目標

減少每個物件的記憶體佔用
避免快取導致的記憶體洩漏
保持 API 不變

實作步驟

步驟 1：使用 `slots` 減少物件大小

__slots__ 告訴 Python 這個類別只會有哪些屬性，讓直譯器可以用更緊湊的方式儲存資料：

 1import sys
 2
 3class ConfigItemWithoutSlots:
 4    """標準類別，使用 __dict__"""
 5    def __init__(self, key: str, value: str, metadata: dict):
 6        self.key = key
 7        self.value = value
 8        self.metadata = metadata
 9        self.access_count = 0
10        self.last_accessed = None
11
12class ConfigItemWithSlots:
13    """使用 __slots__ 優化記憶體"""
14    __slots__ = ['key', 'value', 'metadata', 'access_count', 'last_accessed']
15
16    def __init__(self, key: str, value: str, metadata: dict):
17        self.key = key
18        self.value = value
19        self.metadata = metadata
20        self.access_count = 0
21        self.last_accessed = None
22
23# Compare memory usage
24item_without = ConfigItemWithoutSlots("db.host", "localhost", {"type": "str"})
25item_with = ConfigItemWithSlots("db.host", "localhost", {"type": "str"})
26
27print(f"Without __slots__: {sys.getsizeof(item_without)} bytes")
28print(f"With __slots__:    {sys.getsizeof(item_with)} bytes")
29
30# The real difference is __dict__
31print(f"__dict__ overhead: {sys.getsizeof(item_without.__dict__)} bytes")
32# item_with has no __dict__!
33try:
34    item_with.__dict__
35except AttributeError as e:
36    print(f"No __dict__: {e}")

記憶體結構比較

 1沒有 __slots__:
 2┌──────────────────────────────────┐
 3│ PyObject header         (16 B)   │
 4│ __dict__ 指標            (8 B)   │
 5│ __weakref__ 指標         (8 B)   │
 6│                                  │
 7│ __dict__ (separate object):      │
 8│   - hash table          (64 B)   │
 9│   - keys array          (40 B)   │
10│   - values array        (40 B)   │
11│   - key strings        (~80 B)   │
12│                                  │
13│ Total: ~256 bytes per object     │
14└──────────────────────────────────┘
15
16有 __slots__:
17┌──────────────────────────────────┐
18│ PyObject header         (16 B)   │
19│ key slot                 (8 B)   │
20│ value slot               (8 B)   │
21│ metadata slot            (8 B)   │
22│ access_count slot        (8 B)   │
23│ last_accessed slot       (8 B)   │
24│                                  │
25│ Total: ~56 bytes per object      │
26└──────────────────────────────────┘

大量物件的記憶體節省

 1import sys
 2import tracemalloc
 3
 4def measure_memory(cls, count=10000):
 5    """Measure memory for creating multiple objects"""
 6    tracemalloc.start()
 7
 8    objects = [
 9        cls(f"key_{i}", f"value_{i}", {"index": i})
10        for i in range(count)
11    ]
12
13    current, peak = tracemalloc.get_traced_memory()
14    tracemalloc.stop()
15
16    return current, peak, objects
17
18# Measure both classes
19mem_without, peak_without, _ = measure_memory(ConfigItemWithoutSlots)
20mem_with, peak_with, _ = measure_memory(ConfigItemWithSlots)
21
22print(f"Without __slots__: {mem_without / 1024 / 1024:.2f} MB")
23print(f"With __slots__:    {mem_with / 1024 / 1024:.2f} MB")
24print(f"Savings:           {(mem_without - mem_with) / 1024 / 1024:.2f} MB")
25print(f"Ratio:             {mem_without / mem_with:.1f}x")
26
27# Typical output:
28# Without __slots__: 3.82 MB
29# With __slots__:    1.15 MB
30# Savings:           2.67 MB
31# Ratio:             3.3x

步驟 2：使用 weakref 避免強引用

weakref 讓我們可以引用物件，但不阻止它被垃圾回收：

 1import weakref
 2
 3class CacheableConfig:
 4    """可以被弱引用的配置物件"""
 5    __slots__ = ['key', 'value', '_data', '__weakref__']  # Note: __weakref__ slot
 6
 7    def __init__(self, key: str, value: str):
 8        self.key = key
 9        self.value = value
10        self._data = None
11
12    def __repr__(self):
13        return f"CacheableConfig({self.key!r}, {self.value!r})"
14
15# Create object and weak reference
16config = CacheableConfig("app.name", "MyApp")
17weak_ref = weakref.ref(config)
18
19print(f"Object exists: {weak_ref()}")
20# Object exists: CacheableConfig('app.name', 'MyApp')
21
22# Delete the strong reference
23del config
24
25print(f"After del: {weak_ref()}")
26# After del: None

使用 callback 追蹤物件回收

 1import weakref
 2
 3def on_finalize(ref):
 4    """Callback when object is garbage collected"""
 5    print(f"Object was garbage collected!")
 6
 7config = CacheableConfig("db.port", "5432")
 8weak_ref = weakref.ref(config, on_finalize)
 9
10print("Deleting object...")
11del config
12# Output: Object was garbage collected!

步驟 3：使用 WeakValueDictionary

WeakValueDictionary 是實作自動清理快取的利器：

 1import weakref
 2from typing import Callable, TypeVar, Generic
 3
 4T = TypeVar('T')
 5
 6class WeakCache(Generic[T]):
 7    """
 8    Auto-cleaning cache using weak references.
 9
10    Objects are automatically removed from cache when no strong
11    references exist outside the cache.
12    """
13
14    def __init__(self):
15        self._cache: weakref.WeakValueDictionary[str, T] = (
16            weakref.WeakValueDictionary()
17        )
18        self._hits = 0
19        self._misses = 0
20
21    def get(self, key: str, factory: Callable[[], T]) -> T:
22        """
23        Get item from cache, creating it if necessary.
24
25        Args:
26            key: Cache key
27            factory: Function to create value if not cached
28
29        Returns:
30            Cached or newly created value
31        """
32        value = self._cache.get(key)
33        if value is not None:
34            self._hits += 1
35            return value
36
37        self._misses += 1
38        value = factory()
39        self._cache[key] = value
40        return value
41
42    def __len__(self) -> int:
43        return len(self._cache)
44
45    def stats(self) -> dict:
46        """Return cache statistics"""
47        total = self._hits + self._misses
48        hit_rate = self._hits / total if total > 0 else 0
49        return {
50            "hits": self._hits,
51            "misses": self._misses,
52            "hit_rate": f"{hit_rate:.1%}",
53            "size": len(self._cache),
54        }
55
56# Demo: automatic cleanup
57cache = WeakCache[CacheableConfig]()
58
59# Create and cache object
60config1 = cache.get("app.name", lambda: CacheableConfig("app.name", "MyApp"))
61config2 = cache.get("app.name", lambda: CacheableConfig("app.name", "MyApp"))  # Cache hit
62
63print(f"Cache size: {len(cache)}")  # 1
64print(f"Same object: {config1 is config2}")  # True
65print(f"Stats: {cache.stats()}")  # hits=1, misses=1
66
67# Delete strong reference
68del config1
69del config2
70
71# Object is garbage collected, cache is auto-cleaned
72import gc
73gc.collect()
74
75print(f"Cache size after cleanup: {len(cache)}")  # 0

步驟 4：測量記憶體使用

使用 sys.getsizeof 和 tracemalloc 進行精確測量：

 1import sys
 2import tracemalloc
 3from pympler import asizeof  # pip install pympler
 4
 5def measure_object_size(obj, label="Object"):
 6    """Measure object size using different methods"""
 7
 8    # Basic size (doesn't include referenced objects)
 9    basic = sys.getsizeof(obj)
10
11    # Deep size (includes all referenced objects)
12    # Using pympler for accurate measurement
13    deep = asizeof.asizeof(obj)
14
15    print(f"{label}:")
16    print(f"  sys.getsizeof: {basic:,} bytes")
17    print(f"  pympler deep:  {deep:,} bytes")
18
19    return basic, deep
20
21# Compare different object types
22item_without = ConfigItemWithoutSlots("key", "value", {"a": 1, "b": 2})
23item_with = ConfigItemWithSlots("key", "value", {"a": 1, "b": 2})
24
25measure_object_size(item_without, "Without __slots__")
26measure_object_size(item_with, "With __slots__")
27
28# Using tracemalloc for allocation tracking
29def track_allocations():
30    """Track memory allocations during execution"""
31    tracemalloc.start()
32
33    # Simulate creating many cached objects
34    items = []
35    for i in range(1000):
36        items.append(ConfigItemWithSlots(
37            f"config.item.{i}",
38            f"value_{i}",
39            {"index": i, "active": True}
40        ))
41
42    # Get snapshot
43    snapshot = tracemalloc.take_snapshot()
44    top_stats = snapshot.statistics('lineno')
45
46    print("\nTop 5 memory allocations:")
47    for stat in top_stats[:5]:
48        print(f"  {stat}")
49
50    # Get traced memory
51    current, peak = tracemalloc.get_traced_memory()
52    print(f"\nCurrent memory: {current / 1024:.1f} KB")
53    print(f"Peak memory:    {peak / 1024:.1f} KB")
54
55    tracemalloc.stop()
56    return items
57
58track_allocations()

比較記憶體差異的完整腳本

 1import sys
 2import gc
 3import tracemalloc
 4from dataclasses import dataclass
 5
 6class StandardConfig:
 7    """Standard class with __dict__"""
 8    def __init__(self, key, value, metadata):
 9        self.key = key
10        self.value = value
11        self.metadata = metadata
12        self.hits = 0
13
14class SlottedConfig:
15    """Optimized with __slots__"""
16    __slots__ = ['key', 'value', 'metadata', 'hits']
17
18    def __init__(self, key, value, metadata):
19        self.key = key
20        self.value = value
21        self.metadata = metadata
22        self.hits = 0
23
24@dataclass
25class DataclassConfig:
26    """Using dataclass"""
27    key: str
28    value: str
29    metadata: dict
30    hits: int = 0
31
32@dataclass(slots=True)  # Python 3.10+
33class SlottedDataclass:
34    """Dataclass with __slots__"""
35    key: str
36    value: str
37    metadata: dict
38    hits: int = 0
39
40def benchmark_memory(cls, count=10000, label=""):
41    """Benchmark memory usage for a class"""
42    gc.collect()
43    tracemalloc.start()
44
45    objects = [
46        cls(f"key_{i}", f"value_{i}", {"index": i})
47        for i in range(count)
48    ]
49
50    current, peak = tracemalloc.get_traced_memory()
51    tracemalloc.stop()
52
53    per_object = current / count
54    print(f"{label or cls.__name__:25} | "
55          f"{current/1024:8.1f} KB | "
56          f"{per_object:6.1f} B/obj")
57
58    return objects  # Keep reference to prevent GC
59
60print(f"{'Class':25} | {'Total':>10} | {'Per Object':>10}")
61print("-" * 55)
62
63benchmark_memory(StandardConfig)
64benchmark_memory(SlottedConfig)
65benchmark_memory(DataclassConfig)
66benchmark_memory(SlottedDataclass)
67
68# Typical output:
69# Class                     |      Total |  Per Object
70# -------------------------------------------------------
71# StandardConfig            |   2578.5 KB |  263.6 B/obj
72# SlottedConfig             |    859.4 KB |   87.9 B/obj
73# DataclassConfig           |   2656.3 KB |  271.6 B/obj
74# SlottedDataclass          |    898.4 KB |   91.9 B/obj

完整程式碼

以下是整合所有優化技術的完整實作：

  1"""
  2Memory-optimized configuration cache system.
  3
  4This module demonstrates:
  5- Using __slots__ to reduce object memory footprint
  6- Using weakref for automatic cache cleanup
  7- Using tracemalloc for memory profiling
  8
  9Based on patterns from .claude/lib/config_loader.py
 10"""
 11
 12import weakref
 13import sys
 14import gc
 15import tracemalloc
 16from typing import Any, Callable, Generic, Optional, TypeVar
 17from pathlib import Path
 18from datetime import datetime
 19
 20T = TypeVar('T')
 21
 22class ConfigEntry:
 23    """
 24    Memory-optimized configuration entry.
 25
 26    Uses __slots__ to reduce memory footprint by ~3x compared
 27    to regular classes.
 28    """
 29    __slots__ = [
 30        'key', 'value', 'source', 'loaded_at',
 31        'access_count', '__weakref__'
 32    ]
 33
 34    def __init__(
 35        self,
 36        key: str,
 37        value: Any,
 38        source: Optional[str] = None
 39    ):
 40        self.key = key
 41        self.value = value
 42        self.source = source
 43        self.loaded_at = datetime.now()
 44        self.access_count = 0
 45
 46    def __repr__(self) -> str:
 47        return (
 48            f"ConfigEntry(key={self.key!r}, "
 49            f"value={self.value!r}, "
 50            f"accesses={self.access_count})"
 51        )
 52
 53    def touch(self) -> None:
 54        """Record an access to this entry"""
 55        self.access_count += 1
 56
 57class SmartConfigCache:
 58    """
 59    Smart configuration cache with automatic memory management.
 60
 61    Features:
 62    - Weak references for automatic cleanup
 63    - Memory usage tracking
 64    - Hit/miss statistics
 65    - Optional size limits
 66
 67    Example:
 68        cache = SmartConfigCache(max_size=1000)
 69
 70        # Get or create config
 71        config = cache.get_or_create(
 72            "database.host",
 73            lambda: ConfigEntry("database.host", "localhost", "env")
 74        )
 75
 76        # Check stats
 77        print(cache.stats())
 78    """
 79
 80    def __init__(self, max_size: Optional[int] = None):
 81        """
 82        Initialize the cache.
 83
 84        Args:
 85            max_size: Maximum number of entries. None for unlimited.
 86        """
 87        self._cache: weakref.WeakValueDictionary[str, ConfigEntry] = (
 88            weakref.WeakValueDictionary()
 89        )
 90        self._strong_refs: dict[str, ConfigEntry] = {}  # Keep important items
 91        self._max_size = max_size
 92        self._hits = 0
 93        self._misses = 0
 94        self._evictions = 0
 95
 96    def get(self, key: str) -> Optional[ConfigEntry]:
 97        """
 98        Get entry from cache.
 99
100        Args:
101            key: Configuration key
102
103        Returns:
104            ConfigEntry if found, None otherwise
105        """
106        # Check strong refs first
107        entry = self._strong_refs.get(key)
108        if entry is not None:
109            self._hits += 1
110            entry.touch()
111            return entry
112
113        # Then check weak refs
114        entry = self._cache.get(key)
115        if entry is not None:
116            self._hits += 1
117            entry.touch()
118            return entry
119
120        self._misses += 1
121        return None
122
123    def get_or_create(
124        self,
125        key: str,
126        factory: Callable[[], ConfigEntry],
127        keep_strong: bool = False
128    ) -> ConfigEntry:
129        """
130        Get existing entry or create new one.
131
132        Args:
133            key: Configuration key
134            factory: Function to create entry if not found
135            keep_strong: If True, keep a strong reference (won't auto-cleanup)
136
137        Returns:
138            Existing or newly created ConfigEntry
139        """
140        entry = self.get(key)
141        if entry is not None:
142            return entry
143
144        # Create new entry
145        entry = factory()
146        self._cache[key] = entry
147
148        if keep_strong:
149            self._enforce_size_limit()
150            self._strong_refs[key] = entry
151
152        return entry
153
154    def _enforce_size_limit(self) -> None:
155        """Evict old entries if cache is full"""
156        if self._max_size is None:
157            return
158
159        while len(self._strong_refs) >= self._max_size:
160            # Evict least accessed entry
161            if not self._strong_refs:
162                break
163
164            min_key = min(
165                self._strong_refs.keys(),
166                key=lambda k: self._strong_refs[k].access_count
167            )
168            del self._strong_refs[min_key]
169            self._evictions += 1
170
171    def pin(self, key: str) -> bool:
172        """
173        Pin an entry to prevent automatic cleanup.
174
175        Args:
176            key: Configuration key
177
178        Returns:
179            True if entry was pinned, False if not found
180        """
181        entry = self._cache.get(key)
182        if entry is None:
183            return False
184
185        self._enforce_size_limit()
186        self._strong_refs[key] = entry
187        return True
188
189    def unpin(self, key: str) -> bool:
190        """
191        Unpin an entry to allow automatic cleanup.
192
193        Args:
194            key: Configuration key
195
196        Returns:
197            True if entry was unpinned, False if not found
198        """
199        if key in self._strong_refs:
200            del self._strong_refs[key]
201            return True
202        return False
203
204    def clear(self) -> None:
205        """Clear all cached entries"""
206        self._cache.clear()
207        self._strong_refs.clear()
208
209    def stats(self) -> dict:
210        """
211        Get cache statistics.
212
213        Returns:
214            Dict with hits, misses, hit_rate, size, pinned, evictions
215        """
216        total = self._hits + self._misses
217        hit_rate = self._hits / total if total > 0 else 0.0
218
219        return {
220            "hits": self._hits,
221            "misses": self._misses,
222            "hit_rate": f"{hit_rate:.1%}",
223            "total_size": len(self._cache) + len(self._strong_refs),
224            "weak_refs": len(self._cache),
225            "pinned": len(self._strong_refs),
226            "evictions": self._evictions,
227        }
228
229    def memory_usage(self) -> dict:
230        """
231        Estimate memory usage of cached entries.
232
233        Returns:
234            Dict with entry_count, estimated_bytes, per_entry_bytes
235        """
236        all_entries = list(self._cache.values()) + list(self._strong_refs.values())
237
238        if not all_entries:
239            return {
240                "entry_count": 0,
241                "estimated_bytes": 0,
242                "per_entry_bytes": 0,
243            }
244
245        # Estimate based on first entry
246        sample = all_entries[0]
247        per_entry = sys.getsizeof(sample)
248
249        return {
250            "entry_count": len(all_entries),
251            "estimated_bytes": per_entry * len(all_entries),
252            "per_entry_bytes": per_entry,
253        }
254
255def demo_memory_optimization():
256    """Demonstrate memory optimization techniques"""
257
258    print("=" * 60)
259    print("Memory Optimization Demo")
260    print("=" * 60)
261
262    # Start memory tracking
263    tracemalloc.start()
264    gc.collect()
265    snapshot1 = tracemalloc.take_snapshot()
266
267    # Create cache and populate
268    cache = SmartConfigCache(max_size=100)
269
270    # Simulate loading many configurations
271    entries = []
272    for i in range(1000):
273        entry = cache.get_or_create(
274            f"config.item.{i}",
275            lambda i=i: ConfigEntry(
276                f"config.item.{i}",
277                f"value_{i}",
278                "demo"
279            ),
280            keep_strong=(i < 100)  # Pin first 100
281        )
282        entries.append(entry)
283
284    # Take snapshot after creation
285    gc.collect()
286    snapshot2 = tracemalloc.take_snapshot()
287
288    # Print stats
289    print("\nCache Statistics:")
290    for key, value in cache.stats().items():
291        print(f"  {key}: {value}")
292
293    print("\nMemory Usage:")
294    for key, value in cache.memory_usage().items():
295        print(f"  {key}: {value:,}")
296
297    # Show memory diff
298    diff = snapshot2.compare_to(snapshot1, 'lineno')
299    print("\nTop 5 Memory Allocations:")
300    for stat in diff[:5]:
301        print(f"  {stat}")
302
303    # Demo weak reference cleanup
304    print("\n" + "-" * 60)
305    print("Weak Reference Cleanup Demo")
306    print("-" * 60)
307
308    print(f"Before cleanup - Cache size: {cache.stats()['total_size']}")
309
310    # Delete external references to unpinned entries
311    del entries
312    gc.collect()
313
314    print(f"After cleanup  - Cache size: {cache.stats()['total_size']}")
315    print("(Only pinned entries remain)")
316
317    tracemalloc.stop()
318
319if __name__ == "__main__":
320    demo_memory_optimization()

使用範例

 1from memory_optimized_cache import SmartConfigCache, ConfigEntry
 2
 3# Initialize cache with size limit
 4cache = SmartConfigCache(max_size=1000)
 5
 6# Load configuration
 7def load_database_config():
 8    """Factory function to load database config"""
 9    return ConfigEntry(
10        key="database",
11        value={
12            "host": "localhost",
13            "port": 5432,
14            "name": "myapp"
15        },
16        source="config.yaml"
17    )
18
19# Get or create (with strong reference for important config)
20db_config = cache.get_or_create(
21    "database",
22    load_database_config,
23    keep_strong=True  # Keep in memory
24)
25
26print(f"Database host: {db_config.value['host']}")
27
28# Temporary config (will be auto-cleaned when not referenced)
29temp_config = cache.get_or_create(
30    "temp.setting",
31    lambda: ConfigEntry("temp.setting", "temporary", "runtime")
32)
33
34# Check statistics
35print(cache.stats())
36# {'hits': 0, 'misses': 2, 'hit_rate': '0.0%',
37#  'total_size': 2, 'weak_refs': 1, 'pinned': 1, 'evictions': 0}
38
39# Memory usage
40print(cache.memory_usage())
41# {'entry_count': 2, 'estimated_bytes': 112, 'per_entry_bytes': 56}

設計權衡

`slots` vs 標準類別

面向	標準類別	`__slots__`
記憶體佔用	較多（有 `__dict__`）	較少（節省 ~60-70%）
動態屬性	支援 `obj.new_attr = x`	不支援（除非加 `__dict__`）
繼承	簡單	子類別需要自己的 `__slots__`
弱引用	預設支援	需要加入 `__weakref__` slot
Pickle	直接支援	需要 `__getstate__`/`__setstate__`
多重繼承	正常運作	多個父類別不能都有非空 `__slots__`

強引用 vs 弱引用快取

面向	強引用快取	弱引用快取
記憶體管理	需要手動清理	自動清理
資料保證	資料一定存在	資料可能被回收
適用場景	關鍵配置	暫時性資料
實作複雜度	簡單	稍微複雜

何時使用哪種技術？

 1決策樹：
 2
 3物件數量多嗎？
 4├── 是 → 考慮 __slots__
 5│   └── 需要動態屬性嗎？
 6│       ├── 是 → __slots__ = [..., '__dict__']
 7│       └── 否 → __slots__ = [...]
 8└── 否 → 標準類別即可
 9
10快取可能無限增長嗎？
11├── 是 → 使用 WeakValueDictionary 或 LRU
12└── 否 → 普通字典即可
13
14資料可以被回收嗎？
15├── 是 → weakref
16└── 否 → 強引用

什麼時候該用這個技術？

適合使用

建立大量小物件：如資料點、事件、配置項目
記憶體使用是瓶頸：經過 profiling 確認
快取可能無限增長：如用戶 session、請求資料
長時間運行的服務：如 web server、daemon

不建議使用

物件數量很少：優化效果不明顯
需要動態新增屬性：__slots__ 會限制彈性
過早優化：先確認是否真的有問題
程式碼可讀性優先：標準類別更直觀

優化決策流程

 1# Step 1: Profile first!
 2# Don't optimize until you know where the problem is
 3
 4import tracemalloc
 5
 6tracemalloc.start()
 7# ... run your code ...
 8snapshot = tracemalloc.take_snapshot()
 9top_stats = snapshot.statistics('lineno')
10
11for stat in top_stats[:10]:
12    print(stat)
13
14# Step 2: If memory is the issue, identify the class
15# Look for classes with many instances
16
17import gc
18from collections import Counter
19
20counter = Counter(type(obj).__name__ for obj in gc.get_objects())
21print(counter.most_common(10))
22
23# Step 3: Only then apply __slots__ to hot classes

練習

基礎練習：比較有無 `slots` 的記憶體差異

撰寫一個腳本，比較以下三種類別建立 100,000 個實例的記憶體使用：

 1# Exercise: Complete this benchmark script
 2
 3import sys
 4import tracemalloc
 5from dataclasses import dataclass
 6
 7# 1. Standard class
 8class PointStandard:
 9    def __init__(self, x, y, z):
10        self.x = x
11        self.y = y
12        self.z = z
13
14# 2. Class with __slots__
15class PointSlots:
16    __slots__ = ['x', 'y', 'z']
17    def __init__(self, x, y, z):
18        self.x = x
19        self.y = y
20        self.z = z
21
22# 3. Named tuple
23from collections import namedtuple
24PointNamed = namedtuple('PointNamed', ['x', 'y', 'z'])
25
26# TODO: Write benchmark function
27def benchmark(cls, count=100000):
28    """Measure memory for creating `count` instances"""
29    pass  # Implement this
30
31# TODO: Compare results
32# Expected: PointSlots uses ~3x less memory than PointStandard

進階練習：實作 weakref 快取

建立一個 ImageCache 類別，具有以下功能：

 1# Exercise: Implement ImageCache
 2
 3class ImageCache:
 4    """
 5    Cache for image data with automatic cleanup.
 6
 7    Requirements:
 8    - Use WeakValueDictionary for auto-cleanup
 9    - Track hit/miss statistics
10    - Support maximum size limit
11    - Provide memory usage estimation
12
13    Example usage:
14        cache = ImageCache(max_size=100)
15
16        img = cache.get_or_load("photo.jpg", lambda: load_image("photo.jpg"))
17
18        print(cache.stats())
19        # {'hits': 0, 'misses': 1, 'size': 1}
20    """
21
22    def __init__(self, max_size=None):
23        # TODO: Initialize cache
24        pass
25
26    def get_or_load(self, key, loader):
27        # TODO: Implement get or load logic
28        pass
29
30    def stats(self):
31        # TODO: Return cache statistics
32        pass

挑戰題：用 tracemalloc 追蹤記憶體洩漏

給定以下有記憶體洩漏的程式碼，使用 tracemalloc 找出問題並修復：

 1# Exercise: Find and fix the memory leak
 2
 3class EventHandler:
 4    _handlers = []  # Class variable - potential leak!
 5
 6    def __init__(self, name):
 7        self.name = name
 8        self.callbacks = []
 9        EventHandler._handlers.append(self)  # Leak: strong reference
10
11    def register(self, callback):
12        self.callbacks.append(callback)
13
14    def fire(self, event):
15        for cb in self.callbacks:
16            cb(event)
17
18def process_events():
19    """This function creates handlers but never cleans them up"""
20    for i in range(1000):
21        handler = EventHandler(f"handler_{i}")
22        handler.register(lambda e: print(e))
23        handler.fire(f"event_{i}")
24        # handler goes out of scope but is still in _handlers!
25
26# TODO:
27# 1. Use tracemalloc to measure memory growth
28# 2. Identify the leak
29# 3. Fix EventHandler to use weak references
30# 4. Verify the fix with tracemalloc

延伸閱讀

上一章：效能分析實戰 返回：模組四：CPython 內部機制

案例：正則表達式預編譯

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何透過正則表達式預編譯來減少重複編譯的開銷。

先備知識

模組八基礎章節
Python re 模組基本操作
基本的效能測量概念

問題背景

現有設計

hook_validator.py 是一個 Hook 合規性驗證工具，用於檢查 Hook 腳本是否遵循專案規範。它定義了多組正則表達式模式來偵測各種程式碼特徵：

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 共用模組導入模式
 5    HOOK_IO_PATTERNS = [
 6        r"from\s+hook_io\s+import",
 7        r"from\s+lib\.hook_io\s+import",
 8    ]
 9
10    HOOK_LOGGING_PATTERNS = [
11        r"from\s+hook_logging\s+import",
12        r"from\s+lib\.hook_logging\s+import",
13    ]
14
15    CONFIG_LOADER_PATTERNS = [
16        r"from\s+config_loader\s+import",
17        r"from\s+lib\.config_loader\s+import",
18    ]
19
20    GIT_UTILS_PATTERNS = [
21        r"from\s+git_utils\s+import",
22        r"from\s+lib\.git_utils\s+import",
23    ]
24
25    # 輸出函式使用模式
26    OUTPUT_PATTERNS = [
27        r"write_hook_output\s*\(",
28        r"create_pretooluse_output\s*\(",
29        r"create_posttooluse_output\s*\(",
30    ]
31
32    # 不推薦的輸出模式
33    BAD_OUTPUT_PATTERNS = [
34        r'print\s*\(\s*json\.dumps\s*\(',
35        r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\(',
36    ]
37
38    # 命名規範模式
39    VALID_NAME_PATTERNS = [
40        r"^[a-z0-9](/python-advanced/08-practical-optimization/case-studies/regex-precompile/[a-z0-9\-_]*[a-z0-9])?\.py$",
41    ]
42
43    # Hook 類型推測模式
44    HOOK_TYPE_HINTS = [
45        ("PreToolUse", r"create_pretooluse_output|permissionDecision"),
46        ("PostToolUse", r"create_posttooluse_output|additionalContext"),
47        ("Stop", r"Stop|subagent"),
48        ("SessionStart", r"SessionStart|session_id"),
49    ]

目前的實作將模式儲存為字串列表，並在輔助方法中使用 re.search() 進行匹配：

 1def _has_import(self, content: str, patterns: List[str]) -> bool:
 2    """檢查是否有符合任一模式的導入"""
 3    return any(
 4        re.search(pattern, content)
 5        for pattern in patterns
 6    )
 7
 8def _matches_pattern(self, content: str, patterns: List[str]) -> bool:
 9    """檢查是否符合任一模式"""
10    return any(
11        re.search(pattern, content)
12        for pattern in patterns
13    )

Python re 的內部快取

在討論優化之前，我們需要了解 Python re 模組的內部機制。

當你使用 re.search(pattern, string) 這樣的函式時，Python 會在內部執行兩個步驟：

編譯：將正則表達式字串轉換為內部的 pattern 物件
匹配：使用 pattern 物件對目標字串進行匹配

為了避免重複編譯，re 模組內建了一個 LRU 快取：

 1# Python 內部實作概念（簡化版）
 2_cache = {}
 3_MAXCACHE = 512  # Python 3.12 的預設值
 4
 5def _compile(pattern, flags=0):
 6    key = (type(pattern), pattern, flags)
 7    if key in _cache:
 8        return _cache[key]  # 快取命中
 9
10    # 實際編譯
11    compiled = sre_compile.compile(pattern, flags)
12
13    # 儲存到快取
14    if len(_cache) >= _MAXCACHE:
15        _cache.clear()  # 快取滿了就清空
16    _cache[key] = compiled
17
18    return compiled

你可以驗證這個快取的存在：

 1import re
 2
 3# 查看快取大小
 4print(f"快取大小上限: {re._MAXCACHE}")
 5
 6# 第一次呼叫會編譯
 7re.search(r'\d+', 'test123')
 8
 9# 查看快取內容（僅供觀察，不建議在生產環境使用）
10print(f"目前快取數量: {len(re._cache)}")

為什麼還需要手動預編譯？

既然 re 有內建快取，為什麼還需要手動使用 re.compile()？原因有幾個：

1. 快取查找有開銷

每次使用 re.search() 時，都需要：

 1# 虛擬碼：每次 re.search() 的內部流程
 2def search(pattern, string, flags=0):
 3    # 1. 建立快取鍵（需要計算 hash）
 4    key = (type(pattern), pattern, flags)
 5
 6    # 2. 查找快取（dict lookup）
 7    if key in _cache:
 8        compiled = _cache[key]
 9    else:
10        compiled = _compile_and_cache(pattern, flags)
11
12    # 3. 執行匹配
13    return compiled.search(string)

相比之下，預編譯後直接使用：

1# 預編譯
2pattern = re.compile(r'\d+')
3
4# 直接使用，無需快取查找
5pattern.search(string)

2. 快取可能被清空

當快取達到上限（預設 512 個模式）時，整個快取會被清空：

1if len(_cache) >= _MAXCACHE:
2    _cache.clear()  # 全部清空！

這表示在大型專案中，你的常用模式可能會被意外從快取中移除。

3. 語意更清晰

預編譯讓程式碼意圖更明確：

 1# 不清楚：pattern 是什麼時候編譯的？
 2def check(content):
 3    if re.search(r'pattern1', content):
 4        ...
 5    if re.search(r'pattern2', content):
 6        ...
 7
 8# 清楚：模式在類別載入時就編譯好了
 9class Validator:
10    PATTERN1 = re.compile(r'pattern1')
11    PATTERN2 = re.compile(r'pattern2')
12
13    def check(self, content):
14        if self.PATTERN1.search(content):
15            ...
16        if self.PATTERN2.search(content):
17            ...

進階解決方案

實作步驟

步驟 1：識別需要預編譯的模式

首先，找出所有會被重複使用的正則表達式。在 hook_validator.py 中，以下模式會在每次驗證時使用：

導入檢查模式（7 組，共 14 個模式）
輸出格式檢查模式（5 個模式）
命名規範模式（1 個模式）
Hook 類型推測模式（4 個模式）

步驟 2：建立預編譯版本

將字串模式轉換為已編譯的 pattern 物件：

 1import re
 2from typing import Pattern, List, Tuple
 3
 4class HookValidatorOptimized:
 5    """使用預編譯正則表達式的 Hook 驗證器"""
 6
 7    # 預編譯的導入模式
 8    HOOK_IO_PATTERNS: List[Pattern] = [
 9        re.compile(r"from\s+hook_io\s+import"),
10        re.compile(r"from\s+lib\.hook_io\s+import"),
11    ]
12
13    HOOK_LOGGING_PATTERNS: List[Pattern] = [
14        re.compile(r"from\s+hook_logging\s+import"),
15        re.compile(r"from\s+lib\.hook_logging\s+import"),
16    ]
17
18    CONFIG_LOADER_PATTERNS: List[Pattern] = [
19        re.compile(r"from\s+config_loader\s+import"),
20        re.compile(r"from\s+lib\.config_loader\s+import"),
21    ]
22
23    GIT_UTILS_PATTERNS: List[Pattern] = [
24        re.compile(r"from\s+git_utils\s+import"),
25        re.compile(r"from\s+lib\.git_utils\s+import"),
26    ]
27
28    # 預編譯的輸出模式
29    OUTPUT_PATTERNS: List[Pattern] = [
30        re.compile(r"write_hook_output\s*\("),
31        re.compile(r"create_pretooluse_output\s*\("),
32        re.compile(r"create_posttooluse_output\s*\("),
33    ]
34
35    BAD_OUTPUT_PATTERNS: List[Pattern] = [
36        re.compile(r'print\s*\(\s*json\.dumps\s*\('),
37        re.compile(r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\('),
38    ]
39
40    # 預編譯的命名模式
41    VALID_NAME_PATTERNS: List[Pattern] = [
42        re.compile(r"^[a-z0-9](/python-advanced/08-practical-optimization/case-studies/regex-precompile/[a-z0-9\-_]*[a-z0-9])?\.py$"),
43    ]
44
45    # 預編譯的 Hook 類型推測模式
46    HOOK_TYPE_HINTS: List[Tuple[str, Pattern]] = [
47        ("PreToolUse", re.compile(r"create_pretooluse_output|permissionDecision")),
48        ("PostToolUse", re.compile(r"create_posttooluse_output|additionalContext")),
49        ("Stop", re.compile(r"Stop|subagent")),
50        ("SessionStart", re.compile(r"SessionStart|session_id")),
51    ]
52
53    # 其他預編譯模式
54    JSON_OUTPUT_PATTERNS: List[Pattern] = [
55        re.compile(r"json\.dumps"),
56        re.compile(r"write_hook_output"),
57        re.compile(r"create_.*_output"),
58    ]

步驟 3：更新匹配方法

修改輔助方法，使用預編譯的 pattern 物件：

 1def _has_import(self, content: str, patterns: List[Pattern]) -> bool:
 2    """檢查是否有符合任一模式的導入（使用預編譯模式）"""
 3    return any(
 4        pattern.search(content)  # 直接使用 Pattern.search()
 5        for pattern in patterns
 6    )
 7
 8def _matches_pattern(self, content: str, patterns: List[Pattern]) -> bool:
 9    """檢查是否符合任一模式（使用預編譯模式）"""
10    return any(
11        pattern.search(content)
12        for pattern in patterns
13    )
14
15def _has_json_output(self, content: str) -> bool:
16    """檢查是否有 JSON 輸出相關程式碼"""
17    return any(
18        pattern.search(content)
19        for pattern in self.JSON_OUTPUT_PATTERNS
20    )

完整程式碼

以下是完整的優化版本：

  1#!/usr/bin/env python3
  2"""
  3Hook 合規性驗證工具（優化版）
  4
  5使用 re.compile 預編譯所有正則表達式，減少重複編譯開銷。
  6"""
  7
  8import re
  9from dataclasses import dataclass, field
 10from pathlib import Path
 11from typing import List, Optional, Pattern, Tuple
 12
 13@dataclass
 14class ValidationIssue:
 15    """驗證問題描述"""
 16    level: str  # "error" | "warning" | "info"
 17    message: str
 18    line: Optional[int] = None
 19    suggestion: Optional[str] = None
 20
 21@dataclass
 22class ValidationResult:
 23    """單個 Hook 的驗證結果"""
 24    hook_path: str
 25    issues: List[ValidationIssue] = field(default_factory=list)
 26    is_compliant: bool = True
 27
 28    def __post_init__(self):
 29        self.is_compliant = not any(
 30            issue.level == "error" for issue in self.issues
 31        )
 32
 33class HookValidatorOptimized:
 34    """
 35    使用預編譯正則表達式的 Hook 驗證器
 36
 37    所有正則表達式在類別定義時編譯一次，
 38    之後所有實例共享這些已編譯的 pattern 物件。
 39    """
 40
 41    # ===== 預編譯的正則表達式 =====
 42
 43    # 導入模式
 44    HOOK_IO_PATTERNS: List[Pattern] = [
 45        re.compile(r"from\s+hook_io\s+import"),
 46        re.compile(r"from\s+lib\.hook_io\s+import"),
 47    ]
 48
 49    HOOK_LOGGING_PATTERNS: List[Pattern] = [
 50        re.compile(r"from\s+hook_logging\s+import"),
 51        re.compile(r"from\s+lib\.hook_logging\s+import"),
 52    ]
 53
 54    CONFIG_LOADER_PATTERNS: List[Pattern] = [
 55        re.compile(r"from\s+config_loader\s+import"),
 56        re.compile(r"from\s+lib\.config_loader\s+import"),
 57    ]
 58
 59    GIT_UTILS_PATTERNS: List[Pattern] = [
 60        re.compile(r"from\s+git_utils\s+import"),
 61        re.compile(r"from\s+lib\.git_utils\s+import"),
 62    ]
 63
 64    # 輸出模式
 65    OUTPUT_PATTERNS: List[Pattern] = [
 66        re.compile(r"write_hook_output\s*\("),
 67        re.compile(r"create_pretooluse_output\s*\("),
 68        re.compile(r"create_posttooluse_output\s*\("),
 69    ]
 70
 71    BAD_OUTPUT_PATTERNS: List[Pattern] = [
 72        re.compile(r'print\s*\(\s*json\.dumps\s*\('),
 73        re.compile(r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\('),
 74    ]
 75
 76    # 命名模式
 77    VALID_NAME_PATTERN: Pattern = re.compile(
 78        r"^[a-z0-9](/python-advanced/08-practical-optimization/case-studies/regex-precompile/[a-z0-9\-_]*[a-z0-9])?\.py$"
 79    )
 80
 81    # Hook 類型推測
 82    HOOK_TYPE_HINTS: List[Tuple[str, Pattern]] = [
 83        ("PreToolUse", re.compile(r"create_pretooluse_output|permissionDecision")),
 84        ("PostToolUse", re.compile(r"create_posttooluse_output|additionalContext")),
 85        ("Stop", re.compile(r"Stop|subagent")),
 86        ("SessionStart", re.compile(r"SessionStart|session_id")),
 87    ]
 88
 89    # JSON 輸出檢測
 90    JSON_OUTPUT_PATTERNS: List[Pattern] = [
 91        re.compile(r"json\.dumps"),
 92        re.compile(r"write_hook_output"),
 93        re.compile(r"create_.*_output"),
 94    ]
 95
 96    # 功能推測模式
 97    CONFIG_KEYWORDS_PATTERN: Pattern = re.compile(
 98        r"load_config|configuration|config|yaml|json",
 99        re.IGNORECASE
100    )
101
102    GIT_KEYWORDS_PATTERN: Pattern = re.compile(
103        r"git|branch|commit|worktree|is_protected_branch|get_current_branch",
104        re.IGNORECASE
105    )
106
107    def __init__(self, project_root: Optional[str] = None):
108        """初始化驗證器"""
109        import os
110        if project_root is None:
111            project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
112        self.project_root = Path(project_root)
113
114    def _has_import(self, content: str, patterns: List[Pattern]) -> bool:
115        """檢查是否有符合任一模式的導入"""
116        return any(pattern.search(content) for pattern in patterns)
117
118    def _matches_pattern(self, content: str, patterns: List[Pattern]) -> bool:
119        """檢查是否符合任一模式"""
120        return any(pattern.search(content) for pattern in patterns)
121
122    def _has_json_output(self, content: str) -> bool:
123        """檢查是否有 JSON 輸出相關程式碼"""
124        return any(
125            pattern.search(content)
126            for pattern in self.JSON_OUTPUT_PATTERNS
127        )
128
129    def _needs_config_loader(self, content: str, hook_path: Optional[Path] = None) -> bool:
130        """判斷 Hook 是否需要配置載入"""
131        if self.CONFIG_KEYWORDS_PATTERN.search(content):
132            return True
133
134        if hook_path:
135            name_lower = hook_path.stem.lower()
136            if any(kw in name_lower for kw in ["config", "agent", "dispatch"]):
137                return True
138
139        return False
140
141    def _needs_git_utils(self, content: str, hook_path: Optional[Path] = None) -> bool:
142        """判斷 Hook 是否需要 Git 操作"""
143        if self.GIT_KEYWORDS_PATTERN.search(content):
144            return True
145
146        if hook_path:
147            name_lower = hook_path.stem.lower()
148            if any(kw in name_lower for kw in ["branch", "git", "commit", "worktree"]):
149                return True
150
151        return False
152
153    def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
154        """檢查命名規範"""
155        issues = []
156        filename = hook_path.name
157
158        if not self.VALID_NAME_PATTERN.match(filename):
159            issues.append(
160                ValidationIssue(
161                    level="warning",
162                    message=f"檔案名稱不符合規範: {filename}",
163                    suggestion="建議使用 snake-case 或 kebab-case 命名"
164                )
165            )
166
167        return issues
168
169    def infer_hook_type(self, content: str) -> Optional[str]:
170        """根據內容推測 Hook 類型"""
171        for hook_type, pattern in self.HOOK_TYPE_HINTS:
172            if pattern.search(content):
173                return hook_type
174        return None
175
176    def validate_hook(self, hook_path: str) -> ValidationResult:
177        """驗證單個 Hook 檔案"""
178        path = Path(hook_path)
179        if not path.is_absolute():
180            path = self.project_root / path
181
182        if not path.exists():
183            return ValidationResult(
184                hook_path=str(path),
185                issues=[ValidationIssue(
186                    level="error",
187                    message=f"Hook 檔案不存在: {path}"
188                )]
189            )
190
191        try:
192            content = path.read_text(encoding="utf-8")
193        except Exception as e:
194            return ValidationResult(
195                hook_path=str(path),
196                issues=[ValidationIssue(
197                    level="error",
198                    message=f"無法讀取檔案: {e}"
199                )]
200            )
201
202        issues = []
203        issues.extend(self.check_naming_convention(path))
204
205        # 使用預編譯模式進行各項檢查
206        if not self._has_import(content, self.HOOK_IO_PATTERNS):
207            issues.append(ValidationIssue(
208                level="warning",
209                message="未導入 hook_io 模組"
210            ))
211
212        if self._matches_pattern(content, self.BAD_OUTPUT_PATTERNS):
213            issues.append(ValidationIssue(
214                level="warning",
215                message="使用不推薦的輸出方式"
216            ))
217
218        return ValidationResult(hook_path=str(path), issues=issues)

效能測量

使用 timeit 模組來精確測量預編譯帶來的效能提升：

  1#!/usr/bin/env python3
  2"""
  3正則表達式預編譯效能測試
  4
  5比較：
  61. 每次使用 re.search(string_pattern, content)
  72. 使用預編譯的 pattern.search(content)
  8"""
  9
 10import re
 11import timeit
 12from typing import List, Pattern
 13
 14# 測試用的正則表達式模式（來自 hook_validator.py）
 15STRING_PATTERNS = [
 16    r"from\s+hook_io\s+import",
 17    r"from\s+lib\.hook_io\s+import",
 18    r"from\s+hook_logging\s+import",
 19    r"from\s+lib\.hook_logging\s+import",
 20    r"from\s+config_loader\s+import",
 21    r"from\s+lib\.config_loader\s+import",
 22    r"from\s+git_utils\s+import",
 23    r"from\s+lib\.git_utils\s+import",
 24    r"write_hook_output\s*\(",
 25    r"create_pretooluse_output\s*\(",
 26    r"create_posttooluse_output\s*\(",
 27    r'print\s*\(\s*json\.dumps\s*\(',
 28    r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\(',
 29    r"^[a-z0-9](/python-advanced/08-practical-optimization/case-studies/regex-precompile/[a-z0-9\-_]*[a-z0-9])?\.py$",
 30]
 31
 32# 預編譯版本
 33COMPILED_PATTERNS: List[Pattern] = [
 34    re.compile(p) for p in STRING_PATTERNS
 35]
 36
 37# 模擬的 Hook 檔案內容
 38SAMPLE_CONTENT = '''
 39#!/usr/bin/env python3
 40"""Sample hook for testing"""
 41
 42import json
 43import sys
 44from pathlib import Path
 45
 46from hook_io import read_hook_input, write_hook_output
 47from hook_logging import setup_hook_logging
 48from config_loader import load_config
 49
 50logger = setup_hook_logging(__name__)
 51
 52def main():
 53    """Main entry point"""
 54    input_data = read_hook_input()
 55    config = load_config()
 56
 57    # Process the input
 58    result = process(input_data, config)
 59
 60    # Write output using recommended function
 61    write_hook_output({
 62        "result": "continue",
 63        "additionalContext": result
 64    })
 65
 66def process(data, config):
 67    """Process the hook data"""
 68    return {"status": "ok"}
 69
 70if __name__ == "__main__":
 71    main()
 72'''
 73
 74def search_with_strings(content: str, patterns: List[str]) -> List[bool]:
 75    """使用字串模式搜尋（每次都會經過 re 快取）"""
 76    return [
 77        bool(re.search(pattern, content))
 78        for pattern in patterns
 79    ]
 80
 81def search_with_compiled(content: str, patterns: List[Pattern]) -> List[bool]:
 82    """使用預編譯模式搜尋"""
 83    return [
 84        bool(pattern.search(content))
 85        for pattern in patterns
 86    ]
 87
 88def benchmark():
 89    """執行效能測試"""
 90    # 預熱（讓 re 模組的快取填滿）
 91    for _ in range(100):
 92        search_with_strings(SAMPLE_CONTENT, STRING_PATTERNS)
 93        search_with_compiled(SAMPLE_CONTENT, COMPILED_PATTERNS)
 94
 95    # 測試參數
 96    iterations = 10000
 97    repeat = 5
 98
 99    # 測試字串模式（有 re 快取）
100    string_times = timeit.repeat(
101        lambda: search_with_strings(SAMPLE_CONTENT, STRING_PATTERNS),
102        number=iterations,
103        repeat=repeat
104    )
105
106    # 測試預編譯模式
107    compiled_times = timeit.repeat(
108        lambda: search_with_compiled(SAMPLE_CONTENT, COMPILED_PATTERNS),
109        number=iterations,
110        repeat=repeat
111    )
112
113    # 計算結果
114    string_best = min(string_times)
115    compiled_best = min(compiled_times)
116    speedup = string_best / compiled_best
117
118    # 輸出結果
119    print("正則表達式預編譯效能測試")
120    print("=" * 60)
121    print(f"測試內容大小: {len(SAMPLE_CONTENT)} 字元")
122    print(f"模式數量: {len(STRING_PATTERNS)} 個")
123    print(f"迭代次數: {iterations:,} 次 x {repeat} 輪")
124    print()
125    print("結果（最佳時間）:")
126    print("-" * 60)
127    print(f"字串模式 (re.search):     {string_best:.4f} 秒")
128    print(f"預編譯模式 (Pattern):     {compiled_best:.4f} 秒")
129    print(f"加速比:                   {speedup:.2f}x")
130    print()
131
132    # 單次操作時間
133    string_per_op = (string_best / iterations) * 1_000_000  # 微秒
134    compiled_per_op = (compiled_best / iterations) * 1_000_000
135
136    print("單次操作時間:")
137    print("-" * 60)
138    print(f"字串模式:                 {string_per_op:.2f} 微秒")
139    print(f"預編譯模式:               {compiled_per_op:.2f} 微秒")
140    print(f"每次節省:                 {string_per_op - compiled_per_op:.2f} 微秒")
141
142    return {
143        "string_time": string_best,
144        "compiled_time": compiled_best,
145        "speedup": speedup,
146    }
147
148def benchmark_cache_miss():
149    """測試快取未命中的情況"""
150    print("\n" + "=" * 60)
151    print("快取未命中測試（清空快取後）")
152    print("=" * 60)
153
154    iterations = 1000
155
156    # 清空 re 模組快取
157    re.purge()
158
159    # 測試字串模式（快取被清空）
160    start = timeit.default_timer()
161    for _ in range(iterations):
162        re.purge()  # 每次都清空快取
163        search_with_strings(SAMPLE_CONTENT, STRING_PATTERNS)
164    string_time = timeit.default_timer() - start
165
166    # 測試預編譯模式（不受快取影響）
167    start = timeit.default_timer()
168    for _ in range(iterations):
169        re.purge()  # 清空快取不影響預編譯模式
170        search_with_compiled(SAMPLE_CONTENT, COMPILED_PATTERNS)
171    compiled_time = timeit.default_timer() - start
172
173    speedup = string_time / compiled_time
174
175    print(f"字串模式 (無快取):        {string_time:.4f} 秒")
176    print(f"預編譯模式:               {compiled_time:.4f} 秒")
177    print(f"加速比:                   {speedup:.2f}x")
178
179if __name__ == "__main__":
180    results = benchmark()
181    benchmark_cache_miss()

典型測試結果

 1正則表達式預編譯效能測試
 2============================================================
 3測試內容大小: 847 字元
 4模式數量: 14 個
 5迭代次數: 10,000 次 x 5 輪
 6
 7結果（最佳時間）:
 8------------------------------------------------------------
 9字串模式 (re.search):     0.4823 秒
10預編譯模式 (Pattern):     0.3891 秒
11加速比:                   1.24x
12
13單次操作時間:
14------------------------------------------------------------
15字串模式:                 48.23 微秒
16預編譯模式:               38.91 微秒
17每次節省:                 9.32 微秒
18
19============================================================
20快取未命中測試（清空快取後）
21============================================================
22字串模式 (無快取):        2.3456 秒
23預編譯模式:               0.3912 秒
24加速比:                   6.00x

從結果可以看出：

正常情況：預編譯帶來約 1.2-1.3 倍 的加速
快取未命中：當 re 模組快取失效時，加速可達 6 倍

設計權衡

面向	字串模式	預編譯模式
記憶體使用	較低（依賴 re 快取）	略高（每個 Pattern 物件）
首次載入	快（延遲編譯）	慢（類別載入時編譯）
執行效能	依賴快取狀態	穩定且可預測
程式碼可讀性	模式定義較簡潔	意圖更明確
型別提示	`List[str]`	`List[Pattern]`
適合場景	少量模式、低頻呼叫	多模式、高頻呼叫

記憶體考量

預編譯的 Pattern 物件會佔用額外記憶體：

 1import re
 2import sys
 3
 4pattern_str = r"from\s+hook_io\s+import"
 5pattern_obj = re.compile(pattern_str)
 6
 7print(f"字串大小: {sys.getsizeof(pattern_str)} bytes")
 8print(f"Pattern 大小: {sys.getsizeof(pattern_obj)} bytes")
 9# 字串大小: 74 bytes
10# Pattern 大小: 256 bytes（視模式複雜度而定）

但在大多數情況下，這點記憶體是值得的。

什麼時候該用這個技術？

適合預編譯的情況

同一個模式會被使用多次（例如在迴圈中）
模式數量較多，可能超過 re 快取上限（512 個）
效能敏感的程式碼路徑
需要穩定、可預測的執行時間
類別或模組級別的模式定義

不需要預編譯的情況

模式只使用一次
快速原型開發
簡單的腳本工具
模式是動態生成的

練習

基礎練習：測量你的正則表達式效能

 1"""
 2練習 1：測量自己專案中正則表達式的效能
 3
 4步驟：
 51. 找出你專案中使用正則表達式的程式碼
 62. 記錄有多少個不同的模式
 73. 測量預編譯前後的效能差異
 8"""
 9
10import re
11import timeit
12
13# TODO: 將你專案中的模式填入這裡
14YOUR_PATTERNS = [
15    r"your_pattern_1",
16    r"your_pattern_2",
17    # ...
18]
19
20YOUR_TEST_CONTENT = """
21your test content here
22"""
23
24def measure_performance():
25    """測量效能差異"""
26    # 字串版本
27    string_patterns = YOUR_PATTERNS
28
29    # 預編譯版本
30    compiled_patterns = [re.compile(p) for p in YOUR_PATTERNS]
31
32    # 測量
33    string_time = timeit.timeit(
34        lambda: [re.search(p, YOUR_TEST_CONTENT) for p in string_patterns],
35        number=10000
36    )
37
38    compiled_time = timeit.timeit(
39        lambda: [p.search(YOUR_TEST_CONTENT) for p in compiled_patterns],
40        number=10000
41    )
42
43    print(f"字串模式: {string_time:.4f} 秒")
44    print(f"預編譯模式: {compiled_time:.4f} 秒")
45    print(f"加速比: {string_time / compiled_time:.2f}x")
46
47if __name__ == "__main__":
48    measure_performance()

進階練習：監控 re 快取狀態

 1"""
 2練習 2：監控 re 模組的快取狀態
 3
 4了解你的程式實際使用了多少快取空間。
 5"""
 6
 7import re
 8
 9def check_cache_status():
10    """檢查 re 模組快取狀態"""
11    print(f"快取上限: {re._MAXCACHE}")
12    print(f"目前快取數量: {len(re._cache)}")
13    print(f"使用率: {len(re._cache) / re._MAXCACHE * 100:.1f}%")
14
15    if len(re._cache) > re._MAXCACHE * 0.8:
16        print("警告：快取即將滿載！")
17
18def simulate_cache_overflow():
19    """模擬快取溢出"""
20    print("模擬快取溢出...")
21
22    # 記錄初始狀態
23    initial_count = len(re._cache)
24
25    # 建立大量不同的模式
26    for i in range(600):
27        re.search(f"pattern_{i}", "test content")
28
29    final_count = len(re._cache)
30
31    print(f"初始快取: {initial_count}")
32    print(f"最終快取: {final_count}")
33    print(f"快取被清空了 {(600 - final_count) // re._MAXCACHE} 次")
34
35if __name__ == "__main__":
36    check_cache_status()
37    print()
38    simulate_cache_overflow()

挑戰題：建立自動預編譯裝飾器

 1"""
 2練習 3：建立自動預編譯裝飾器
 3
 4設計一個裝飾器，自動將類別中的字串模式轉換為預編譯模式。
 5"""
 6
 7import re
 8from typing import List, Pattern, Type
 9
10def auto_compile_patterns(cls: Type) -> Type:
11    """
12    類別裝飾器：自動預編譯所有 _PATTERNS 結尾的類別屬性
13
14    使用方式：
15        @auto_compile_patterns
16        class MyValidator:
17            IMPORT_PATTERNS = [
18                r"from\s+module\s+import",
19                r"import\s+module",
20            ]
21    """
22    for attr_name in dir(cls):
23        if attr_name.endswith("_PATTERNS") and not attr_name.startswith("_"):
24            value = getattr(cls, attr_name)
25
26            if isinstance(value, list) and value and isinstance(value[0], str):
27                # 將字串列表轉換為預編譯模式列表
28                compiled = [re.compile(p) for p in value]
29                setattr(cls, attr_name, compiled)
30                print(f"預編譯 {cls.__name__}.{attr_name}: {len(compiled)} 個模式")
31
32    return cls
33
34# 測試
35@auto_compile_patterns
36class TestValidator:
37    IMPORT_PATTERNS = [
38        r"from\s+module\s+import",
39        r"import\s+module",
40    ]
41
42    OUTPUT_PATTERNS = [
43        r"print\s*\(",
44        r"write\s*\(",
45    ]
46
47    NOT_A_PATTERN = "這不是模式列表"
48
49if __name__ == "__main__":
50    # 驗證轉換結果
51    print(f"\nIMPORT_PATTERNS 類型: {type(TestValidator.IMPORT_PATTERNS[0])}")
52    print(f"OUTPUT_PATTERNS 類型: {type(TestValidator.OUTPUT_PATTERNS[0])}")
53    print(f"NOT_A_PATTERN 類型: {type(TestValidator.NOT_A_PATTERN)}")

延伸閱讀

上一章：並行 Hook 驗證 下一章：LRU 快取

案例：LRU 快取

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/git_utils.py 的 is_protected_branch() 和 is_allowed_branch() 函式，展示如何用 functools.lru_cache 快取重複的分支檢查結果。

先備知識

入門系列 3.8 效能優化
基本的 Git 分支概念

問題背景

現有設計

git_utils.py 提供兩個分支檢查函式：

 1import fnmatch
 2
 3# 保護分支列表（支援 glob 模式）
 4PROTECTED_BRANCHES = [
 5    "main",
 6    "master",
 7    "develop",
 8    "release/*",
 9    "production",
10]
11
12# 允許編輯的分支模式
13ALLOWED_BRANCHES = [
14    "feat/*",
15    "feature/*",
16    "fix/*",
17    "hotfix/*",
18    "bugfix/*",
19    "chore/*",
20    "docs/*",
21    "refactor/*",
22    "test/*",
23]
24
25def is_protected_branch(branch: str) -> bool:
26    """
27    檢查是否為保護分支
28
29    Args:
30        branch: 分支名稱
31
32    Returns:
33        bool: 如果是保護分支返回 True
34    """
35    for pattern in PROTECTED_BRANCHES:
36        if fnmatch.fnmatch(branch, pattern):
37            return True
38    return False
39
40def is_allowed_branch(branch: str) -> bool:
41    """
42    檢查是否為允許編輯的分支
43
44    Args:
45        branch: 分支名稱
46
47    Returns:
48        bool: 如果是允許編輯的分支返回 True
49    """
50    for pattern in ALLOWED_BRANCHES:
51        if fnmatch.fnmatch(branch, pattern):
52            return True
53    return False

這個設計的優點

簡單直覺：迴圈遍歷模式清單，易於理解
彈性高：支援 glob 模式，可輕易新增規則
無狀態：純函數，沒有副作用

重複計算的開銷

在 Hook 驗證流程中，同一個分支可能被檢查多次：

 1def validate_hook(hook_config: dict) -> list[str]:
 2    """驗證 Hook 配置"""
 3    errors = []
 4    branch = get_current_branch()
 5
 6    # 第一次檢查：是否允許執行
 7    if is_protected_branch(branch):
 8        errors.append("Cannot run on protected branch")
 9
10    # ... 其他驗證邏輯 ...
11
12    # 第二次檢查：是否需要額外確認
13    if is_protected_branch(branch) and hook_config.get("dangerous"):
14        errors.append("Dangerous operation on protected branch")
15
16    return errors
17
18def process_multiple_hooks(hooks: list[dict]) -> None:
19    """處理多個 Hook"""
20    branch = get_current_branch()
21
22    for hook in hooks:
23        # 每個 Hook 都會檢查分支
24        if not is_allowed_branch(branch):
25            continue
26
27        # 再次檢查保護狀態
28        if is_protected_branch(branch):
29            # ... 特殊處理 ...
30            pass

問題分析：

同一個分支名稱被重複檢查多次
每次檢查都要遍歷整個模式清單
fnmatch.fnmatch() 雖然快，但重複呼叫仍是浪費

測量重複呼叫的影響：

 1import time
 2
 3def benchmark_repeated_calls(branch: str, iterations: int = 10000) -> float:
 4    """測量重複呼叫的時間"""
 5    start = time.perf_counter()
 6
 7    for _ in range(iterations):
 8        is_protected_branch(branch)
 9        is_allowed_branch(branch)
10
11    return time.perf_counter() - start
12
13# 測量結果
14# 10000 次呼叫: ~0.05 秒
15# 每次呼叫: ~5 微秒
16
17# 看起來很快，但如果在熱路徑上...
18# 100 個 Hook x 10 次檢查 = 1000 次呼叫
19# 累積起來就有影響了

進階解決方案

lru_cache 基礎

functools.lru_cache 是 Python 內建的記憶化（memoization）裝飾器：

 1from functools import lru_cache
 2
 3@lru_cache(maxsize=128)
 4def expensive_function(x: int) -> int:
 5    """結果會被快取"""
 6    return x * 2
 7
 8# 第一次呼叫：實際計算
 9result1 = expensive_function(10)  # 計算並快取
10
11# 第二次呼叫：直接返回快取結果
12result2 = expensive_function(10)  # 從快取讀取

lru_cache 的適用條件：

純函數：相同輸入永遠產生相同輸出
可雜湊參數：所有參數必須是 hashable（可作為 dict 的 key）
沒有副作用：函數不應修改外部狀態
計算成本 > 快取成本：快取有記憶體開銷，要值得

檢查 is_protected_branch 是否適用：

 1# 1. 純函數？
 2#    是 - 相同分支名稱永遠返回相同結果
 3#    （前提：PROTECTED_BRANCHES 不會在執行時改變）
 4
 5# 2. 可雜湊參數？
 6#    是 - str 是 hashable
 7
 8# 3. 沒有副作用？
 9#    是 - 只讀取全域常數，不修改任何狀態
10
11# 4. 計算成本值得快取？
12#    要測量...

實作步驟

步驟 1：加入 lru_cache 裝飾器

 1from functools import lru_cache
 2import fnmatch
 3
 4PROTECTED_BRANCHES = [
 5    "main",
 6    "master",
 7    "develop",
 8    "release/*",
 9    "production",
10]
11
12ALLOWED_BRANCHES = [
13    "feat/*",
14    "feature/*",
15    "fix/*",
16    "hotfix/*",
17    "bugfix/*",
18    "chore/*",
19    "docs/*",
20    "refactor/*",
21    "test/*",
22]
23
24@lru_cache(maxsize=128)
25def is_protected_branch(branch: str) -> bool:
26    """
27    檢查是否為保護分支（帶快取）
28
29    Args:
30        branch: 分支名稱
31
32    Returns:
33        bool: 如果是保護分支返回 True
34
35    Note:
36        結果會被快取，快取大小為 128 個不同的分支名稱。
37        如果 PROTECTED_BRANCHES 在執行時改變，需要呼叫
38        is_protected_branch.cache_clear() 清除快取。
39    """
40    for pattern in PROTECTED_BRANCHES:
41        if fnmatch.fnmatch(branch, pattern):
42            return True
43    return False
44
45@lru_cache(maxsize=128)
46def is_allowed_branch(branch: str) -> bool:
47    """
48    檢查是否為允許編輯的分支（帶快取）
49
50    Args:
51        branch: 分支名稱
52
53    Returns:
54        bool: 如果是允許編輯的分支返回 True
55
56    Note:
57        結果會被快取。修改 ALLOWED_BRANCHES 後需要
58        呼叫 is_allowed_branch.cache_clear()。
59    """
60    for pattern in ALLOWED_BRANCHES:
61        if fnmatch.fnmatch(branch, pattern):
62            return True
63    return False

步驟 2：驗證快取行為

 1def verify_cache_behavior():
 2    """驗證快取確實在運作"""
 3    # 清除快取，確保乾淨狀態
 4    is_protected_branch.cache_clear()
 5
 6    # 第一次呼叫
 7    result1 = is_protected_branch("main")
 8    info1 = is_protected_branch.cache_info()
 9    print(f"第一次呼叫: hits={info1.hits}, misses={info1.misses}")
10    # 輸出: hits=0, misses=1
11
12    # 第二次呼叫（相同參數）
13    result2 = is_protected_branch("main")
14    info2 = is_protected_branch.cache_info()
15    print(f"第二次呼叫: hits={info2.hits}, misses={info2.misses}")
16    # 輸出: hits=1, misses=1
17
18    # 不同參數
19    result3 = is_protected_branch("feature/new")
20    info3 = is_protected_branch.cache_info()
21    print(f"不同參數: hits={info3.hits}, misses={info3.misses}")
22    # 輸出: hits=1, misses=2
23
24verify_cache_behavior()

maxsize 的選擇

maxsize 決定快取可以儲存多少個不同的輸入結果：

 1# maxsize=None：無限制快取
 2# 優點：所有結果都快取，命中率最高
 3# 缺點：記憶體可能無限增長
 4
 5@lru_cache(maxsize=None)
 6def unlimited_cache(x):
 7    return x * 2
 8
 9# maxsize=128（預設）：快取最多 128 個結果
10# LRU = Least Recently Used，超過時淘汰最久未使用的
11
12@lru_cache(maxsize=128)
13def limited_cache(x):
14    return x * 2
15
16# maxsize=1：只快取最後一個結果
17# 適用於「連續呼叫通常是相同參數」的情況
18
19@lru_cache(maxsize=1)
20def single_cache(x):
21    return x * 2

選擇策略：

 1def choose_maxsize():
 2    """
 3    選擇 maxsize 的考量因素
 4    """
 5    # 因素 1：輸入值的多樣性
 6    # - 分支名稱通常不多（< 100 種）
 7    # - 單一專案可能只有 10-20 個分支
 8    # - maxsize=128 綽綽有餘
 9
10    # 因素 2：記憶體使用
11    # - 每個快取項目: key + value + overhead
12    # - str 的 key 大小視長度而定
13    # - bool 的 value 很小
14    # - 128 個項目 < 10KB，可忽略
15
16    # 因素 3：呼叫模式
17    # - 如果同一個分支會被檢查很多次 → 大 maxsize
18    # - 如果每次都是新分支 → 快取沒意義
19
20    # 對於分支檢查：
21    # - 通常會重複檢查目前分支
22    # - maxsize=32 或 64 就足夠
23    # - 用 128 是保守選擇
24    pass

實際測量 maxsize 的影響：

 1from functools import lru_cache
 2import random
 3import time
 4
 5def benchmark_maxsize():
 6    """比較不同 maxsize 的效能"""
 7
 8    # 模擬分支名稱
 9    branches = [
10        "main", "master", "develop",
11        "feature/auth", "feature/api", "feature/ui",
12        "fix/bug1", "fix/bug2", "fix/bug3",
13        "release/v1.0", "release/v2.0",
14    ]
15
16    # 模擬呼叫模式：80% 是常見分支，20% 是其他
17    common_branches = branches[:3]
18
19    def simulate_calls(func, iterations=10000):
20        for _ in range(iterations):
21            if random.random() < 0.8:
22                branch = random.choice(common_branches)
23            else:
24                branch = random.choice(branches)
25            func(branch)
26        return func.cache_info()
27
28    # 測試不同 maxsize
29    for maxsize in [1, 4, 16, 64, 128, None]:
30        @lru_cache(maxsize=maxsize)
31        def test_func(branch):
32            for pattern in PROTECTED_BRANCHES:
33                if fnmatch.fnmatch(branch, pattern):
34                    return True
35            return False
36
37        info = simulate_calls(test_func)
38        hit_rate = info.hits / (info.hits + info.misses) * 100
39
40        print(f"maxsize={str(maxsize):>4}: "
41              f"hit_rate={hit_rate:.1f}%, "
42              f"size={info.currsize}")
43
44# 輸出範例:
45# maxsize=   1: hit_rate=65.2%, size=1
46# maxsize=   4: hit_rate=92.8%, size=4
47# maxsize=  16: hit_rate=99.9%, size=11
48# maxsize=  64: hit_rate=99.9%, size=11
49# maxsize= 128: hit_rate=99.9%, size=11
50# maxsize=None: hit_rate=99.9%, size=11

結論：對於分支檢查，maxsize=32 就足夠。用 maxsize=128 是安全的預設值。

快取命中率分析

cache_info() 提供詳細的快取統計：

 1def analyze_cache_performance():
 2    """分析快取效能"""
 3    # 模擬一個 Hook 驗證流程
 4    is_protected_branch.cache_clear()
 5    is_allowed_branch.cache_clear()
 6
 7    # 模擬驗證 50 個 Hook，每個 Hook 檢查 2 次
 8    branch = "feature/new-feature"
 9
10    for _ in range(50):
11        # 每個 Hook 的驗證邏輯
12        is_protected_branch(branch)
13        is_allowed_branch(branch)
14
15        # 某些 Hook 會再次檢查
16        if not is_protected_branch(branch):
17            is_allowed_branch(branch)
18
19    # 分析結果
20    protected_info = is_protected_branch.cache_info()
21    allowed_info = is_allowed_branch.cache_info()
22
23    print("=== 快取效能分析 ===")
24    print(f"\nis_protected_branch:")
25    print(f"  命中: {protected_info.hits}")
26    print(f"  未命中: {protected_info.misses}")
27    print(f"  命中率: {protected_info.hits / (protected_info.hits + protected_info.misses) * 100:.1f}%")
28    print(f"  快取大小: {protected_info.currsize}/{protected_info.maxsize}")
29
30    print(f"\nis_allowed_branch:")
31    print(f"  命中: {allowed_info.hits}")
32    print(f"  未命中: {allowed_info.misses}")
33    print(f"  命中率: {allowed_info.hits / (allowed_info.hits + allowed_info.misses) * 100:.1f}%")
34    print(f"  快取大小: {allowed_info.currsize}/{allowed_info.maxsize}")
35
36# 輸出:
37# === 快取效能分析 ===
38#
39# is_protected_branch:
40#   命中: 99
41#   未命中: 1
42#   命中率: 99.0%
43#   快取大小: 1/128
44#
45# is_allowed_branch:
46#   命中: 99
47#   未命中: 1
48#   命中率: 99.0%
49#   快取大小: 1/128

命中率解讀：

命中率	意義	建議
> 90%	快取非常有效	保持現狀
70-90%	快取有幫助	可考慮增加 maxsize
50-70%	效果有限	檢查呼叫模式
< 50%	快取可能沒意義	考慮移除快取

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3分支檢查工具 - 帶 LRU 快取
  4
  5展示如何用 functools.lru_cache 優化重複的分支檢查。
  6"""
  7
  8from functools import lru_cache
  9import fnmatch
 10from typing import Callable
 11
 12# ===== 分支配置常數 =====
 13
 14PROTECTED_BRANCHES = [
 15    "main",
 16    "master",
 17    "develop",
 18    "release/*",
 19    "production",
 20]
 21
 22ALLOWED_BRANCHES = [
 23    "feat/*",
 24    "feature/*",
 25    "fix/*",
 26    "hotfix/*",
 27    "bugfix/*",
 28    "chore/*",
 29    "docs/*",
 30    "refactor/*",
 31    "test/*",
 32]
 33
 34# ===== 帶快取的檢查函式 =====
 35
 36@lru_cache(maxsize=128)
 37def is_protected_branch(branch: str) -> bool:
 38    """
 39    檢查是否為保護分支（帶快取）
 40
 41    Args:
 42        branch: 分支名稱
 43
 44    Returns:
 45        bool: 如果是保護分支返回 True
 46
 47    Example:
 48        >>> is_protected_branch("main")
 49        True
 50        >>> is_protected_branch("feature/new")
 51        False
 52    """
 53    for pattern in PROTECTED_BRANCHES:
 54        if fnmatch.fnmatch(branch, pattern):
 55            return True
 56    return False
 57
 58@lru_cache(maxsize=128)
 59def is_allowed_branch(branch: str) -> bool:
 60    """
 61    檢查是否為允許編輯的分支（帶快取）
 62
 63    Args:
 64        branch: 分支名稱
 65
 66    Returns:
 67        bool: 如果是允許編輯的分支返回 True
 68
 69    Example:
 70        >>> is_allowed_branch("feat/new-feature")
 71        True
 72        >>> is_allowed_branch("random-branch")
 73        False
 74    """
 75    for pattern in ALLOWED_BRANCHES:
 76        if fnmatch.fnmatch(branch, pattern):
 77            return True
 78    return False
 79
 80# ===== 快取管理工具 =====
 81
 82def clear_branch_caches() -> None:
 83    """
 84    清除所有分支檢查快取
 85
 86    當 PROTECTED_BRANCHES 或 ALLOWED_BRANCHES 在執行時
 87    被修改時，需要呼叫此函式。
 88
 89    Example:
 90        >>> PROTECTED_BRANCHES.append("staging")
 91        >>> clear_branch_caches()  # 清除舊的快取結果
 92    """
 93    is_protected_branch.cache_clear()
 94    is_allowed_branch.cache_clear()
 95
 96def get_cache_stats() -> dict:
 97    """
 98    獲取快取統計資訊
 99
100    Returns:
101        dict: 包含兩個函式的快取統計
102
103    Example:
104        >>> stats = get_cache_stats()
105        >>> print(f"protected hit rate: {stats['protected']['hit_rate']:.1f}%")
106    """
107    protected = is_protected_branch.cache_info()
108    allowed = is_allowed_branch.cache_info()
109
110    def calc_hit_rate(info):
111        total = info.hits + info.misses
112        return info.hits / total * 100 if total > 0 else 0.0
113
114    return {
115        "protected": {
116            "hits": protected.hits,
117            "misses": protected.misses,
118            "hit_rate": calc_hit_rate(protected),
119            "size": protected.currsize,
120            "maxsize": protected.maxsize,
121        },
122        "allowed": {
123            "hits": allowed.hits,
124            "misses": allowed.misses,
125            "hit_rate": calc_hit_rate(allowed),
126            "size": allowed.currsize,
127            "maxsize": allowed.maxsize,
128        },
129    }
130
131def print_cache_stats() -> None:
132    """印出快取統計的格式化報告"""
133    stats = get_cache_stats()
134
135    print("=== 分支檢查快取統計 ===")
136
137    for name, info in stats.items():
138        print(f"\n{name}:")
139        print(f"  命中: {info['hits']}, 未命中: {info['misses']}")
140        print(f"  命中率: {info['hit_rate']:.1f}%")
141        print(f"  快取大小: {info['size']}/{info['maxsize']}")
142
143# ===== 效能比較工具 =====
144
145def benchmark_with_without_cache(
146    branches: list[str],
147    iterations: int = 1000
148) -> dict:
149    """
150    比較有無快取的效能差異
151
152    Args:
153        branches: 要測試的分支列表
154        iterations: 每個分支的呼叫次數
155
156    Returns:
157        dict: 效能比較結果
158    """
159    import time
160
161    # 無快取版本
162    def is_protected_no_cache(branch: str) -> bool:
163        for pattern in PROTECTED_BRANCHES:
164            if fnmatch.fnmatch(branch, pattern):
165                return True
166        return False
167
168    # 測試無快取版本
169    start = time.perf_counter()
170    for branch in branches:
171        for _ in range(iterations):
172            is_protected_no_cache(branch)
173    no_cache_time = time.perf_counter() - start
174
175    # 清除快取，測試有快取版本
176    is_protected_branch.cache_clear()
177
178    start = time.perf_counter()
179    for branch in branches:
180        for _ in range(iterations):
181            is_protected_branch(branch)
182    with_cache_time = time.perf_counter() - start
183
184    return {
185        "no_cache_time": no_cache_time,
186        "with_cache_time": with_cache_time,
187        "speedup": no_cache_time / with_cache_time,
188        "cache_info": is_protected_branch.cache_info(),
189    }
190
191# ===== 示範 =====
192
193if __name__ == "__main__":
194    import random
195
196    print("=== LRU 快取示範 ===\n")
197
198    # 測試分支
199    test_branches = [
200        "main",
201        "feature/auth",
202        "fix/bug-123",
203        "develop",
204        "chore/cleanup",
205        "release/v1.0",
206    ]
207
208    # 模擬重複呼叫
209    print("1. 模擬 Hook 驗證流程（100 次迭代）:")
210    clear_branch_caches()
211
212    for _ in range(100):
213        branch = random.choice(test_branches)
214        is_protected_branch(branch)
215        is_allowed_branch(branch)
216
217    print_cache_stats()
218
219    # 效能比較
220    print("\n2. 效能比較:")
221    result = benchmark_with_without_cache(test_branches, iterations=10000)
222
223    print(f"  無快取: {result['no_cache_time']:.4f}s")
224    print(f"  有快取: {result['with_cache_time']:.4f}s")
225    print(f"  加速比: {result['speedup']:.1f}x")
226    print(f"  快取命中率: {result['cache_info'].hits / (result['cache_info'].hits + result['cache_info'].misses) * 100:.1f}%")

設計權衡

面向	無快取	lru_cache
記憶體使用	無額外開銷	每個不同輸入一個快取項目
首次呼叫	直接計算	計算 + 快取開銷
重複呼叫	每次都計算	O(1) 查表
程式碼複雜度	最簡單	加一行裝飾器
正確性風險	無	配置變更時需清除快取
可測試性	直接測試	需考慮快取狀態
執行緒安全	是	是（lru_cache 內建鎖）

何時不該用快取

情況 1：函數不是純函數

 1import os
 2
 3# 錯誤示範：結果依賴外部狀態
 4@lru_cache(maxsize=128)
 5def get_env_value(key: str) -> str:
 6    return os.environ.get(key, "")
 7
 8# 問題：環境變數改變後，快取還是返回舊值
 9os.environ["MY_VAR"] = "old"
10print(get_env_value("MY_VAR"))  # "old"
11
12os.environ["MY_VAR"] = "new"
13print(get_env_value("MY_VAR"))  # 仍然是 "old"！

情況 2：參數不可雜湊

1# 錯誤示範：list 不是 hashable
2@lru_cache(maxsize=128)
3def process_items(items: list) -> int:  # TypeError!
4    return sum(items)
5
6# 解法：用 tuple 代替 list
7@lru_cache(maxsize=128)
8def process_items(items: tuple) -> int:
9    return sum(items)

情況 3：計算太簡單

1# 不建議：快取開銷可能大於計算成本
2@lru_cache(maxsize=128)
3def is_empty(s: str) -> bool:
4    return len(s) == 0
5
6# len() 和 == 操作非常快
7# 快取的雜湊計算和查表可能更慢

情況 4：輸入值極度多樣

1# 不建議：每次輸入都不同，快取永遠不會命中
2@lru_cache(maxsize=128)
3def process_unique_id(unique_id: str) -> dict:
4    # 如果 unique_id 每次都不同...
5    return {"id": unique_id}
6
7# 快取只會一直 miss，浪費記憶體

情況 5：需要即時反映外部變化

1# 不建議：配置可能動態變化
2@lru_cache(maxsize=128)
3def is_feature_enabled(feature: str) -> bool:
4    # 從資料庫讀取 feature flag
5    return db.get_feature_flag(feature)
6
7# 問題：資料庫更新後，快取還是返回舊值
8# 需要額外的快取失效機制

什麼時候該用這個技術？

適合使用 lru_cache：

純函數（相同輸入，相同輸出）
會被重複呼叫，且輸入值有限
計算成本明顯高於雜湊和查表
配置是靜態的，不會在執行時改變

不適合使用：

函數有副作用或依賴外部狀態
參數不可雜湊（list、dict、set）
每次輸入都不同（如 UUID、時間戳）
計算非常簡單（如 len()、+）

快速決策流程：

1函數是純函數嗎？
2├── 否 → 不要用 lru_cache
3└── 是 → 參數都是 hashable 嗎？
4         ├── 否 → 轉換成 hashable（如 tuple）或不用
5         └── 是 → 會被重複呼叫嗎？
6                  ├── 否 → 不需要快取
7                  └── 是 → 適合用 lru_cache

練習

基礎練習

測量快取效益：在你的專案中找一個被重複呼叫的純函數，加入 lru_cache，比較效能差異。
監控快取狀態：寫一個裝飾器，在每次呼叫後印出 cache_info()，觀察快取行為。

進階練習

帶 TTL 的快取：實作一個有過期時間的快取裝飾器。提示：可以結合 time.time() 和 lru_cache。

 1from functools import lru_cache, wraps
 2import time
 3
 4def timed_lru_cache(seconds: int, maxsize: int = 128):
 5    """
 6    帶過期時間的 LRU 快取
 7
 8    Args:
 9        seconds: 快取過期秒數
10        maxsize: 快取大小
11
12    用法：
13        @timed_lru_cache(seconds=60)
14        def fetch_data(url):
15            ...
16    """
17    def decorator(func):
18        # 你的實作
19        pass
20    return decorator

快取命中率監控：建立一個監控系統，追蹤多個快取函式的命中率，當命中率低於閾值時發出警告。

挑戰題

動態配置的快取失效：修改 is_protected_branch，支援在執行時新增保護分支，並自動失效相關快取（而不是清除所有快取）。

提示：考慮用 typed=True 選項，或自訂快取類別。

上一章：正則表達式預編譯 下一章：資料結構選擇

案例：資料結構選擇

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何選擇正確的資料結構來優化成員查詢效能。

先備知識

入門系列 3.8 效能優化
基本的時間複雜度概念（O(n)、O(1)）

問題背景

成員查詢的效能差異

在 Python 中，檢查某個元素是否存在於容器中（成員查詢）是最常見的操作之一：

1if item in container:
2    # 做某些事

但這行簡單的程式碼，背後的效能差異可能高達 100 倍以上，取決於 container 是什麼資料結構。

list 的成員查詢：O(n)

1my_list = [1, 2, 3, ..., n]
2if x in my_list:  # 最壞情況要檢查 n 個元素
3    ...

list 是有序的線性結構，Python 必須從頭開始逐一比對，直到找到目標或走完整個 list。

set 的成員查詢：O(1)

1my_set = {1, 2, 3, ..., n}
2if x in my_set:  # 平均只需要 1 次雜湊計算
3    ...

set 使用雜湊表（hash table）實作，透過計算元素的雜湊值直接定位，不受容器大小影響。

真實案例：測試檔案存在性檢查

hook_validator.py 的 check_test_exists 方法會檢查每個 Hook 是否有對應的測試檔案：

 1def check_test_exists(self, hook_path: Path) -> List[ValidationIssue]:
 2    """
 3    檢查對應的測試檔案是否存在
 4
 5    Args:
 6        hook_path: Hook 檔案路徑
 7
 8    Returns:
 9        list[ValidationIssue]: 發現的問題
10    """
11    issues = []
12
13    # 生成測試檔案名稱
14    hook_name = hook_path.stem
15    test_name = f"test_{hook_name.replace('-', '_')}.py"
16
17    # 測試檔案應該在 .claude/lib/tests/ 或 .claude/hooks/tests/
18    possible_test_paths = [
19        self.project_root / ".claude" / "lib" / "tests" / test_name,
20        self.project_root / ".claude" / "hooks" / "tests" / test_name,
21    ]
22
23    test_exists = any(p.exists() for p in possible_test_paths)
24
25    if not test_exists:
26        issues.append(
27            ValidationIssue(
28                level="info",
29                message=f"未找到對應的測試檔案: {test_name}",
30                suggestion=(
31                    f"建議在以下位置建立測試:\n"
32                    f"  .claude/lib/tests/{test_name}"
33                )
34            )
35        )
36
37    return issues

這個程式碼有一個隱藏的效能問題：當需要驗證大量 Hook 時，每次都要呼叫 p.exists() 進行檔案系統操作。

假設我們要驗證 100 個 Hook，而測試目錄下有 200 個測試檔案：

 1def validate_all_hooks(self, hooks_dir: Optional[str] = None) -> List[ValidationResult]:
 2    """驗證所有 Hook 檔案"""
 3    # ... 省略部分程式碼 ...
 4
 5    results = []
 6    for hook_file in sorted(hooks_dir.glob("*.py")):  # 100 個 Hook
 7        if hook_file.name.startswith("_"):
 8            continue
 9        results.append(self.validate_hook(str(hook_file)))
10        # 每個 validate_hook 會呼叫 check_test_exists
11        # check_test_exists 會呼叫 2 次 Path.exists()
12        # 總共：100 * 2 = 200 次檔案系統操作
13
14    return results

問題分析

原始程式碼的瓶頸：

重複的檔案系統操作：每個 Hook 都要呼叫 exists() 檢查測試是否存在
沒有快取：相同的檢查可能被重複執行
線性搜尋：如果測試清單很長，用 list 儲存會導致 O(n) 的查詢時間

進階解決方案

用 set 取代 list

核心思路：先掃描一次測試目錄，建立測試檔案的 set，然後用 O(1) 查詢取代檔案系統操作。

 1class HookValidator:
 2    """Hook 合規性驗證器（優化版）"""
 3
 4    def __init__(self, project_root: Optional[str] = None):
 5        if project_root is None:
 6            project_root = os.environ.get(
 7                "CLAUDE_PROJECT_DIR",
 8                os.getcwd()
 9            )
10        self.project_root = Path(project_root)
11
12        # 優化：預先建立測試檔案的 set
13        self._test_files_cache: Optional[set[str]] = None
14
15    @property
16    def test_files(self) -> set[str]:
17        """
18        取得所有測試檔案名稱（快取）
19
20        Returns:
21            set[str]: 測試檔案名稱集合
22        """
23        if self._test_files_cache is None:
24            self._test_files_cache = self._scan_test_files()
25        return self._test_files_cache
26
27    def _scan_test_files(self) -> set[str]:
28        """
29        掃描所有測試目錄，建立測試檔案集合
30
31        Returns:
32            set[str]: 測試檔案名稱集合
33        """
34        test_dirs = [
35            self.project_root / ".claude" / "lib" / "tests",
36            self.project_root / ".claude" / "hooks" / "tests",
37        ]
38
39        test_files = set()  # 使用 set 而非 list
40        for test_dir in test_dirs:
41            if test_dir.is_dir():
42                for test_file in test_dir.glob("test_*.py"):
43                    test_files.add(test_file.name)
44
45        return test_files
46
47    def check_test_exists(self, hook_path: Path) -> List[ValidationIssue]:
48        """
49        檢查對應的測試檔案是否存在（優化版）
50
51        使用 set 進行 O(1) 查詢，取代檔案系統操作。
52        """
53        issues = []
54
55        hook_name = hook_path.stem
56        test_name = f"test_{hook_name.replace('-', '_')}.py"
57
58        # 優化：O(1) 的 set 查詢，取代 O(n) 的 exists() 呼叫
59        test_exists = test_name in self.test_files
60
61        if not test_exists:
62            issues.append(
63                ValidationIssue(
64                    level="info",
65                    message=f"未找到對應的測試檔案: {test_name}",
66                    suggestion=(
67                        f"建議在以下位置建立測試:\n"
68                        f"  .claude/lib/tests/{test_name}"
69                    )
70                )
71            )
72
73        return issues

實作步驟

步驟 1：識別重複查詢

找出程式碼中哪些查詢會被重複執行：

1# 原始程式碼：每次驗證都會執行檔案系統操作
2for hook_file in hooks:
3    # possible_test_paths 中的 Path.exists() 被呼叫 2 次
4    test_exists = any(p.exists() for p in possible_test_paths)

步驟 2：收集所有可能的查詢目標

在初始化時掃描一次，建立完整的資料集：

 1def _scan_test_files(self) -> set[str]:
 2    """一次性掃描所有測試檔案"""
 3    test_files = set()
 4
 5    for test_dir in test_directories:
 6        if test_dir.is_dir():
 7            for test_file in test_dir.glob("test_*.py"):
 8                test_files.add(test_file.name)
 9
10    return test_files

步驟 3：用 set 取代 list

確保查詢容器是 set 而非 list：

1# 錯誤：用 list 儲存
2test_files = []  # O(n) 查詢
3for test_file in test_dir.glob("test_*.py"):
4    test_files.append(test_file.name)
5
6# 正確：用 set 儲存
7test_files = set()  # O(1) 查詢
8for test_file in test_dir.glob("test_*.py"):
9    test_files.add(test_file.name)

步驟 4：加入快取機制

避免重複掃描：

 1@property
 2def test_files(self) -> set[str]:
 3    """延遲初始化 + 快取"""
 4    if self._test_files_cache is None:
 5        self._test_files_cache = self._scan_test_files()
 6    return self._test_files_cache
 7
 8def clear_cache(self) -> None:
 9    """需要時可以清除快取"""
10    self._test_files_cache = None

效能測量

讓我們用 timeit 測量 list 和 set 的查詢效能差異：

 1import timeit
 2import random
 3import string
 4
 5def benchmark_membership_test():
 6    """比較 list 和 set 的成員查詢效能"""
 7
 8    # 準備測試資料
 9    def generate_filename():
10        return f"test_{''.join(random.choices(string.ascii_lowercase, k=10))}.py"
11
12    sizes = [100, 1000, 10000]
13
14    for size in sizes:
15        # 建立測試資料
16        items = [generate_filename() for _ in range(size)]
17        test_list = items.copy()
18        test_set = set(items)
19
20        # 準備查詢目標（一半存在、一半不存在）
21        existing_items = random.sample(items, min(100, size))
22        non_existing_items = [generate_filename() for _ in range(100)]
23        query_items = existing_items + non_existing_items
24        random.shuffle(query_items)
25
26        # 測量 list 查詢
27        def list_lookup():
28            for item in query_items:
29                _ = item in test_list
30
31        list_time = timeit.timeit(list_lookup, number=100)
32
33        # 測量 set 查詢
34        def set_lookup():
35            for item in query_items:
36                _ = item in test_set
37
38        set_time = timeit.timeit(set_lookup, number=100)
39
40        # 計算加速比
41        speedup = list_time / set_time
42
43        print(f"\n元素數量: {size:,}")
44        print(f"  list 查詢: {list_time:.4f} 秒")
45        print(f"  set 查詢:  {set_time:.4f} 秒")
46        print(f"  加速比:    {speedup:.1f}x")
47
48if __name__ == "__main__":
49    benchmark_membership_test()

典型執行結果：

 1元素數量: 100
 2  list 查詢: 0.0234 秒
 3  set 查詢:  0.0012 秒
 4  加速比:    19.5x
 5
 6元素數量: 1,000
 7  list 查詢: 0.2156 秒
 8  set 查詢:  0.0013 秒
 9  加速比:    165.8x
10
11元素數量: 10,000
12  list 查詢: 2.1847 秒
13  set 查詢:  0.0014 秒
14  加速比:    1560.5x

觀察重點：

set 的查詢時間幾乎不變：無論元素數量是 100 還是 10,000，set 的查詢時間都在 0.001 秒左右
list 的查詢時間線性增長：元素增加 10 倍，查詢時間也增加約 10 倍
加速比隨資料量增加：元素越多，set 的優勢越明顯

實際場景測試

模擬 Hook 驗證器的真實使用場景：

 1import timeit
 2from pathlib import Path
 3from typing import Optional, List, Set
 4
 5def benchmark_hook_validation():
 6    """模擬 Hook 驗證器的效能差異"""
 7
 8    # 模擬 200 個測試檔案
 9    test_files_list = [f"test_hook_{i}.py" for i in range(200)]
10    test_files_set = set(test_files_list)
11
12    # 模擬 100 個 Hook 要檢查
13    hooks_to_check = [f"hook_{i}" for i in range(100)]
14
15    def check_with_list():
16        """使用 list 進行查詢"""
17        results = []
18        for hook_name in hooks_to_check:
19            test_name = f"test_{hook_name}.py"
20            exists = test_name in test_files_list  # O(n)
21            results.append(exists)
22        return results
23
24    def check_with_set():
25        """使用 set 進行查詢"""
26        results = []
27        for hook_name in hooks_to_check:
28            test_name = f"test_{hook_name}.py"
29            exists = test_name in test_files_set  # O(1)
30            results.append(exists)
31        return results
32
33    # 測量效能
34    list_time = timeit.timeit(check_with_list, number=1000)
35    set_time = timeit.timeit(check_with_set, number=1000)
36
37    print(f"驗證 100 個 Hook（執行 1000 次）：")
38    print(f"  list 版本: {list_time:.4f} 秒")
39    print(f"  set 版本:  {set_time:.4f} 秒")
40    print(f"  加速比:    {list_time / set_time:.1f}x")
41
42if __name__ == "__main__":
43    benchmark_hook_validation()

典型執行結果：

1驗證 100 個 Hook（執行 1000 次）：
2  list 版本: 0.3892 秒
3  set 版本:  0.0087 秒
4  加速比:    44.7x

設計權衡

資料結構	查詢	插入	刪除	記憶體	有序	重複元素
list	O(n)	O(1)*	O(n)	低	是	允許
set	O(1)	O(1)	O(1)	高	否	不允許
dict	O(1)	O(1)	O(1)	高	是**	鍵不允許

*list 的 append 是 O(1)，insert 是 O(n)

**Python 3.7+ 的 dict 保持插入順序

記憶體使用比較

 1import sys
 2
 3def compare_memory():
 4    """比較 list 和 set 的記憶體使用"""
 5    items = list(range(10000))
 6
 7    list_version = items.copy()
 8    set_version = set(items)
 9
10    list_size = sys.getsizeof(list_version)
11    set_size = sys.getsizeof(set_version)
12
13    print(f"10,000 個整數：")
14    print(f"  list: {list_size:,} bytes")
15    print(f"  set:  {set_size:,} bytes")
16    print(f"  set/list 比率: {set_size / list_size:.2f}x")
17
18# 輸出：
19# 10,000 個整數：
20#   list: 87,624 bytes
21#   set:  524,512 bytes
22#   set/list 比率: 5.99x

權衡分析：

set 的記憶體使用約為 list 的 4-8 倍
但查詢速度可以快 10-100 倍以上
對於大多數場景，記憶體增加可以接受

何時該用 list？

需要保持順序：元素的順序很重要
需要重複元素：同一個值可能出現多次
需要索引存取：經常用 items[i] 存取
主要操作是遍歷：很少做成員查詢
資料量很小：少於 10 個元素時差異不大

1# 適合用 list 的場景
2commands = ["init", "build", "test", "deploy"]  # 需要順序
3scores = [95, 87, 95, 92, 87]  # 需要重複

何時該用 set？

主要操作是成員查詢：頻繁使用 in 運算子
需要去重：自動排除重複元素
需要集合運算：交集、聯集、差集
資料量較大：幾百個以上的元素

1# 適合用 set 的場景
2valid_extensions = {".py", ".js", ".ts"}  # 成員查詢
3seen_files = set()  # 追蹤已處理的檔案（去重）
4common_tags = tags_a & tags_b  # 集合運算

什麼時候該用這個技術？

適合使用的情況

頻繁的成員查詢：程式碼中有很多 if x in container 的檢查
查詢容器較大：容器有幾百個以上的元素
查詢頻率高：同一個容器被查詢多次
不需要元素順序：只關心「有沒有」而非「在哪裡」

不建議使用的情況

需要保持插入順序：用 list 或 dict
需要重複元素：用 list 或 collections.Counter
容器很小：10 個以下元素時差異不明顯
元素不可雜湊：list、dict 等 mutable 物件無法放入 set

1# 不可雜湊的物件無法用 set
2items = [[1, 2], [3, 4]]  # list of lists
3# set(items)  # TypeError: unhashable type: 'list'
4
5# 解法：轉換為 tuple
6items_set = {tuple(item) for item in items}  # OK

練習

基礎練習

實作去重函式：寫一個函式，用 set 去除 list 中的重複元素，同時保持原本的順序

 1def deduplicate_ordered(items: list) -> list:
 2    """
 3    去除重複元素，保持順序
 4
 5    Example:
 6        >>> deduplicate_ordered([3, 1, 2, 1, 3, 2])
 7        [3, 1, 2]
 8    """
 9    # Your implementation here
10    pass

優化單字計數器：以下程式碼檢查一段文字中有多少個「停用詞」，請用 set 優化它

 1STOP_WORDS = ["the", "a", "an", "is", "are", "was", "were", "be", "been",
 2              "being", "have", "has", "had", "do", "does", "did", "will",
 3              "would", "could", "should", "may", "might", "must", "can"]
 4
 5def count_stop_words_slow(text: str) -> int:
 6    """計算停用詞數量（待優化）"""
 7    words = text.lower().split()
 8    count = 0
 9    for word in words:
10        if word in STOP_WORDS:  # O(n) 查詢
11            count += 1
12    return count
13
14# 請優化這個函式
15def count_stop_words_fast(text: str) -> int:
16    """計算停用詞數量（優化版）"""
17    # Your implementation here
18    pass

進階練習

實作檔案比對工具：比較兩個目錄中的檔案，找出只在其中一個目錄存在的檔案

 1from pathlib import Path
 2
 3def compare_directories(dir1: Path, dir2: Path) -> dict:
 4    """
 5    比較兩個目錄的檔案
 6
 7    Returns:
 8        dict: {
 9            "only_in_dir1": set[str],
10            "only_in_dir2": set[str],
11            "in_both": set[str],
12        }
13
14    提示：使用 set 的交集、差集運算
15    """
16    # Your implementation here
17    pass

優化 Hook 驗證器：參考本文的優化方案，為 HookValidator 加入以下功能：

快取測試檔案列表
支援多個測試目錄
在測試目錄變更時自動更新快取

上一章：LRU 快取 返回：案例研究索引

ECS Fargate 成本分析與優化

Fri, 26 Jun 2026 00:00:00 +0000

Fargate 把運算的維運面外包給 AWS — 不需要管 EC2 instance、不需要管 AMI 更新、不需要管 capacity provider 的擴縮邏輯。這份簡化的代價是單位成本較高。當服務規模小或流量不穩定時，Fargate 的簡化值回票價；當服務規模穩定且持續運行時，EC2 launch type 的單位成本優勢會累積到值得切換的量級。本篇的目標是讓讀者能判斷自己的服務在成本曲線的哪個位置、以及有哪些槓桿可以調。

Fargate 計價模型

Fargate 按 task 的 vCPU 時數和記憶體時數分別計費，從 task 啟動（pull image 完成、進入 RUNNING）到停止。計費的最小粒度是一分鐘，不足一分鐘按一分鐘算。

以 ap-northeast-1（東京）為例的單價（截至撰寫時的量級參考，實際以 AWS 定價頁為準）：

資源	單價（每小時）
1 vCPU	~$0.05056
1 GB RAM	~$0.00553

一個 1 vCPU / 2 GB 的 task 持續運行一個月（730 小時）的費用約為 $0.05056 × 730 + $0.00553 × 2 × 730 ≈ $44.97。這個數字是所有後續比較的基線。

Fargate 的計費粒度還有一個常被忽略的面向：task 規格只能從 AWS 預定義的 vCPU/memory 組合中選。如果應用只需要 0.3 vCPU / 512 MB，最小可選的配置是 0.25 vCPU / 0.5 GB，但如果需要 0.3 vCPU / 1 GB，就得選 0.5 vCPU / 1 GB — 多付了 0.2 vCPU 的費用。這個「階梯式浪費」在小規格 task 上比例最高。

Fargate vs EC2 launch type 的成本比較

EC2 launch type 的成本結構不同：付的是 EC2 instance 的時數（不管上面跑幾個 task），加上 ECS 本身不收費。省的是 Fargate 的 markup，多的是 instance 管理（AMI 更新、capacity provider 設定、instance 閒置時仍計費）。

場景	Fargate 月費	EC2（t3.medium）月費	差異
1 task, 1 vCPU / 2 GB, 持續	~$45	~$30（共享 instance）	+50%
5 tasks, 各 0.5 vCPU / 1 GB	~$113	~$30（1 台 t3.medium 裝得下）	+277%
20 tasks, 各 1 vCPU / 2 GB	~$900	~$240（4 台 t3.xlarge）	+275%
流量波動大，尖峰 10 tasks / 離峰 1	~$180（加權平均）	~$150（需預留尖峰容量）	+20%

幾個判讀要點：

task 數量少且持續運行時，Fargate 的溢價比例最高（+50% 到 +277%），但絕對金額小（$15-$80/月的差距），不值得為此承擔 instance 管理的維運負擔
task 數量多且持續運行時，EC2 的絕對節省量開始可觀（$660/月），這時候切換的維運成本有回報
流量波動大時，Fargate 的優勢是按需計費 — 離峰時 task 數降下來就停止計費，EC2 instance 閒置時仍然計費。波動越大，Fargate 的成本效益越接近或超過 EC2

Fargate Spot

Fargate Spot 使用 AWS 的閒置容量，價格約為 on-demand 的 30%（折扣幅度 ~70%），代價是 AWS 可以隨時回收容量、task 會收到 SIGTERM 後被終止。

適用條件：task 能在 120 秒內優雅停止、應用有重試機制或上游有 load balancer 自動移除不健康的 target。批次處理、背景 worker、可中斷的佇列消費者是典型的 Spot 候選。對外直接服務的 API 通常混合部署 — 基線容量用 on-demand、彈性擴張部分用 Spot。

 1resource "aws_ecs_service" "api" {
 2  # ...
 3
 4  capacity_provider_strategy {
 5    capacity_provider = "FARGATE"
 6    weight            = 1
 7    base              = 2  # 至少 2 個 on-demand task 保底
 8  }
 9
10  capacity_provider_strategy {
11    capacity_provider = "FARGATE_SPOT"
12    weight            = 3  # 擴張時 3/4 的 task 用 Spot
13  }
14}

base = 2 確保至少有兩個 on-demand task 在線（不會被回收），weight 比例讓後續擴張的 task 優先使用 Spot。中斷發生時 ECS 會自動在 on-demand 上補充，但補充需要時間（task 啟動 + health check 通過），這段期間服務容量會短暫下降。

Compute Savings Plans

Compute Savings Plans 是對 Fargate（和 EC2、Lambda）的預付承諾折扣：承諾每小時固定消費 X 美元的運算量，換取 1 年或 3 年的折扣（1 年約 -20%、3 年約 -40%，視具體方案）。

關鍵判斷：承諾量（$/hr）設在實際用量的多少比例。保守做法是設在過去 3 個月最低用量的 80% — 這部分幾乎確定會用到，享受折扣；超過承諾量的部分自動按 on-demand 計費，不會浪費。

1# 查過去 90 天的 Fargate 用量趨勢
2aws ce get-cost-and-usage \
3  --time-period Start=2026-03-01,End=2026-06-01 \
4  --granularity MONTHLY \
5  --metrics "UnblendedCost" \
6  --filter '{"Dimensions":{"Key":"SERVICE","Values":["Amazon Elastic Container Service"]}}'

Savings Plans 跟 Fargate Spot 可以疊加：Spot task 的費用也能用 Savings Plans 折抵。先用 Savings Plans 降低基線成本，再用 Spot 降低彈性擴張的成本，兩層折扣疊起來可以把 Fargate 的實際單價壓到接近 EC2 on-demand。

Task 規格的 rightsizing

Fargate task 的 vCPU 和記憶體配置如果設得過大，多出來的資源每小時都在計費。rightsizing 的目標是讓 task 規格貼合實際使用量，但留足安全餘裕。

量測實際使用量

開啟 CloudWatch Container Insights 後，每個 task 的 CPU 和記憶體使用量會自動上報。觀察 7-14 天的 p95 值：

1# 查 ECS service 過去 7 天的 CPU p95
2aws cloudwatch get-metric-statistics \
3  --namespace ECS/ContainerInsights \
4  --metric-name CpuUtilized \
5  --dimensions Name=ServiceName,Value=api Name=ClusterName,Value=prod \
6  --start-time 2026-06-19T00:00:00Z \
7  --end-time 2026-06-26T00:00:00Z \
8  --period 3600 \
9  --statistics p95

判斷調整方向

p95 使用率	判斷	動作
CPU < 30%	過度配置，浪費明顯	降一級 vCPU
CPU 30-70%	合理範圍，有足夠餘裕應對尖峰	維持
CPU > 80%	餘裕不足，尖峰時可能觸發 throttling	升一級 vCPU 或增加 task 數
Memory < 40%	過度配置	降一級 memory
Memory > 80%	OOM kill 風險	升一級 memory

調整後觀察 3-5 天確認沒有效能退化再進入下一輪。每次只調一個維度（CPU 或 memory），避免同時改兩個變數無法歸因。

Fargate 可選的規格組合

Fargate 的 vCPU 和 memory 不能任意搭配。常用的組合：

vCPU	可選 Memory 範圍	典型用途
0.25	0.5 / 1 / 2 GB	輕量 sidecar、cron job
0.5	1 / 2 / 3 / 4 GB	小型 API、worker
1	2 / 3 / 4 / 5 / 6 / 7 / 8 GB	標準 API、中型 worker
2	4 ~ 16 GB	高負載 API、批次處理
4	8 ~ 30 GB	資料處理、ML inference

選的時候從最小的「能跑」組合開始，用 Container Insights 量測後再調。常見的浪費是把所有 task 都設成 1 vCPU / 2 GB — 一個只用 0.1 vCPU / 256 MB 的 sidecar 也配了同樣的規格。

何時從 Fargate 切到 EC2

切換的判斷不只看成本差額，還要看維運能力。EC2 launch type 需要管理：AMI 更新（安全 patch）、instance draining（rolling update 時把 task 遷走再關 instance）、capacity provider 的擴縮邏輯、instance 的 security group 與 IAM role。

判斷維度	留在 Fargate	切到 EC2
月費差額	< $200	> $500 且持續 3 個月
團隊維運能力	沒有專人管 instance	有平台工程師或 DevOps
流量型態	波動大、有明顯離峰	穩定、24/7 持續運行
GPU 需求	不需要	需要（Fargate 不支援 GPU）
啟動速度	可接受 cold start	需要 <1s 啟動（EC2 instance 已在線）

混合部署是常見的中間路線：基線容量用 EC2（成本低、啟動快），尖峰彈性用 Fargate Spot（按需、不需預留）。這需要同時維護兩種 capacity provider，複雜度較高。

成本監控

把 ECS 的成本歸因到服務層級需要兩個機制：task 層的 tag propagation 和 Cost Explorer 的 tag 維度。

 1resource "aws_ecs_service" "api" {
 2  # ...
 3  propagate_tags = "SERVICE"
 4
 5  tags = {
 6    service     = "payment-api"
 7    env         = "prod"
 8    cost-center = "cc-payments"
 9  }
10}

propagate_tags = "SERVICE" 讓 service 的 tag 自動傳播到每個 task，Cost Explorer 就能按 service 或 cost-center 維度拆分 Fargate 費用。這跟模組八：治理好習慣的 tagging 規範對齊 — tag 是成本可見性的地基。

定期（月初或月中）檢查 Cost Explorer 的 Fargate 費用趨勢：

1aws ce get-cost-and-usage \
2  --time-period Start=2026-06-01,End=2026-06-26 \
3  --granularity DAILY \
4  --metrics "UnblendedCost" \
5  --group-by Type=TAG,Key=service \
6  --filter '{"Dimensions":{"Key":"SERVICE","Values":["Amazon Elastic Container Service"]}}'

費用突然跳升時，先看是 task 數增加（auto-scaling 觸發）還是單價變化（Savings Plans 過期或 Spot 中斷後自動回補為 on-demand）。這兩者的處理方式不同：前者檢查 scaling policy、後者檢查 Savings Plans 到期日和 Spot 回收頻率。

跨分類引用

→ 運算平台上 IaC：ECS vs EKS 選型、Fargate 的定位
→ 模組八：治理好習慣：tagging 與成本可見性的地基
→ devops 模組八：成本管理：運行期的 RI / Spot / rightsizing 策略

模組八：實戰效能優化

Wed, 21 Jan 2026 00:00:00 +0000

本模組將入門系列學到的「並行處理」和「效能優化」知識，應用於 .claude/lib 的實際程式碼，展示如何分析、測量、優化真實系統。

與入門系列的關係

1入門系列 本模組
23.7 並行處理 ──────────────────→ 並行處理實戰
3 (概念與 API) (應用於真實系統)
4
53.8 效能優化 ──────────────────→ 效能調優實戰
6 (原則與工具) (實際測量與改善)

入門系列教你「工具怎麼用」，本模組教你「什麼時候用、用了效果如何」。

為什麼需要這個模組？

在入門系列中，我們學習了：

ThreadPoolExecutor 和 ProcessPoolExecutor 的用法
timeit、cProfile 等效能測量工具
正則表達式、資料結構選擇等優化技巧

但在實際專案中，你可能會問：

這段程式碼值得優化嗎？ → 需要先測量
用並行能快多少？ → 需要實際比較
優化後維護成本增加多少？ → 需要權衡

本模組透過真實案例回答這些問題。

章節列表

章節	主題	關鍵收穫
8.1	並行處理實戰	將 I/O 密集任務並行化
8.2	效能調優實戰	測量、分析、優化的完整流程

案例研究

基於 .claude/lib 實際程式碼的進階案例：

案例	素材	學習重點
並行檔案檢查	markdown_link_checker.py	ThreadPoolExecutor
並行 Hook 驗證	hook_validator.py	as_completed + 進度報告
正則表達式預編譯	hook_validator.py	re.compile 效能提升
LRU 快取	git_utils.py	functools.lru_cache
資料結構選擇	hook_validator.py	list vs set 查詢效能

可執行程式碼

本模組提供完整的可執行程式碼，放在 /static/code/practical-optimization/：

1practical-optimization/
2├── original/ # 原始版本（對照組）
3├── optimized/ # 優化版本
4├── benchmarks/ # 效能測試腳本
5└── profiling/ # 效能分析腳本

你可以下載這些程式碼，在自己的環境中執行效能測試。

先備知識

章節	需要先讀
8.1 並行處理實戰	入門系列 3.7 並行處理
8.2 效能調優實戰	入門系列 3.8 效能優化

學習目標

完成本模組後，你將能夠：

識別優化機會：判斷哪些程式碼值得優化
測量效能基準：使用 cProfile、timeit 建立基準數據
應用並行處理：選擇適當的並行模式加速 I/O 任務
實施效能優化：正則預編譯、快取策略、資料結構選擇
評估優化效果：比較優化前後的效能差異

學習時間

每章節約 30-45 分鐘，全模組約 2-3 小時

上一模組：模組七：打包與發布

案例研究：效能優化實戰

Wed, 21 Jan 2026 00:00:00 +0000

本系列案例基於 .claude/lib 的實際程式碼，展示如何用並行處理和效能優化技術改善真實系統。

案例列表

並行處理

案例	素材	技術	預期加速
並行檔案檢查	markdown_link_checker.py	ThreadPoolExecutor	3-5x
並行 Hook 驗證	hook_validator.py	as_completed + 進度	3-5x

效能調優

案例	素材	技術	預期加速
正則表達式預編譯	hook_validator.py	re.compile	1.2-1.3x
LRU 快取	git_utils.py	functools.lru_cache	視命中率
資料結構選擇	hook_validator.py	set vs list	10-100x

學習路徑

1並行檔案檢查（入門）
2 ↓
3並行 Hook 驗證（進階：含進度報告）
4 ↓
5正則表達式預編譯（效能調優入門）
6 ↓
7LRU 快取（快取策略）
8 ↓
9資料結構選擇（演算法思維）

可執行程式碼

所有案例都有對應的可執行程式碼：

 1# 下載程式碼
 2cd /path/to/your/workspace
 3
 4# 執行效能測試
 5python benchmarks/benchmark_parallel.py
 6python benchmarks/benchmark_regex.py
 7python benchmarks/benchmark_cache.py
 8python benchmarks/benchmark_data_structure.py
 9
10# 執行效能分析
11python profiling/profile_link_checker.py

先備知識

建議先完成以下章節：

返回：模組八：實戰效能優化