案例研究：效能優化實戰 on Tarragon

案例：並行檔案檢查

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 驗證

案例：並行 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/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 快取 返回：案例研究索引