Design-Patterns on Tarragon

案例：快取生命週期管理

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

本案例基於 .claude/lib/config_loader.py 的實際程式碼，展示如何用 Context Manager 管理快取生命週期。

先備知識

3.3 進階上下文管理

問題背景

現有設計

config_loader.py 使用全域變數實現快取：

 1# 全域快取變數
 2_agents_config_cache: Optional[dict] = None
 3_quality_rules_cache: Optional[dict] = None
 4
 5def load_agents_config() -> dict:
 6 """
 7 載入代理人配置
 8
 9 使用全域快取避免重複讀取檔案。
10 """
11 global _agents_config_cache
12 if _agents_config_cache is None:
13 try:
14 _agents_config_cache = load_config("agents")
15 except FileNotFoundError:
16 _agents_config_cache = _get_default_agents_config()
17 return _agents_config_cache
18
19def load_quality_rules() -> dict:
20 """載入品質規則配置"""
21 global _quality_rules_cache
22 if _quality_rules_cache is None:
23 try:
24 _quality_rules_cache = load_config("quality_rules")
25 except FileNotFoundError:
26 _quality_rules_cache = _get_default_quality_rules()
27 return _quality_rules_cache
28
29def clear_config_cache() -> None:
30 """清除配置快取（用於測試或配置熱更新）"""
31 global _agents_config_cache, _quality_rules_cache
32 _agents_config_cache = None
33 _quality_rules_cache = None

這個設計的優點

簡單直覺：全域變數是最簡單的快取方式
效能好：配置只讀取一次
API 簡潔：呼叫者不需要管理快取

這個設計的限制

問題 1：測試難以隔離

 1def test_load_agents_config():
 2 # 測試 A：預設配置
 3 config = load_agents_config()
 4 assert "known_agents" in config
 5
 6def test_load_agents_config_custom():
 7 # 測試 B：自訂配置檔案
 8 # 問題：測試 A 的快取會影響測試 B！
 9 config = load_agents_config()
10 # 可能拿到測試 A 的快取結果

問題 2：快取生命週期不明確

1def process_hooks():
2 config = load_agents_config()
3 # ... 處理完成
4
5 # 問題：什麼時候應該清除快取？
6 # 如果配置檔案改了，這裡會用到舊的快取

問題 3：清除快取容易忘記

1def test_something():
2 # 設定測試環境
3 os.environ["CLAUDE_PROJECT_DIR"] = "/tmp/test"
4
5 # 執行測試
6 config = load_agents_config()
7
8 # 問題：忘記清除快取！
9 # 下一個測試會用到這個測試的快取

進階解決方案：Context Manager 管理快取

設計目標

明確的快取範圍：快取的生命週期有明確的開始和結束
自動清理：離開範圍時自動清除快取
測試友好：每個測試可以有獨立的快取

實作步驟

步驟 1：建立快取管理類別

 1from contextlib import contextmanager
 2from pathlib import Path
 3from typing import Any, Iterator, Optional
 4import os
 5
 6class ConfigManager:
 7 """
 8 配置管理器
 9
10 用 Context Manager 控制快取的生命週期，
11 解決全域快取的問題。
12 """
13
14 def __init__(self, project_root: Optional[str] = None):
15 """
16 初始化配置管理器
17
18 Args:
19 project_root: 專案根目錄，預設從環境變數讀取
20 """
21 if project_root is None:
22 project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
23 self.project_root = Path(project_root)
24 self._cache: dict[str, Any] = {}
25
26 @property
27 def config_dir(self) -> Path:
28 """配置目錄路徑"""
29 return self.project_root / ".claude" / "config"
30
31 def load_config(self, name: str) -> dict:
32 """
33 載入配置（使用快取）
34
35 Args:
36 name: 配置名稱
37
38 Returns:
39 配置內容
40 """
41 if name not in self._cache:
42 self._cache[name] = self._load_from_file(name)
43 return self._cache[name]
44
45 def _load_from_file(self, name: str) -> dict:
46 """從檔案載入配置（內部方法）"""
47 yaml_path = self.config_dir / f"{name}.yaml"
48 if yaml_path.exists():
49 import yaml
50 with open(yaml_path, "r", encoding="utf-8") as f:
51 return yaml.safe_load(f) or {}
52 raise FileNotFoundError(f"Config not found: {name}")
53
54 def clear_cache(self) -> None:
55 """清除所有快取"""
56 self._cache.clear()

步驟 2：加入 Context Manager 支援

 1class ConfigManager:
 2 # ... 前面的程式碼 ...
 3
 4 @contextmanager
 5 def cached_scope(self) -> Iterator["ConfigManager"]:
 6 """
 7 快取範圍 Context Manager
 8
 9 在這個範圍內，配置會被快取。
10 離開範圍時自動清除快取。
11
12 Yields:
13 ConfigManager: 自己，方便鏈式呼叫
14
15 Example:
16 manager = ConfigManager()
17 with manager.cached_scope():
18 config = manager.load_config("agents")
19 # ... 使用配置 ...
20 # 離開時快取自動清除
21 """
22 try:
23 yield self
24 finally:
25 self.clear_cache()
26
27 @contextmanager
28 def isolated_scope(
29 self,
30 project_root: Optional[str] = None
31 ) -> Iterator["ConfigManager"]:
32 """
33 隔離範圍 Context Manager
34
35 建立一個完全隔離的配置環境，
36 適合用於測試。
37
38 Args:
39 project_root: 臨時的專案根目錄
40
41 Yields:
42 ConfigManager: 新的管理器實例
43
44 Example:
45 with manager.isolated_scope("/tmp/test") as isolated:
46 config = isolated.load_config("agents")
47 # 完全隔離，不影響原本的 manager
48 """
49 isolated_manager = ConfigManager(
50 project_root=project_root or str(self.project_root)
51 )
52 try:
53 yield isolated_manager
54 finally:
55 isolated_manager.clear_cache()

步驟 3：加入便利方法

 1class ConfigManager:
 2 # ... 前面的程式碼 ...
 3
 4 def load_agents_config(self) -> dict:
 5 """載入代理人配置（帶預設值）"""
 6 try:
 7 return self.load_config("agents")
 8 except FileNotFoundError:
 9 return self._get_default_agents_config()
10
11 def load_quality_rules(self) -> dict:
12 """載入品質規則配置（帶預設值）"""
13 try:
14 return self.load_config("quality_rules")
15 except FileNotFoundError:
16 return self._get_default_quality_rules()
17
18 def _get_default_agents_config(self) -> dict:
19 """預設代理人配置"""
20 return {
21 "known_agents": ["basil", "thyme", "mint"],
22 "agent_dispatch_rules": {},
23 }
24
25 def _get_default_quality_rules(self) -> dict:
26 """預設品質規則配置"""
27 return {
28 "trigger_conditions": {"allowed_tools": ["Write", "Edit"]},
29 "cache": {"ttl_minutes": 5},
30 }

完整程式碼

 1#!/usr/bin/env python3
 2"""
 3快取生命週期管理 - 完整範例
 4
 5展示如何用 Context Manager 管理配置快取的生命週期。
 6"""
 7
 8from contextlib import contextmanager
 9from pathlib import Path
 10from typing import Any, Iterator, Optional
 11import os
 12
 13try:
 14 import yaml
 15 HAS_YAML = True
 16except ImportError:
 17 HAS_YAML = False
 18 import json
 19
 20class ConfigManager:
 21 """
 22 配置管理器
 23
 24 用 Context Manager 控制快取的生命週期。
 25 """
 26
 27 def __init__(self, project_root: Optional[str] = None):
 28 if project_root is None:
 29 project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 30 self.project_root = Path(project_root)
 31 self._cache: dict[str, Any] = {}
 32
 33 @property
 34 def config_dir(self) -> Path:
 35 return self.project_root / ".claude" / "config"
 36
 37 # ===== 載入方法 =====
 38
 39 def load_config(self, name: str) -> dict:
 40 """載入配置（使用快取）"""
 41 if name not in self._cache:
 42 self._cache[name] = self._load_from_file(name)
 43 return self._cache[name]
 44
 45 def _load_from_file(self, name: str) -> dict:
 46 """從檔案載入配置"""
 47 yaml_path = self.config_dir / f"{name}.yaml"
 48 json_path = self.config_dir / f"{name}.json"
 49
 50 if yaml_path.exists() and HAS_YAML:
 51 with open(yaml_path, "r", encoding="utf-8") as f:
 52 return yaml.safe_load(f) or {}
 53
 54 if json_path.exists():
 55 with open(json_path, "r", encoding="utf-8") as f:
 56 return json.load(f)
 57
 58 raise FileNotFoundError(f"Config not found: {name}")
 59
 60 def clear_cache(self) -> None:
 61 """清除所有快取"""
 62 self._cache.clear()
 63
 64 # ===== Context Manager =====
 65
 66 @contextmanager
 67 def cached_scope(self) -> Iterator["ConfigManager"]:
 68 """快取範圍：離開時自動清除快取"""
 69 try:
 70 yield self
 71 finally:
 72 self.clear_cache()
 73
 74 @contextmanager
 75 def isolated_scope(
 76 self,
 77 project_root: Optional[str] = None
 78 ) -> Iterator["ConfigManager"]:
 79 """隔離範圍：建立獨立的配置環境"""
 80 isolated = ConfigManager(project_root or str(self.project_root))
 81 try:
 82 yield isolated
 83 finally:
 84 isolated.clear_cache()
 85
 86 # ===== 便利方法 =====
 87
 88 def load_agents_config(self) -> dict:
 89 """載入代理人配置"""
 90 try:
 91 return self.load_config("agents")
 92 except FileNotFoundError:
 93 return {"known_agents": [], "agent_dispatch_rules": {}}
 94
 95 def load_quality_rules(self) -> dict:
 96 """載入品質規則配置"""
 97 try:
 98 return self.load_config("quality_rules")
 99 except FileNotFoundError:
100 return {"trigger_conditions": {}, "cache": {"ttl_minutes": 5}}
101
102# ===== 全域便利函式（相容舊 API）=====
103
104_default_manager: Optional[ConfigManager] = None
105
106def get_config_manager() -> ConfigManager:
107 """獲取預設的配置管理器"""
108 global _default_manager
109 if _default_manager is None:
110 _default_manager = ConfigManager()
111 return _default_manager
112
113def load_agents_config() -> dict:
114 """相容舊 API：載入代理人配置"""
115 return get_config_manager().load_agents_config()
116
117def load_quality_rules() -> dict:
118 """相容舊 API：載入品質規則配置"""
119 return get_config_manager().load_quality_rules()
120
121@contextmanager
122def config_scope(project_root: Optional[str] = None) -> Iterator[ConfigManager]:
123 """
124 配置範圍 Context Manager
125
126 建立一個有明確生命週期的配置環境。
127
128 Args:
129 project_root: 專案根目錄
130
131 Yields:
132 ConfigManager: 配置管理器
133
134 Example:
135 with config_scope("/path/to/project") as config:
136 agents = config.load_agents_config()
137 rules = config.load_quality_rules()
138 # 離開時快取自動清除
139 """
140 manager = ConfigManager(project_root)
141 with manager.cached_scope():
142 yield manager
143
144# ===== 測試範例 =====
145
146if __name__ == "__main__":
147 import tempfile
148
149 # 建立測試配置
150 with tempfile.TemporaryDirectory() as tmpdir:
151 config_dir = Path(tmpdir) / ".claude" / "config"
152 config_dir.mkdir(parents=True)
153
154 # 寫入測試配置
155 (config_dir / "agents.json").write_text(
156 '{"known_agents": ["test-agent-1", "test-agent-2"]}'
157 )
158
159 # 使用 Context Manager
160 with config_scope(tmpdir) as config:
161 agents = config.load_agents_config()
162 print(f"代理人配置: {agents}")
163
164 # 第二次呼叫會使用快取
165 agents2 = config.load_agents_config()
166 print(f"快取命中: {agents is agents2}")
167
168 # 離開範圍後快取已清除
169 print("離開範圍，快取已清除")
170
171 # 測試隔離範圍
172 print("\n=== 測試隔離範圍 ===")
173 manager = ConfigManager()
174
175 with manager.isolated_scope() as isolated:
176 # 隔離環境
177 try:
178 config = isolated.load_config("nonexistent")
179 except FileNotFoundError as e:
180 print(f"預期的錯誤: {e}")
181
182 print("隔離範圍結束")

使用範例

基本使用

 1# 建立配置管理器
 2manager = ConfigManager()
 3
 4# 使用快取範圍
 5with manager.cached_scope():
 6 agents = manager.load_agents_config()
 7 rules = manager.load_quality_rules()
 8
 9 # 第二次呼叫會使用快取
10 agents2 = manager.load_agents_config()
11 assert agents is agents2 # 同一個物件
12
13# 離開範圍後快取已清除

測試中使用

 1import pytest
 2from pathlib import Path
 3import tempfile
 4
 5@pytest.fixture
 6def config_manager():
 7 """測試用的配置管理器"""
 8 with tempfile.TemporaryDirectory() as tmpdir:
 9 # 準備測試配置
10 config_dir = Path(tmpdir) / ".claude" / "config"
11 config_dir.mkdir(parents=True)
12 (config_dir / "agents.json").write_text(
13 '{"known_agents": ["test-agent"]}'
14 )
15
16 # 使用隔離範圍
17 manager = ConfigManager()
18 with manager.isolated_scope(tmpdir) as isolated:
19 yield isolated
20
21def test_load_agents_config(config_manager):
22 """測試載入代理人配置"""
23 config = config_manager.load_agents_config()
24 assert config["known_agents"] == ["test-agent"]
25
26def test_cache_works(config_manager):
27 """測試快取功能"""
28 config1 = config_manager.load_agents_config()
29 config2 = config_manager.load_agents_config()
30 assert config1 is config2 # 同一個物件

相容舊 API

1# 如果有既有程式碼使用舊 API
2from config_loader import load_agents_config, config_scope
3
4# 舊的呼叫方式仍然可用
5config = load_agents_config()
6
7# 新的呼叫方式有明確的生命週期
8with config_scope() as manager:
9 config = manager.load_agents_config()

設計權衡

面向	全域快取	Context Manager
簡單性	最簡單	需要理解 Context Manager
生命週期	不明確（程式結束前一直存在）	明確（範圍結束時清除）
測試隔離	困難（需要手動清除）	容易（自動隔離）
並行安全	不安全（共用全域變數）	可以安全（每個範圍獨立）
記憶體管理	可能洩漏	自動清理
API 相容性	N/A	可以相容舊 API

什麼時候該用 Context Manager 管理快取？

適合使用：

3.5.1 泛型進階

Tue, 20 Jan 2026 00:00:00 +0000

入門系列介紹了 TypeVar 的基本用法。本章深入探討泛型的進階特性，讓你能夠建立型別安全的抽象層。

先備知識

入門系列 2.2 Optional、Union、泛型

TypeVar 進階

bound 參數

bound 限制 TypeVar 必須是某個型別的子型別：

 1from typing import TypeVar
 2
 3class Animal:
 4    def speak(self) -> str:
 5        return "..."
 6
 7class Dog(Animal):
 8    def speak(self) -> str:
 9        return "Woof!"
10
11class Cat(Animal):
12    def speak(self) -> str:
13        return "Meow!"
14
15# T 必須是 Animal 或其子類別
16T = TypeVar("T", bound=Animal)
17
18def make_speak(animal: T) -> str:
19    return animal.speak()  # 型別檢查器知道 animal 有 speak() 方法
20
21# 正確使用
22make_speak(Dog())  # OK
23make_speak(Cat())  # OK
24
25# 錯誤使用
26make_speak("not an animal")  # 型別錯誤

bound vs 限制型別

1from typing import TypeVar
2
3# 方式一：bound - T 可以是 Animal 或任何子類別
4T_bound = TypeVar("T_bound", bound=Animal)
5
6# 方式二：限制型別 - T 只能是 Dog 或 Cat，不能是其他 Animal 子類別
7T_constrained = TypeVar("T_constrained", Dog, Cat)

差異：

方式	適用情況
`bound=Animal`	T 可以是 Animal 或任何子類別（包括未來新增的）
`TypeVar("T", Dog, Cat)`	T 只能是明確列出的型別

covariant 與 contravariant

這是泛型最難理解的概念，但對於設計型別安全的 API 非常重要。

問題情境

 1class Animal:
 2    pass
 3
 4class Dog(Animal):
 5    pass
 6
 7# 問題：List[Dog] 是 List[Animal] 的子型別嗎？
 8def process_animals(animals: list[Animal]) -> None:
 9    animals.append(Animal())  # 如果傳入 list[Dog]，這會破壞型別安全
10
11dogs: list[Dog] = [Dog(), Dog()]
12process_animals(dogs)  # 如果允許，dogs 裡面會有 Animal！

Python 的 list 是不變的（invariant），所以 list[Dog] 不是 list[Animal] 的子型別。

covariant（協變）

只讀的容器可以是協變的：

 1from typing import TypeVar, Generic, Iterator
 2
 3T_co = TypeVar("T_co", covariant=True)
 4
 5class ReadOnlyBox(Generic[T_co]):
 6    """只能讀取，不能修改"""
 7    def __init__(self, value: T_co) -> None:
 8        self._value = value
 9
10    def get(self) -> T_co:
11        return self._value
12
13# ReadOnlyBox[Dog] 是 ReadOnlyBox[Animal] 的子型別
14def show_animal(box: ReadOnlyBox[Animal]) -> None:
15    print(box.get())
16
17dog_box: ReadOnlyBox[Dog] = ReadOnlyBox(Dog())
18show_animal(dog_box)  # OK - Dog 是 Animal

記憶方式：協變 = 輸出方向，子型別可以替代父型別。

contravariant（逆變）

只寫的容器可以是逆變的：

 1from typing import TypeVar, Generic
 2
 3T_contra = TypeVar("T_contra", contravariant=True)
 4
 5class Handler(Generic[T_contra]):
 6    """處理器：只接收值"""
 7    def handle(self, value: T_contra) -> None:
 8        print(f"Handling: {value}")
 9
10# Handler[Animal] 是 Handler[Dog] 的子型別！（反直覺）
11def setup_dog_handler(handler: Handler[Dog]) -> None:
12    handler.handle(Dog())
13
14animal_handler: Handler[Animal] = Handler()
15setup_dog_handler(animal_handler)  # OK - 能處理 Animal 就能處理 Dog

記憶方式：逆變 = 輸入方向，父型別可以替代子型別。

實際應用

 1from typing import Callable
 2
 3# Callable 的參數是逆變的，返回值是協變的
 4# Callable[[Animal], Dog] 是 Callable[[Dog], Animal] 的子型別
 5
 6def process(func: Callable[[Dog], Animal]) -> None:
 7    result = func(Dog())
 8    print(result)
 9
10def any_animal_to_dog(animal: Animal) -> Dog:
11    return Dog()
12
13process(any_animal_to_dog)  # OK

Generic 類別

建立自己的泛型容器

 1from typing import TypeVar, Generic, Optional
 2
 3T = TypeVar("T")
 4
 5class Stack(Generic[T]):
 6    """型別安全的堆疊"""
 7
 8    def __init__(self) -> None:
 9        self._items: list[T] = []
10
11    def push(self, item: T) -> None:
12        self._items.append(item)
13
14    def pop(self) -> Optional[T]:
15        if self._items:
16            return self._items.pop()
17        return None
18
19    def peek(self) -> Optional[T]:
20        if self._items:
21            return self._items[-1]
22        return None
23
24# 使用
25int_stack: Stack[int] = Stack()
26int_stack.push(1)
27int_stack.push(2)
28int_stack.push("three")  # 型別錯誤！
29
30str_stack: Stack[str] = Stack()
31str_stack.push("hello")

多型別參數

 1from typing import TypeVar, Generic
 2
 3K = TypeVar("K")
 4V = TypeVar("V")
 5
 6class Pair(Generic[K, V]):
 7    """鍵值對"""
 8
 9    def __init__(self, key: K, value: V) -> None:
10        self.key = key
11        self.value = value
12
13    def swap(self) -> "Pair[V, K]":
14        return Pair(self.value, self.key)
15
16# 使用
17pair: Pair[str, int] = Pair("age", 25)
18swapped: Pair[int, str] = pair.swap()

繼承泛型類別

 1from typing import TypeVar, Generic
 2
 3T = TypeVar("T")
 4
 5class Container(Generic[T]):
 6    def __init__(self, value: T) -> None:
 7        self.value = value
 8
 9# 方式一：保持泛型
10class Box(Container[T]):
11    def unwrap(self) -> T:
12        return self.value
13
14# 方式二：具體化型別
15class StringBox(Container[str]):
16    def upper(self) -> str:
17        return self.value.upper()

Protocol 與結構化子型別

什麼是 Protocol？

Protocol 定義「介面」，任何實現該介面的類別都被視為符合該 Protocol，無需明確繼承。

 1from typing import Protocol
 2
 3class Drawable(Protocol):
 4    def draw(self) -> str:
 5        ...
 6
 7# 這個類別沒有繼承 Drawable，但符合 Protocol
 8class Circle:
 9    def draw(self) -> str:
10        return "○"
11
12class Square:
13    def draw(self) -> str:
14        return "□"
15
16def render(shape: Drawable) -> None:
17    print(shape.draw())
18
19render(Circle())  # OK - Circle 有 draw() 方法
20render(Square())  # OK - Square 有 draw() 方法

Protocol vs ABC

特性	Protocol	ABC
繼承要求	不需要	需要
型別檢查	結構化（duck typing）	名義上（nominal）
執行期檢查	需要 `runtime_checkable`	內建
適用場景	第三方類別、鬆散耦合	自己控制的類別層級

 1from abc import ABC, abstractmethod
 2from typing import Protocol, runtime_checkable
 3
 4# ABC 方式
 5class DrawableABC(ABC):
 6    @abstractmethod
 7    def draw(self) -> str:
 8        ...
 9
10class CircleABC(DrawableABC):  # 必須繼承
11    def draw(self) -> str:
12        return "○"
13
14# Protocol 方式
15@runtime_checkable
16class DrawableProtocol(Protocol):
17    def draw(self) -> str:
18        ...
19
20class CircleProtocol:  # 不需要繼承
21    def draw(self) -> str:
22        return "○"
23
24# 執行期檢查
25print(isinstance(CircleProtocol(), DrawableProtocol))  # True

何時選擇 Protocol？

 1# 使用 Protocol 的情況：
 2
 3# 1. 處理第三方類別
 4class JSONSerializable(Protocol):
 5    def to_json(self) -> str:
 6        ...
 7
 8# 第三方類別可能已經有 to_json()，不需要修改它們
 9
10# 2. 定義回調介面
11class EventHandler(Protocol):
12    def on_event(self, event: dict) -> None:
13        ...
14
15# 任何有 on_event 方法的類別或函式都可以使用
16
17# 3. 鬆散耦合
18class Closeable(Protocol):
19    def close(self) -> None:
20        ...
21
22def cleanup(resource: Closeable) -> None:
23    resource.close()
24
25# 檔案、連接、任何有 close() 的東西都可以用

帶有屬性的 Protocol

 1from typing import Protocol
 2
 3class Named(Protocol):
 4    name: str  # 只需要有這個屬性
 5
 6class Person:
 7    def __init__(self, name: str) -> None:
 8        self.name = name
 9
10class Company:
11    name: str = "Acme Corp"
12
13def greet(entity: Named) -> str:
14    return f"Hello, {entity.name}!"
15
16greet(Person("Alice"))  # OK
17greet(Company())        # OK

實際範例：型別安全的 Repository 介面

結合以上所有概念，建立一個型別安全的資料存取層：

 1from typing import TypeVar, Generic, Protocol, Optional
 2from abc import abstractmethod
 3
 4# 定義實體必須有 id 屬性
 5class HasId(Protocol):
 6    id: int
 7
 8# 泛型 Repository 介面
 9T = TypeVar("T", bound=HasId)
10
11class Repository(Generic[T]):
12    """資料存取層的抽象介面"""
13
14    @abstractmethod
15    def get(self, id: int) -> Optional[T]:
16        """根據 ID 取得實體"""
17        ...
18
19    @abstractmethod
20    def save(self, entity: T) -> T:
21        """儲存實體"""
22        ...
23
24    @abstractmethod
25    def delete(self, id: int) -> bool:
26        """刪除實體"""
27        ...
28
29    @abstractmethod
30    def find_all(self) -> list[T]:
31        """取得所有實體"""
32        ...
33
34# 具體實現
35class User:
36    def __init__(self, id: int, name: str) -> None:
37        self.id = id
38        self.name = name
39
40class InMemoryUserRepository(Repository[User]):
41    """記憶體中的 User Repository"""
42
43    def __init__(self) -> None:
44        self._storage: dict[int, User] = {}
45        self._next_id = 1
46
47    def get(self, id: int) -> Optional[User]:
48        return self._storage.get(id)
49
50    def save(self, entity: User) -> User:
51        if entity.id == 0:
52            entity.id = self._next_id
53            self._next_id += 1
54        self._storage[entity.id] = entity
55        return entity
56
57    def delete(self, id: int) -> bool:
58        if id in self._storage:
59            del self._storage[id]
60            return True
61        return False
62
63    def find_all(self) -> list[User]:
64        return list(self._storage.values())
65
66# 使用
67def process_user(repo: Repository[User], user_id: int) -> None:
68    user = repo.get(user_id)
69    if user:
70        print(f"Found user: {user.name}")
71
72# 型別安全：不能把 UserRepository 傳給需要 Repository[Product] 的函式

常見錯誤

1. 忘記 TypeVar 的名稱參數

1# 錯誤
2T = TypeVar()  # TypeError
3
4# 正確
5T = TypeVar("T")

2. 在類別方法中重複定義 TypeVar

 1T = TypeVar("T")
 2
 3class Box(Generic[T]):
 4    # 錯誤：方法內重新定義 T
 5    def transform(self, func: Callable[[T], T]) -> T:
 6        T2 = TypeVar("T2")  # 這是不同的 TypeVar！
 7        ...
 8
 9    # 正確：直接使用類別的 T
10    def transform(self, func: Callable[[T], T]) -> T:
11        return func(self.value)

3. 誤用 covariant/contravariant

1T_co = TypeVar("T_co", covariant=True)
2
3class MutableBox(Generic[T_co]):  # 錯誤！
4    def __init__(self, value: T_co) -> None:
5        self._value = value
6
7    def set(self, value: T_co) -> None:  # 協變型別不能用在參數位置
8        self._value = value

小結

概念	用途
`bound`	限制 TypeVar 必須是某型別的子型別
`covariant`	只讀容器，子型別可替代父型別
`contravariant`	只寫容器，父型別可替代子型別
`Generic[T]`	建立泛型類別
`Protocol`	結構化子型別，不需繼承

思考題

為什麼 list 是不變的而不是協變的？
什麼情況下應該用 Protocol 而不是 ABC？
如何為一個既可讀又可寫的容器設計型別安全的介面？

下一章：3.5.2 異常設計架構

案例：插件架構設計

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

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何用 Protocol 和註冊機制實現可擴展的插件系統。

先備知識

問題背景

現有設計

hook_validator.py 的驗證邏輯直接寫在類別中：

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    def validate_hook(self, hook_path: str) -> ValidationResult:
 5        """驗證單個 Hook 檔案"""
 6        # ... 讀取檔案 ...
 7
 8        # 執行各項檢查 - 硬編碼的驗證規則
 9        issues = []
10        issues.extend(self.check_naming_convention(hook_path))
11        issues.extend(self.check_lib_imports(content, hook_path))
12        issues.extend(self.check_output_format(content))
13        issues.extend(self.check_test_exists(hook_path))
14
15        return ValidationResult(hook_path=str(hook_path), issues=issues)
16
17    def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
18        """檢查命名規範"""
19        # ... 具體驗證邏輯 ...
20
21    def check_lib_imports(self, content: str, hook_path: Path) -> List[ValidationIssue]:
22        """檢查共用模組導入"""
23        # ... 具體驗證邏輯 ...
24
25    def check_output_format(self, content: str) -> List[ValidationIssue]:
26        """檢查輸出格式"""
27        # ... 具體驗證邏輯 ...
28
29    def check_test_exists(self, hook_path: Path) -> List[ValidationIssue]:
30        """檢查測試檔案是否存在"""
31        # ... 具體驗證邏輯 ...

這個設計的優點

所有邏輯集中管理，容易找到相關程式碼
沒有額外的抽象層，直接明瞭
對小型專案來說足夠使用

這個設計的限制

當需要擴展時：

第三方無法新增自己的檢查項：想加入「Docstring 檢查」必須修改 HookValidator
修改需要改動核心程式碼：每新增一個檢查都要改 validate_hook 方法
違反開放封閉原則：對擴展不開放，對修改不封閉

進階解決方案

設計目標

定義清晰的插件介面：用 Protocol 描述檢查項該有的行為
支援第三方擴展：外部套件可以新增檢查項
插件可以獨立測試：每個檢查項是獨立的單元
支援插件的啟用/停用：可以動態控制要執行哪些檢查

實作步驟

步驟 1：用 Protocol 定義插件介面

Protocol 讓我們定義「檢查項該有的行為」，而不強制繼承關係：

 1from dataclasses import dataclass, field
 2from pathlib import Path
 3from typing import Protocol, Optional, List, runtime_checkable
 4
 5@dataclass
 6class ValidationIssue:
 7    """Validation issue description"""
 8    level: str  # "error" | "warning" | "info"
 9    message: str
10    line: Optional[int] = None
11    suggestion: Optional[str] = None
12
13@dataclass
14class CheckContext:
15    """Context passed to each check"""
16    hook_path: Path
17    content: str
18    project_root: Path
19
20@runtime_checkable
21class ValidationCheck(Protocol):
22    """
23    Protocol for validation checks
24
25    Any class implementing this protocol can be used as a validation check.
26    No inheritance required - just implement the methods.
27    """
28
29    @property
30    def name(self) -> str:
31        """Check name for identification"""
32        ...
33
34    @property
35    def description(self) -> str:
36        """Human-readable description"""
37        ...
38
39    def check(self, context: CheckContext) -> List[ValidationIssue]:
40        """
41        Execute the validation check
42
43        Args:
44            context: Check context with file info
45
46        Returns:
47            List of validation issues found
48        """
49        ...

為什麼用 Protocol 而不是 ABC？

Protocol 是「鴨子型別」的靜態版本
不強制繼承，現有類別只要有對應方法就能用
@runtime_checkable 讓我們可以用 isinstance() 檢查

步驟 2：實作插件註冊機制

註冊機制提供兩種方式：裝飾器和明確註冊：

 1from typing import Type, Dict, Callable, TypeVar
 2
 3# Type variable for check classes
 4C = TypeVar("C", bound=ValidationCheck)
 5
 6class CheckRegistry:
 7    """
 8    Registry for validation checks
 9
10    Supports both decorator registration and explicit registration.
11    """
12
13    def __init__(self) -> None:
14        self._checks: Dict[str, ValidationCheck] = {}
15        self._disabled: set[str] = set()
16
17    def register(self, check: ValidationCheck) -> ValidationCheck:
18        """
19        Register a check instance
20
21        Args:
22            check: Check instance to register
23
24        Returns:
25            The same check instance (for chaining)
26
27        Example:
28            registry.register(NamingCheck())
29        """
30        if not isinstance(check, ValidationCheck):
31            raise TypeError(
32                f"Check must implement ValidationCheck protocol, "
33                f"got {type(check).__name__}"
34            )
35        self._checks[check.name] = check
36        return check
37
38    def check(self, name: Optional[str] = None) -> Callable[[Type[C]], Type[C]]:
39        """
40        Decorator for registering check classes
41
42        Args:
43            name: Optional custom name (default: class name)
44
45        Returns:
46            Class decorator
47
48        Example:
49            @registry.check()
50            class MyCheck:
51                ...
52        """
53        def decorator(cls: Type[C]) -> Type[C]:
54            instance = cls()
55            self._checks[name or instance.name] = instance
56            return cls
57        return decorator
58
59    def get_check(self, name: str) -> Optional[ValidationCheck]:
60        """Get a check by name"""
61        return self._checks.get(name)
62
63    def get_enabled_checks(self) -> List[ValidationCheck]:
64        """Get all enabled checks"""
65        return [
66            check for name, check in self._checks.items()
67            if name not in self._disabled
68        ]
69
70    def enable(self, name: str) -> None:
71        """Enable a check"""
72        self._disabled.discard(name)
73
74    def disable(self, name: str) -> None:
75        """Disable a check"""
76        self._disabled.add(name)
77
78    def list_checks(self) -> List[str]:
79        """List all registered check names"""
80        return list(self._checks.keys())
81
82# Global registry instance
83default_registry = CheckRegistry()

兩種註冊方式的比較：

方式	使用時機	優點	缺點
裝飾器 `@registry.check()`	類別定義時	簡潔、宣告式	模組載入時就註冊
明確註冊 `registry.register()`	執行時	更靈活、可延遲	較囉嗦

步驟 3：支援 entry_points 自動發現

entry_points 是 Python 打包系統的標準機制，讓外部套件可以註冊插件：

 1import sys
 2from importlib.metadata import entry_points
 3from typing import Iterator
 4
 5def discover_checks(
 6    group: str = "hook_validator.checks"
 7) -> Iterator[ValidationCheck]:
 8    """
 9    Discover checks from installed packages via entry_points
10
11    Args:
12        group: Entry point group name
13
14    Yields:
15        Discovered check instances
16
17    Example:
18        for check in discover_checks():
19            registry.register(check)
20    """
21    # Python 3.10+ API
22    if sys.version_info >= (3, 10):
23        eps = entry_points(group=group)
24    else:
25        # Python 3.9 compatibility
26        eps = entry_points().get(group, [])
27
28    for ep in eps:
29        try:
30            # Load the check class/factory
31            check_factory = ep.load()
32
33            # Create instance
34            if callable(check_factory):
35                check = check_factory()
36            else:
37                check = check_factory
38
39            # Validate it implements the protocol
40            if isinstance(check, ValidationCheck):
41                yield check
42            else:
43                import warnings
44                warnings.warn(
45                    f"Entry point {ep.name} does not implement "
46                    f"ValidationCheck protocol"
47                )
48
49        except Exception as e:
50            import warnings
51            warnings.warn(f"Failed to load check {ep.name}: {e}")
52
53def load_external_checks(registry: CheckRegistry) -> int:
54    """
55    Load all external checks into a registry
56
57    Args:
58        registry: Target registry
59
60    Returns:
61        Number of checks loaded
62    """
63    count = 0
64    for check in discover_checks():
65        registry.register(check)
66        count += 1
67    return count

步驟 4：實作插件載入與管理

插件管理器整合了註冊、發現和執行：

  1from dataclasses import dataclass, field
  2from pathlib import Path
  3from typing import Optional, List
  4
  5@dataclass
  6class ValidationResult:
  7    """Validation result for a single hook"""
  8    hook_path: str
  9    issues: List[ValidationIssue] = field(default_factory=list)
 10    is_compliant: bool = True
 11    checks_run: List[str] = field(default_factory=list)
 12
 13    def __post_init__(self) -> None:
 14        """Calculate compliance status"""
 15        self.is_compliant = not any(
 16            issue.level == "error" for issue in self.issues
 17        )
 18
 19class PluginValidator:
 20    """
 21    Plugin-based hook validator
 22
 23    Uses registered checks to validate hook files.
 24    """
 25
 26    def __init__(
 27        self,
 28        registry: Optional[CheckRegistry] = None,
 29        project_root: Optional[str] = None,
 30        auto_discover: bool = True
 31    ) -> None:
 32        """
 33        Initialize validator
 34
 35        Args:
 36            registry: Check registry (default: global registry)
 37            project_root: Project root directory
 38            auto_discover: Whether to auto-discover external checks
 39        """
 40        self.registry = registry or default_registry
 41        self.project_root = Path(
 42            project_root or os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 43        )
 44
 45        if auto_discover:
 46            load_external_checks(self.registry)
 47
 48    def validate_hook(self, hook_path: str) -> ValidationResult:
 49        """
 50        Validate a single hook file
 51
 52        Args:
 53            hook_path: Path to hook file
 54
 55        Returns:
 56            Validation result
 57        """
 58        path = self._resolve_path(hook_path)
 59
 60        # Check file exists
 61        if not path.exists():
 62            return ValidationResult(
 63                hook_path=str(path),
 64                issues=[
 65                    ValidationIssue(
 66                        level="error",
 67                        message=f"Hook file not found: {path}"
 68                    )
 69                ]
 70            )
 71
 72        # Read content
 73        try:
 74            content = path.read_text(encoding="utf-8")
 75        except Exception as e:
 76            return ValidationResult(
 77                hook_path=str(path),
 78                issues=[
 79                    ValidationIssue(
 80                        level="error",
 81                        message=f"Cannot read hook file: {e}"
 82                    )
 83                ]
 84            )
 85
 86        # Build context
 87        context = CheckContext(
 88            hook_path=path,
 89            content=content,
 90            project_root=self.project_root
 91        )
 92
 93        # Run all enabled checks
 94        all_issues: List[ValidationIssue] = []
 95        checks_run: List[str] = []
 96
 97        for check in self.registry.get_enabled_checks():
 98            try:
 99                issues = check.check(context)
100                all_issues.extend(issues)
101                checks_run.append(check.name)
102            except Exception as e:
103                all_issues.append(
104                    ValidationIssue(
105                        level="error",
106                        message=f"Check {check.name} failed: {e}"
107                    )
108                )
109
110        return ValidationResult(
111            hook_path=str(path),
112            issues=all_issues,
113            checks_run=checks_run
114        )
115
116    def _resolve_path(self, path: str) -> Path:
117        """Resolve path to absolute"""
118        p = Path(path)
119        if p.is_absolute():
120            return p
121        return self.project_root / p

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Plugin-based Hook Validator
  4
  5A validation system using Protocol and registry pattern,
  6allowing third-party extensions via entry_points.
  7"""
  8
  9from __future__ import annotations
 10
 11import os
 12import re
 13import sys
 14import warnings
 15from dataclasses import dataclass, field
 16from importlib.metadata import entry_points
 17from pathlib import Path
 18from typing import (
 19    Callable,
 20    Dict,
 21    Iterator,
 22    List,
 23    Optional,
 24    Protocol,
 25    Type,
 26    TypeVar,
 27    runtime_checkable,
 28)
 29
 30# ============================================================
 31# Data Classes
 32# ============================================================
 33
 34@dataclass
 35class ValidationIssue:
 36    """Validation issue description"""
 37    level: str  # "error" | "warning" | "info"
 38    message: str
 39    line: Optional[int] = None
 40    suggestion: Optional[str] = None
 41
 42@dataclass
 43class CheckContext:
 44    """Context passed to each check"""
 45    hook_path: Path
 46    content: str
 47    project_root: Path
 48
 49@dataclass
 50class ValidationResult:
 51    """Validation result for a single hook"""
 52    hook_path: str
 53    issues: List[ValidationIssue] = field(default_factory=list)
 54    is_compliant: bool = True
 55    checks_run: List[str] = field(default_factory=list)
 56
 57    def __post_init__(self) -> None:
 58        self.is_compliant = not any(
 59            issue.level == "error" for issue in self.issues
 60        )
 61
 62# ============================================================
 63# Protocol Definition
 64# ============================================================
 65
 66@runtime_checkable
 67class ValidationCheck(Protocol):
 68    """Protocol for validation checks"""
 69
 70    @property
 71    def name(self) -> str:
 72        """Check name for identification"""
 73        ...
 74
 75    @property
 76    def description(self) -> str:
 77        """Human-readable description"""
 78        ...
 79
 80    def check(self, context: CheckContext) -> List[ValidationIssue]:
 81        """Execute the validation check"""
 82        ...
 83
 84# ============================================================
 85# Registry
 86# ============================================================
 87
 88C = TypeVar("C", bound=ValidationCheck)
 89
 90class CheckRegistry:
 91    """Registry for validation checks"""
 92
 93    def __init__(self) -> None:
 94        self._checks: Dict[str, ValidationCheck] = {}
 95        self._disabled: set[str] = set()
 96
 97    def register(self, check: ValidationCheck) -> ValidationCheck:
 98        """Register a check instance"""
 99        if not isinstance(check, ValidationCheck):
100            raise TypeError(
101                f"Check must implement ValidationCheck protocol, "
102                f"got {type(check).__name__}"
103            )
104        self._checks[check.name] = check
105        return check
106
107    def check(self, name: Optional[str] = None) -> Callable[[Type[C]], Type[C]]:
108        """Decorator for registering check classes"""
109        def decorator(cls: Type[C]) -> Type[C]:
110            instance = cls()
111            self._checks[name or instance.name] = instance
112            return cls
113        return decorator
114
115    def get_check(self, name: str) -> Optional[ValidationCheck]:
116        """Get a check by name"""
117        return self._checks.get(name)
118
119    def get_enabled_checks(self) -> List[ValidationCheck]:
120        """Get all enabled checks"""
121        return [
122            check for name, check in self._checks.items()
123            if name not in self._disabled
124        ]
125
126    def enable(self, name: str) -> None:
127        """Enable a check"""
128        self._disabled.discard(name)
129
130    def disable(self, name: str) -> None:
131        """Disable a check"""
132        self._disabled.add(name)
133
134    def list_checks(self) -> List[str]:
135        """List all registered check names"""
136        return list(self._checks.keys())
137
138# Global registry
139default_registry = CheckRegistry()
140
141# ============================================================
142# Entry Points Discovery
143# ============================================================
144
145def discover_checks(
146    group: str = "hook_validator.checks"
147) -> Iterator[ValidationCheck]:
148    """Discover checks from installed packages via entry_points"""
149    if sys.version_info >= (3, 10):
150        eps = entry_points(group=group)
151    else:
152        eps = entry_points().get(group, [])
153
154    for ep in eps:
155        try:
156            check_factory = ep.load()
157            check = check_factory() if callable(check_factory) else check_factory
158
159            if isinstance(check, ValidationCheck):
160                yield check
161            else:
162                warnings.warn(
163                    f"Entry point {ep.name} does not implement "
164                    f"ValidationCheck protocol"
165                )
166        except Exception as e:
167            warnings.warn(f"Failed to load check {ep.name}: {e}")
168
169def load_external_checks(registry: CheckRegistry) -> int:
170    """Load all external checks into a registry"""
171    count = 0
172    for check in discover_checks():
173        registry.register(check)
174        count += 1
175    return count
176
177# ============================================================
178# Built-in Checks
179# ============================================================
180
181@default_registry.check()
182class NamingConventionCheck:
183    """Check hook file naming convention"""
184
185    VALID_PATTERNS = [
186        r"^[a-z0-9](/python-advanced/03-design-patterns/case-studies/plugin-architecture/[a-z0-9\-_]*[a-z0-9])?\.py$",
187    ]
188
189    @property
190    def name(self) -> str:
191        return "naming_convention"
192
193    @property
194    def description(self) -> str:
195        return "Check that hook files follow naming conventions"
196
197    def check(self, context: CheckContext) -> List[ValidationIssue]:
198        issues: List[ValidationIssue] = []
199        filename = context.hook_path.name
200
201        valid = any(
202            re.match(pattern, filename)
203            for pattern in self.VALID_PATTERNS
204        )
205
206        if not valid:
207            issues.append(
208                ValidationIssue(
209                    level="warning",
210                    message=f"Invalid file name: {filename}",
211                    suggestion="Use snake_case or kebab-case naming"
212                )
213            )
214
215        return issues
216
217@default_registry.check()
218class LibImportCheck:
219    """Check that hooks import required libraries"""
220
221    HOOK_IO_PATTERNS = [
222        r"from\s+hook_io\s+import",
223        r"from\s+lib\.hook_io\s+import",
224    ]
225
226    @property
227    def name(self) -> str:
228        return "lib_import"
229
230    @property
231    def description(self) -> str:
232        return "Check that hooks import hook_io module"
233
234    def check(self, context: CheckContext) -> List[ValidationIssue]:
235        issues: List[ValidationIssue] = []
236
237        has_import = any(
238            re.search(pattern, context.content)
239            for pattern in self.HOOK_IO_PATTERNS
240        )
241
242        if not has_import:
243            issues.append(
244                ValidationIssue(
245                    level="warning",
246                    message="Missing hook_io import",
247                    suggestion="Add: from hook_io import read_hook_input, write_hook_output"
248                )
249            )
250
251        return issues
252
253@default_registry.check()
254class OutputFormatCheck:
255    """Check hook output format"""
256
257    GOOD_PATTERNS = [
258        r"write_hook_output\s*\(",
259        r"create_pretooluse_output\s*\(",
260        r"create_posttooluse_output\s*\(",
261    ]
262
263    BAD_PATTERNS = [
264        r'print\s*\(\s*json\.dumps\s*\(',
265        r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\(',
266    ]
267
268    @property
269    def name(self) -> str:
270        return "output_format"
271
272    @property
273    def description(self) -> str:
274        return "Check that hooks use proper output functions"
275
276    def check(self, context: CheckContext) -> List[ValidationIssue]:
277        issues: List[ValidationIssue] = []
278
279        has_bad = any(
280            re.search(pattern, context.content)
281            for pattern in self.BAD_PATTERNS
282        )
283
284        if has_bad:
285            issues.append(
286                ValidationIssue(
287                    level="warning",
288                    message="Using print(json.dumps(...)) instead of write_hook_output()",
289                    suggestion="Use write_hook_output() for proper output formatting"
290                )
291            )
292
293        return issues
294
295@default_registry.check()
296class TestExistsCheck:
297    """Check that corresponding test file exists"""
298
299    @property
300    def name(self) -> str:
301        return "test_exists"
302
303    @property
304    def description(self) -> str:
305        return "Check that hook has a corresponding test file"
306
307    def check(self, context: CheckContext) -> List[ValidationIssue]:
308        issues: List[ValidationIssue] = []
309
310        hook_name = context.hook_path.stem
311        test_name = f"test_{hook_name.replace('-', '_')}.py"
312
313        possible_paths = [
314            context.project_root / ".claude" / "lib" / "tests" / test_name,
315            context.project_root / ".claude" / "hooks" / "tests" / test_name,
316        ]
317
318        if not any(p.exists() for p in possible_paths):
319            issues.append(
320                ValidationIssue(
321                    level="info",
322                    message=f"No test file found: {test_name}",
323                    suggestion=f"Create test at .claude/lib/tests/{test_name}"
324                )
325            )
326
327        return issues
328
329# ============================================================
330# Validator
331# ============================================================
332
333class PluginValidator:
334    """Plugin-based hook validator"""
335
336    def __init__(
337        self,
338        registry: Optional[CheckRegistry] = None,
339        project_root: Optional[str] = None,
340        auto_discover: bool = True
341    ) -> None:
342        self.registry = registry or default_registry
343        self.project_root = Path(
344            project_root or os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
345        )
346
347        if auto_discover:
348            load_external_checks(self.registry)
349
350    def validate_hook(self, hook_path: str) -> ValidationResult:
351        """Validate a single hook file"""
352        path = self._resolve_path(hook_path)
353
354        if not path.exists():
355            return ValidationResult(
356                hook_path=str(path),
357                issues=[
358                    ValidationIssue(
359                        level="error",
360                        message=f"Hook file not found: {path}"
361                    )
362                ]
363            )
364
365        try:
366            content = path.read_text(encoding="utf-8")
367        except Exception as e:
368            return ValidationResult(
369                hook_path=str(path),
370                issues=[
371                    ValidationIssue(
372                        level="error",
373                        message=f"Cannot read hook file: {e}"
374                    )
375                ]
376            )
377
378        context = CheckContext(
379            hook_path=path,
380            content=content,
381            project_root=self.project_root
382        )
383
384        all_issues: List[ValidationIssue] = []
385        checks_run: List[str] = []
386
387        for check in self.registry.get_enabled_checks():
388            try:
389                issues = check.check(context)
390                all_issues.extend(issues)
391                checks_run.append(check.name)
392            except Exception as e:
393                all_issues.append(
394                    ValidationIssue(
395                        level="error",
396                        message=f"Check {check.name} failed: {e}"
397                    )
398                )
399
400        return ValidationResult(
401            hook_path=str(path),
402            issues=all_issues,
403            checks_run=checks_run
404        )
405
406    def validate_all_hooks(self, hooks_dir: Optional[str] = None) -> List[ValidationResult]:
407        """Validate all hook files in a directory"""
408        if hooks_dir is None:
409            hooks_dir = str(self.project_root / ".claude" / "hooks")
410
411        hooks_path = self._resolve_path(hooks_dir)
412
413        if not hooks_path.is_dir():
414            return [
415                ValidationResult(
416                    hook_path=str(hooks_path),
417                    issues=[
418                        ValidationIssue(
419                            level="error",
420                            message=f"Hooks directory not found: {hooks_path}"
421                        )
422                    ]
423                )
424            ]
425
426        results = []
427        for hook_file in sorted(hooks_path.glob("*.py")):
428            if hook_file.name.startswith("_"):
429                continue
430            results.append(self.validate_hook(str(hook_file)))
431
432        return results
433
434    def _resolve_path(self, path: str) -> Path:
435        """Resolve path to absolute"""
436        p = Path(path)
437        return p if p.is_absolute() else self.project_root / p
438
439# ============================================================
440# Demo
441# ============================================================
442
443if __name__ == "__main__":
444    import tempfile
445
446    # Show registered checks
447    print("Registered checks:")
448    for name in default_registry.list_checks():
449        check = default_registry.get_check(name)
450        if check:
451            print(f"  - {name}: {check.description}")
452
453    # Create test hook
454    with tempfile.TemporaryDirectory() as tmpdir:
455        hooks_dir = Path(tmpdir) / ".claude" / "hooks"
456        hooks_dir.mkdir(parents=True)
457
458        # Create a hook file
459        hook_file = hooks_dir / "check-permissions.py"
460        hook_file.write_text("""
461#!/usr/bin/env python3
462from hook_io import read_hook_input, write_hook_output
463
464def main():
465    data = read_hook_input()
466    write_hook_output({"decision": "allow"})
467
468if __name__ == "__main__":
469    main()
470""")
471
472        # Validate
473        validator = PluginValidator(project_root=tmpdir, auto_discover=False)
474        result = validator.validate_hook(str(hook_file))
475
476        print(f"\nValidation result for {result.hook_path}:")
477        print(f"  Compliant: {result.is_compliant}")
478        print(f"  Checks run: {result.checks_run}")
479        for issue in result.issues:
480            print(f"  [{issue.level}] {issue.message}")

使用範例

建立插件

建立自訂檢查項只需要實作 Protocol 定義的介面：

 1from typing import List
 2import re
 3
 4class DocstringCheck:
 5    """
 6    Check that hooks have proper docstrings
 7
 8    A custom check that can be added to the validator.
 9    No inheritance required - just implement the protocol.
10    """
11
12    @property
13    def name(self) -> str:
14        return "docstring"
15
16    @property
17    def description(self) -> str:
18        return "Check that hook has a module docstring"
19
20    def check(self, context: CheckContext) -> List[ValidationIssue]:
21        issues: List[ValidationIssue] = []
22
23        # Check for module docstring
24        docstring_pattern = r'^(#!/.*\n)?[\s]*["\'\]{3}'
25
26        if not re.match(docstring_pattern, context.content):
27            issues.append(
28                ValidationIssue(
29                    level="info",
30                    message="Missing module docstring",
31                    suggestion='Add a docstring at the top: """Description of hook"""'
32                )
33            )
34
35        return issues
36
37class SecurityCheck:
38    """
39    Check for potential security issues
40
41    Looks for dangerous patterns like eval(), exec(), subprocess with shell=True
42    """
43
44    DANGEROUS_PATTERNS = [
45        (r'\beval\s*\(', "eval() is dangerous, consider alternatives"),
46        (r'\bexec\s*\(', "exec() is dangerous, consider alternatives"),
47        (r'subprocess.*shell\s*=\s*True', "shell=True is a security risk"),
48        (r'os\.system\s*\(', "os.system() is insecure, use subprocess instead"),
49    ]
50
51    @property
52    def name(self) -> str:
53        return "security"
54
55    @property
56    def description(self) -> str:
57        return "Check for potential security vulnerabilities"
58
59    def check(self, context: CheckContext) -> List[ValidationIssue]:
60        issues: List[ValidationIssue] = []
61
62        for pattern, message in self.DANGEROUS_PATTERNS:
63            if re.search(pattern, context.content):
64                issues.append(
65                    ValidationIssue(
66                        level="warning",
67                        message=message
68                    )
69                )
70
71        return issues

註冊插件

有三種方式可以註冊插件：

 1# Method 1: Using decorator (at class definition time)
 2@default_registry.check()
 3class MyCheck:
 4    @property
 5    def name(self) -> str:
 6        return "my_check"
 7    # ...
 8
 9# Method 2: Explicit registration (at runtime)
10docstring_check = DocstringCheck()
11security_check = SecurityCheck()
12
13default_registry.register(docstring_check)
14default_registry.register(security_check)
15
16# Method 3: Create custom registry
17custom_registry = CheckRegistry()
18custom_registry.register(DocstringCheck())
19custom_registry.register(SecurityCheck())
20
21validator = PluginValidator(registry=custom_registry, auto_discover=False)

使用 entry_points

對於要發布為獨立套件的插件，使用 pyproject.toml 設定 entry_points：

 1# pyproject.toml
 2[project]
 3name = "my-hook-checks"
 4version = "1.0.0"
 5description = "Custom hook validation checks"
 6
 7dependencies = [
 8    # hook-validator is the core package
 9]
10
11[project.entry-points."hook_validator.checks"]
12# Format: name = "module:factory_or_class"
13docstring = "my_hook_checks:DocstringCheck"
14security = "my_hook_checks.security:SecurityCheck"

插件模組結構：

 1# my_hook_checks/__init__.py
 2from .docstring import DocstringCheck
 3from .security import SecurityCheck
 4
 5__all__ = ["DocstringCheck", "SecurityCheck"]
 6
 7# my_hook_checks/docstring.py
 8class DocstringCheck:
 9    """Check for module docstrings"""
10
11    @property
12    def name(self) -> str:
13        return "docstring"
14
15    @property
16    def description(self) -> str:
17        return "Check that hook has a module docstring"
18
19    def check(self, context):
20        # ... implementation ...
21        return []

安裝後，PluginValidator 會自動發現並載入這些檢查項：

1# Automatic discovery from entry_points
2validator = PluginValidator(auto_discover=True)
3
4# Check what's loaded
5print(validator.registry.list_checks())
6# ['naming_convention', 'lib_import', 'output_format', 'test_exists',
7#  'docstring', 'security']  # <- external checks discovered!

設計權衡

面向	硬編碼方法	插件架構
擴展性	差：需修改核心程式碼	優秀：第三方可自由擴展
初始複雜度	低：直接寫邏輯	中：需要理解 Protocol 和註冊機制
維護成本	隨功能增加而上升	穩定：新增功能不改核心
第三方擴展	不支援	支援：透過 entry_points
測試難度	需要 mock 整個類別	容易：每個 check 獨立測試
執行時彈性	固定	高：可動態啟用/停用
除錯難度	簡單：程式碼集中	需要追蹤插件來源
效能開銷	無	輕微：註冊和迭代成本

什麼時候該用這個技術？

適合使用：

需要支援第三方擴展的工具（如 pytest、flake8、pre-commit）
功能模組化明確，各檢查項獨立
預期會頻繁新增功能
需要讓使用者自訂行為

不建議使用：

內部使用的小工具
功能很少變動
團隊對 Protocol 和 entry_points 不熟悉
效能關鍵的熱路徑

練習

基礎練習：實作格式檢查插件

實作一個 IndentationCheck，檢查 Python 檔案是否使用一致的縮排（空格 vs Tab）：

 1class IndentationCheck:
 2    """Check for consistent indentation"""
 3
 4    @property
 5    def name(self) -> str:
 6        return "indentation"
 7
 8    @property
 9    def description(self) -> str:
10        return "Check for consistent indentation style"
11
12    def check(self, context: CheckContext) -> List[ValidationIssue]:
13        issues: List[ValidationIssue] = []
14
15        # TODO: Implement
16        # 1. Check each line's leading whitespace
17        # 2. Detect if mixing tabs and spaces
18        # 3. Report as warning if inconsistent
19
20        return issues

提示：

使用 context.content.splitlines() 取得每一行
檢查每行開頭的空白字元 line[:len(line) - len(line.lstrip())]

進階練習：新增優先順序和相依性

擴展 ValidationCheck Protocol，支援：

優先順序：決定檢查項執行順序
相依性：某些檢查必須在其他檢查之後執行

 1@runtime_checkable
 2class ValidationCheck(Protocol):
 3    @property
 4    def name(self) -> str: ...
 5
 6    @property
 7    def description(self) -> str: ...
 8
 9    @property
10    def priority(self) -> int:
11        """Lower number = higher priority (default: 100)"""
12        return 100
13
14    @property
15    def depends_on(self) -> List[str]:
16        """Names of checks that must run before this one"""
17        return []
18
19    def check(self, context: CheckContext) -> List[ValidationIssue]: ...

然後修改 PluginValidator.validate_hook() 使用拓撲排序執行檢查。

挑戰題：實作插件的熱載入

實作「不重啟程式就能載入新插件」的功能：

 1class HotReloadableRegistry(CheckRegistry):
 2    """Registry that supports hot-reloading plugins"""
 3
 4    def watch_directory(self, path: str) -> None:
 5        """Watch a directory for new plugin files"""
 6        # TODO: Use watchdog or polling to detect new files
 7        pass
 8
 9    def reload_check(self, name: str) -> None:
10        """Reload a specific check"""
11        # TODO: Unload old module, load new version
12        pass

提示：

使用 importlib.reload() 重新載入模組
使用 watchdog 套件監控檔案變化
注意處理模組快取 sys.modules

延伸閱讀

上一章：快取生命週期管理 下一章：異常設計架構

3.5.2 異常設計架構

Tue, 20 Jan 2026 00:00:00 +0000

入門系列介紹了異常處理的基本策略。本章深入探討如何為大型專案設計異常架構，包括異常層級、異常鏈、以及 Python 3.11 引入的 ExceptionGroup。

先備知識

入門系列 5.1 異常處理策略

異常層級設計

為什麼需要層級設計？

當專案規模增長，你會需要：

區分錯誤來源：資料庫錯誤 vs 網路錯誤 vs 驗證錯誤
提供不同處理策略：有些錯誤可重試，有些需要通知用戶
方便呼叫者選擇處理粒度：捕獲所有錯誤 vs 只捕獲特定錯誤

模組級異常基類

 1# myapp/exceptions.py
 2
 3class AppError(Exception):
 4    """應用程式的基礎異常類別
 5
 6    所有自訂異常都應繼承此類別，讓呼叫者可以：
 7    - except AppError: 捕獲所有應用程式錯誤
 8    - except SpecificError: 只捕獲特定錯誤
 9    """
10
11    def __init__(self, message: str, code: str | None = None) -> None:
12        super().__init__(message)
13        self.message = message
14        self.code = code  # 可選的錯誤碼，方便 API 回應
15
16    def __str__(self) -> str:
17        if self.code:
18            return f"[{self.code}] {self.message}"
19        return self.message

細粒度異常分類

 1# 第一層：按錯誤類型分類
 2class ValidationError(AppError):
 3    """驗證相關錯誤"""
 4    pass
 5
 6class DataAccessError(AppError):
 7    """資料存取相關錯誤"""
 8    pass
 9
10class NetworkError(AppError):
11    """網路相關錯誤"""
12    pass
13
14class ConfigurationError(AppError):
15    """配置相關錯誤"""
16    pass
17
18# 第二層：更細的分類
19class FieldValidationError(ValidationError):
20    """欄位驗證錯誤"""
21
22    def __init__(self, field: str, message: str) -> None:
23        super().__init__(f"Field '{field}': {message}", code="VALIDATION_FIELD")
24        self.field = field
25
26class SchemaValidationError(ValidationError):
27    """資料結構驗證錯誤"""
28
29    def __init__(self, message: str, errors: list[str]) -> None:
30        super().__init__(message, code="VALIDATION_SCHEMA")
31        self.errors = errors
32
33class EntityNotFoundError(DataAccessError):
34    """實體不存在"""
35
36    def __init__(self, entity_type: str, entity_id: int | str) -> None:
37        super().__init__(
38            f"{entity_type} with id '{entity_id}' not found",
39            code="NOT_FOUND"
40        )
41        self.entity_type = entity_type
42        self.entity_id = entity_id
43
44class DuplicateEntityError(DataAccessError):
45    """實體已存在"""
46
47    def __init__(self, entity_type: str, field: str, value: str) -> None:
48        super().__init__(
49            f"{entity_type} with {field}='{value}' already exists",
50            code="DUPLICATE"
51        )

使用範例

 1from myapp.exceptions import (
 2    AppError,
 3    ValidationError,
 4    FieldValidationError,
 5    EntityNotFoundError
 6)
 7
 8def create_user(data: dict) -> User:
 9    # 驗證
10    if not data.get("email"):
11        raise FieldValidationError("email", "Email is required")
12
13    if not is_valid_email(data["email"]):
14        raise FieldValidationError("email", "Invalid email format")
15
16    # 檢查重複
17    if user_exists(data["email"]):
18        raise DuplicateEntityError("User", "email", data["email"])
19
20    return User(**data)
21
22# 呼叫者可以選擇處理粒度
23def handle_user_creation(data: dict) -> dict:
24    try:
25        user = create_user(data)
26        return {"status": "success", "user_id": user.id}
27
28    except FieldValidationError as e:
29        # 處理欄位驗證錯誤
30        return {"status": "error", "field": e.field, "message": e.message}
31
32    except ValidationError as e:
33        # 處理所有驗證錯誤
34        return {"status": "error", "message": str(e)}
35
36    except AppError as e:
37        # 處理所有應用程式錯誤
38        return {"status": "error", "code": e.code, "message": str(e)}

異常鏈的進階用法

`cause` vs `context`

Python 有兩種異常鏈機制：

 1# __cause__：明確指定的原因（使用 from）
 2try:
 3    result = int("not a number")
 4except ValueError as e:
 5    raise DataAccessError("Failed to parse ID") from e
 6    # e 會被設為 __cause__
 7
 8# __context__：隱式的上下文（在 except 中 raise）
 9try:
10    result = int("not a number")
11except ValueError:
12    raise DataAccessError("Failed to parse ID")
13    # 原始的 ValueError 會被設為 __context__

輸出差異：

 1# 使用 from（__cause__）
 2DataAccessError: Failed to parse ID
 3
 4The above exception was the direct cause of the following exception:
 5...
 6
 7# 不使用 from（__context__）
 8DataAccessError: Failed to parse ID
 9
10During handling of the above exception, another exception occurred:
11...

何時使用 from

 1# 情況 1：轉換異常型別
 2def load_user(user_id: int) -> User:
 3    try:
 4        data = database.query(f"SELECT * FROM users WHERE id = {user_id}")
 5        return User(**data)
 6    except DatabaseError as e:
 7        # 將底層資料庫錯誤轉換為應用層錯誤
 8        raise EntityNotFoundError("User", user_id) from e
 9
10# 情況 2：添加上下文資訊
11def process_config(path: str) -> dict:
12    try:
13        with open(path) as f:
14            return json.load(f)
15    except json.JSONDecodeError as e:
16        # 添加檔案路徑資訊
17        raise ConfigurationError(f"Invalid JSON in {path}") from e

suppress context

有時你想切斷異常鏈：

1def get_value(data: dict, key: str) -> str:
2    try:
3        return data[key]
4    except KeyError:
5        # 使用 from None 切斷異常鏈
6        raise ValueError(f"Required key '{key}' not found") from None

輸出：

1# 沒有 from None：會顯示原始 KeyError
2# 有 from None：只顯示 ValueError，不顯示 KeyError
3ValueError: Required key 'name' not found

使用時機：

原始異常不相關或會造成困惑
刻意隱藏實作細節
簡化錯誤訊息

ExceptionGroup（Python 3.11+）

問題情境

當需要同時處理多個異常時，傳統方式有限制：

 1# 傳統方式：只能記錄第一個錯誤，或全部收集後手動處理
 2errors = []
 3for task in tasks:
 4    try:
 5        task.run()
 6    except Exception as e:
 7        errors.append(e)
 8
 9if errors:
10    # 該拋出哪一個？或如何表示多個錯誤？
11    raise errors[0]  # 丟失其他錯誤

ExceptionGroup 解決方案

 1# Python 3.11+
 2def run_all_tasks(tasks: list[Task]) -> None:
 3    errors = []
 4    for task in tasks:
 5        try:
 6            task.run()
 7        except Exception as e:
 8            errors.append(e)
 9
10    if errors:
11        raise ExceptionGroup("Multiple tasks failed", errors)

except* 語法

1try:
2    run_all_tasks(tasks)
3except* ValueError as eg:
4    # eg 是包含所有 ValueError 的 ExceptionGroup
5    print(f"Value errors: {eg.exceptions}")
6except* TypeError as eg:
7    # eg 是包含所有 TypeError 的 ExceptionGroup
8    print(f"Type errors: {eg.exceptions}")

實際範例：並行任務處理

 1import asyncio
 2from typing import Callable, Any
 3
 4async def run_parallel(
 5    tasks: list[Callable[[], Any]]
 6) -> list[Any]:
 7    """並行執行多個任務，收集所有錯誤"""
 8
 9    async def run_task(task: Callable[[], Any]) -> Any:
10        return task()
11
12    # 使用 TaskGroup（Python 3.11+）
13    results = []
14    async with asyncio.TaskGroup() as tg:
15        futures = [tg.create_task(run_task(task)) for task in tasks]
16
17    # 如果有異常，TaskGroup 會拋出 ExceptionGroup
18    return [f.result() for f in futures]
19
20# 處理
21async def main():
22    tasks = [task1, task2, task3]
23
24    try:
25        results = await run_parallel(tasks)
26    except* ValueError as eg:
27        for e in eg.exceptions:
28            print(f"Validation failed: {e}")
29    except* ConnectionError as eg:
30        for e in eg.exceptions:
31            print(f"Connection failed: {e}")

巢狀 ExceptionGroup

 1# ExceptionGroup 可以巢狀
 2outer = ExceptionGroup("outer", [
 3    ValueError("value error"),
 4    ExceptionGroup("inner", [
 5        TypeError("type error 1"),
 6        TypeError("type error 2"),
 7    ])
 8])
 9
10# 使用 .subgroup() 過濾
11type_errors = outer.subgroup(lambda e: isinstance(e, TypeError))
12# 返回只包含 TypeError 的新 ExceptionGroup

異常 vs 返回值

何時使用異常

 1# 適合使用異常的情況：
 2
 3# 1. 無法繼續執行的錯誤
 4def connect_database(url: str) -> Connection:
 5    if not url:
 6        raise ConfigurationError("Database URL is required")
 7    # ...
 8
 9# 2. 呼叫者通常不處理的錯誤
10def validate_schema(data: dict) -> None:
11    errors = find_schema_errors(data)
12    if errors:
13        raise SchemaValidationError("Invalid data", errors)
14
15# 3. 深層呼叫需要跨多層傳遞錯誤
16def process_order(order_id: int) -> Order:
17    order = load_order(order_id)  # 可能 raise EntityNotFoundError
18    validate_order(order)          # 可能 raise ValidationError
19    return execute_order(order)    # 可能 raise PaymentError

何時使用 Result 模式

 1from dataclasses import dataclass
 2from typing import Generic, TypeVar
 3
 4T = TypeVar("T")
 5E = TypeVar("E")
 6
 7@dataclass
 8class Ok(Generic[T]):
 9    value: T
10
11@dataclass
12class Err(Generic[E]):
13    error: E
14
15Result = Ok[T] | Err[E]
16
17# 適合使用 Result 的情況：
18
19# 1. 錯誤是預期的、常見的
20def find_user(user_id: int) -> Result[User, str]:
21    user = db.get_user(user_id)
22    if user is None:
23        return Err(f"User {user_id} not found")
24    return Ok(user)
25
26# 2. 需要強制呼叫者處理錯誤
27def parse_config(text: str) -> Result[Config, list[str]]:
28    errors = []
29    # ... 解析邏輯
30    if errors:
31        return Err(errors)
32    return Ok(config)
33
34# 使用
35match parse_config(text):
36    case Ok(config):
37        use_config(config)
38    case Err(errors):
39        show_errors(errors)
40
41# 3. 效能敏感的熱點路徑
42# 異常有效能成本，頻繁拋出會影響效能

混合使用

 1class UserService:
 2    """服務層：使用異常表示錯誤"""
 3
 4    def create_user(self, data: dict) -> User:
 5        if not data.get("email"):
 6            raise FieldValidationError("email", "required")
 7        # ...
 8        return user
 9
10class UserAPI:
11    """API 層：將異常轉換為 Result"""
12
13    def __init__(self, service: UserService) -> None:
14        self.service = service
15
16    def create_user(self, data: dict) -> Result[dict, dict]:
17        try:
18            user = self.service.create_user(data)
19            return Ok({"id": user.id, "email": user.email})
20        except FieldValidationError as e:
21            return Err({"field": e.field, "message": e.message})
22        except AppError as e:
23            return Err({"code": e.code, "message": str(e)})

補充：contextlib.suppress

簡潔地忽略特定異常：

 1from contextlib import suppress
 2
 3# 傳統方式
 4try:
 5    os.remove(temp_file)
 6except FileNotFoundError:
 7    pass
 8
 9# 使用 suppress
10with suppress(FileNotFoundError):
11    os.remove(temp_file)
12
13# 可以同時忽略多種異常
14with suppress(FileNotFoundError, PermissionError):
15    os.remove(temp_file)

注意：只應該用於「真正可以安全忽略」的異常。

設計檢查表

設計異常架構時，考慮以下問題：

問題	建議
錯誤會被如何處理？	決定用異常還是返回值
需要區分多少種錯誤？	決定異常層級深度
呼叫者需要什麼資訊？	決定異常屬性
原始錯誤重要嗎？	決定是否使用 `from`
會有並行錯誤嗎？	考慮 ExceptionGroup

小結

概念	用途
異常層級	區分錯誤來源，提供不同處理粒度
`raise ... from e`	明確指定異常原因，保留追蹤資訊
`raise ... from None`	切斷異常鏈，隱藏實作細節
ExceptionGroup	同時處理多個異常
`except*`	按型別過濾 ExceptionGroup
Result 模式	強制錯誤處理，適合預期的錯誤

思考題

為什麼要使用異常層級而不是一個通用的 AppError？
from e 和 from None 分別在什麼情況下使用？
ExceptionGroup 解決了什麼問題？在什麼場景下最有用？

上一章：3.5.1 泛型進階 下一章：3.5.3 進階上下文管理

案例：同步/非同步橋接

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

本案例基於 .claude/lib 整體架構，展示如何用 run_in_executor 和 asyncio.run 在同步與非同步程式碼之間建立橋樑。

先備知識

問題背景

現有設計

.claude/lib 是一個同步設計的 Python 工具庫，包含多個模組：

 1# .claude/lib/__init__.py
 2"""
 3Claude Hooks 共用程式庫
 4
 5模組結構:
 6- git_utils: Git 操作工具（分支、worktree、專案根目錄）
 7- config_loader: 配置檔案載入
 8- hook_io: Hook 輸入輸出處理
 9- hook_validator: Hook 合規性驗證
10- markdown_link_checker: Markdown 連結檢查
11"""
12
13from .git_utils import (
14    run_git_command,
15    get_current_branch,
16    get_project_root,
17    get_worktree_list,
18)
19
20from .config_loader import (
21    load_config,
22    load_agents_config,
23)
24
25from .hook_io import (
26    read_hook_input,
27    write_hook_output,
28)

這些函式都是同步的：

 1# git_utils.py - 同步的 subprocess 呼叫
 2def run_git_command(
 3    args: list[str],
 4    cwd: Optional[str] = None,
 5    timeout: int = 10
 6) -> tuple[bool, str]:
 7    """Execute git command and return result"""
 8    result = subprocess.run(
 9        ["git"] + args,
10        cwd=cwd,
11        capture_output=True,
12        text=True,
13        timeout=timeout
14    )
15    if result.returncode == 0:
16        return True, result.stdout.strip()
17    return False, result.stderr.strip()
18
19# config_loader.py - 同步的檔案 I/O
20def load_config(config_name: str) -> dict:
21    """Load configuration file"""
22    config_dir = get_config_dir()
23    yaml_path = config_dir / f"{config_name}.yaml"
24
25    with open(yaml_path, "r", encoding="utf-8") as f:
26        return yaml.safe_load(f)
27
28# hook_validator.py - 同步的檔案驗證
29def validate_hook(hook_path: str) -> ValidationResult:
30    """Validate a single hook file"""
31    with open(hook_path, "r", encoding="utf-8") as f:
32        content = f.read()
33    # ... validation logic

這個設計的優點

簡單直覺：不需要了解 asyncio，任何 Python 開發者都能使用
向後相容：可以在任何 Python 環境中執行
測試容易：同步程式碼的測試更直觀
依賴少：不需要額外的非同步依賴庫

這個設計的限制

在非同步環境（如 FastAPI、aiohttp）中使用時：

問題 1：阻塞事件迴圈

 1from fastapi import FastAPI
 2from lib.git_utils import get_current_branch, get_worktree_list
 3
 4app = FastAPI()
 5
 6@app.get("/git/status")
 7async def get_git_status():
 8    # BAD: These synchronous calls block the event loop!
 9    branch = get_current_branch()      # Blocks ~50ms
10    worktrees = get_worktree_list()    # Blocks ~50ms
11
12    # During these 100ms, NO other requests can be processed!
13    return {"branch": branch, "worktrees": worktrees}

問題 2：無法並行執行

 1def validate_all_hooks(hooks_dir: str) -> list[ValidationResult]:
 2    """Validate all hooks - sequential execution"""
 3    results = []
 4    for hook_file in Path(hooks_dir).glob("*.py"):
 5        # Each validation runs one after another
 6        result = validate_hook(str(hook_file))  # ~10ms each
 7        results.append(result)
 8    return results
 9
10# 10 hooks = 100ms total
11# With parallelization, could be ~10ms!

問題 3：無法有效利用等待時間

 1def check_project_health() -> dict:
 2    """Check multiple aspects of project health"""
 3    # All I/O operations execute sequentially
 4    git_status = run_git_command(["status", "-s"])      # Wait...
 5    config = load_config("agents")                       # Wait...
 6    links = check_markdown_links("docs/README.md")       # Wait...
 7
 8    # Total time = sum of all operations
 9    return {
10        "git": git_status,
11        "config": config,
12        "links": links
13    }

進階解決方案

設計目標

在非同步程式碼中安全地呼叫同步函式（不阻塞事件迴圈）
在同步程式碼中使用非同步函式（保持向後相容）
避免巢狀事件迴圈問題
保持原有 API 不變

實作步驟

步驟 1：run_in_executor - 同步到非同步

run_in_executor 將同步函式放到執行緒池中執行，讓事件迴圈可以繼續處理其他任務。

 1import asyncio
 2from concurrent.futures import ThreadPoolExecutor
 3from typing import TypeVar, Callable, Any
 4
 5T = TypeVar('T')
 6
 7# Create a shared thread pool for I/O operations
 8_io_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="async_io")
 9
10async def run_sync_in_executor(
11    func: Callable[..., T],
12    *args: Any,
13    **kwargs: Any
14) -> T:
15    """
16    Run a synchronous function in a thread pool executor.
17
18    This prevents blocking the event loop when calling
19    synchronous I/O operations from async code.
20
21    Args:
22        func: The synchronous function to execute
23        *args: Positional arguments for the function
24        **kwargs: Keyword arguments for the function
25
26    Returns:
27        The result of the function call
28
29    Example:
30        # Instead of blocking:
31        result = sync_function(arg1, arg2)
32
33        # Use executor:
34        result = await run_sync_in_executor(sync_function, arg1, arg2)
35    """
36    loop = asyncio.get_running_loop()
37
38    # functools.partial handles kwargs
39    if kwargs:
40        import functools
41        func = functools.partial(func, **kwargs)
42
43    return await loop.run_in_executor(_io_executor, func, *args)

使用範例：包裝現有同步函式

 1from lib.git_utils import get_current_branch, get_worktree_list, run_git_command
 2from lib.config_loader import load_config
 3from lib.hook_validator import validate_hook
 4
 5# Async wrappers for existing sync functions
 6async def async_get_current_branch() -> Optional[str]:
 7    """Async wrapper for get_current_branch"""
 8    return await run_sync_in_executor(get_current_branch)
 9
10async def async_get_worktree_list() -> list[dict]:
11    """Async wrapper for get_worktree_list"""
12    return await run_sync_in_executor(get_worktree_list)
13
14async def async_load_config(config_name: str) -> dict:
15    """Async wrapper for load_config"""
16    return await run_sync_in_executor(load_config, config_name)
17
18async def async_validate_hook(hook_path: str) -> ValidationResult:
19    """Async wrapper for validate_hook"""
20    return await run_sync_in_executor(validate_hook, hook_path)

步驟 2：asyncio.run - 非同步到同步

當你有非同步程式碼，但需要從同步環境呼叫時，使用 asyncio.run。

 1import asyncio
 2from typing import TypeVar, Coroutine
 3
 4T = TypeVar('T')
 5
 6def run_async(coro: Coroutine[Any, Any, T]) -> T:
 7    """
 8    Run an async function from synchronous code.
 9
10    Creates a new event loop if none exists.
11    Safe to call from synchronous entry points.
12
13    Args:
14        coro: The coroutine to execute
15
16    Returns:
17        The result of the coroutine
18
19    Example:
20        # From a synchronous script:
21        result = run_async(async_function(arg1, arg2))
22
23    Warning:
24        Cannot be called when an event loop is already running!
25        Use nest_asyncio or redesign your code structure.
26    """
27    return asyncio.run(coro)
28
29# Synchronous API that uses async implementation internally
30def get_all_worktree_branches() -> dict[str, str]:
31    """
32    Get branches for all worktrees.
33
34    Uses async implementation internally for parallelization,
35    but provides a synchronous API for compatibility.
36    """
37    async def _async_impl():
38        worktrees = await async_get_worktree_list()
39        tasks = []
40        for wt in worktrees:
41            path = wt["path"]
42            tasks.append(_get_branch_for_path(path))
43        results = await asyncio.gather(*tasks)
44        return dict(zip([wt["path"] for wt in worktrees], results))
45
46    return run_async(_async_impl())
47
48async def _get_branch_for_path(path: str) -> str:
49    """Get current branch for a specific path"""
50    success, output = await run_sync_in_executor(
51        run_git_command,
52        ["branch", "--show-current"],
53        cwd=path
54    )
55    return output if success else "unknown"

步驟 3：處理已存在的事件迴圈

當你在已有事件迴圈的環境中（如 Jupyter Notebook、某些 Web 框架），直接呼叫 asyncio.run 會失敗：

1# This will raise RuntimeError in Jupyter or when loop is running
2asyncio.run(some_coroutine())
3# RuntimeError: asyncio.run() cannot be called from a running event loop

解決方案 A：使用 nest_asyncio（快速修復）

 1# pip install nest-asyncio
 2import nest_asyncio
 3
 4def run_async_safe(coro: Coroutine[Any, Any, T]) -> T:
 5    """
 6    Run async code safely, even from a running event loop.
 7
 8    Uses nest_asyncio to allow nested event loops.
 9    This is a pragmatic solution for environments like Jupyter.
10
11    Note:
12        nest_asyncio patches the event loop globally.
13        Use with caution in production code.
14    """
15    try:
16        loop = asyncio.get_running_loop()
17    except RuntimeError:
18        # No running loop - safe to use asyncio.run
19        return asyncio.run(coro)
20
21    # Running loop exists - need to nest
22    nest_asyncio.apply()
23    return loop.run_until_complete(coro)

解決方案 B：偵測執行環境（推薦）

 1import asyncio
 2from typing import TypeVar, Coroutine, Any
 3
 4T = TypeVar('T')
 5
 6def is_event_loop_running() -> bool:
 7    """Check if there's a running event loop"""
 8    try:
 9        asyncio.get_running_loop()
10        return True
11    except RuntimeError:
12        return False
13
14def run_async_adaptive(coro: Coroutine[Any, Any, T]) -> T:
15    """
16    Run async code with automatic environment detection.
17
18    - If no event loop: uses asyncio.run()
19    - If loop running: uses run_in_executor to run in a new thread
20
21    This is safer than nest_asyncio for production use.
22    """
23    if is_event_loop_running():
24        # We're in an async context - run in a new thread
25        import concurrent.futures
26        with concurrent.futures.ThreadPoolExecutor() as executor:
27            future = executor.submit(asyncio.run, coro)
28            return future.result()
29    else:
30        # Safe to run directly
31        return asyncio.run(coro)

解決方案 C：提供雙重 API（最佳實踐）

 1class GitUtils:
 2    """
 3    Git utilities with both sync and async APIs.
 4
 5    Usage:
 6        # Synchronous (traditional)
 7        utils = GitUtils()
 8        branch = utils.get_current_branch()
 9
10        # Asynchronous
11        branch = await utils.async_get_current_branch()
12    """
13
14    def __init__(self, cwd: Optional[str] = None):
15        self.cwd = cwd
16
17    # ===== Synchronous API (original) =====
18
19    def get_current_branch(self) -> Optional[str]:
20        """Get current branch (sync)"""
21        success, output = run_git_command(
22            ["branch", "--show-current"],
23            cwd=self.cwd
24        )
25        return output if success else None
26
27    def get_worktree_list(self) -> list[dict]:
28        """Get worktree list (sync)"""
29        # ... original implementation
30        pass
31
32    # ===== Asynchronous API =====
33
34    async def async_get_current_branch(self) -> Optional[str]:
35        """Get current branch (async)"""
36        return await run_sync_in_executor(self.get_current_branch)
37
38    async def async_get_worktree_list(self) -> list[dict]:
39        """Get worktree list (async)"""
40        return await run_sync_in_executor(self.get_worktree_list)

步驟 4：建立統一的 API

整合以上模式，建立一個統一的適配器：

  1"""
  2Sync/Async Bridge Adapter
  3
  4Provides unified access to .claude/lib modules from both
  5synchronous and asynchronous contexts.
  6"""
  7
  8import asyncio
  9import functools
 10from concurrent.futures import ThreadPoolExecutor
 11from typing import TypeVar, Callable, Any, Optional, Coroutine
 12
 13T = TypeVar('T')
 14
 15# Shared executor for I/O operations
 16_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="lib_async")
 17
 18class AsyncAdapter:
 19    """
 20    Adapter for converting sync functions to async.
 21
 22    Provides both decorator and wrapper patterns for flexibility.
 23
 24    Example:
 25        adapter = AsyncAdapter()
 26
 27        # As decorator
 28        @adapter.make_async
 29        def sync_function(x):
 30            return x * 2
 31
 32        result = await sync_function(5)
 33
 34        # As wrapper
 35        result = await adapter.run(other_sync_function, arg1, arg2)
 36    """
 37
 38    def __init__(self, executor: Optional[ThreadPoolExecutor] = None):
 39        self.executor = executor or _executor
 40
 41    async def run(
 42        self,
 43        func: Callable[..., T],
 44        *args: Any,
 45        **kwargs: Any
 46    ) -> T:
 47        """Run a sync function asynchronously"""
 48        loop = asyncio.get_running_loop()
 49
 50        if kwargs:
 51            func = functools.partial(func, **kwargs)
 52
 53        return await loop.run_in_executor(self.executor, func, *args)
 54
 55    def make_async(self, func: Callable[..., T]) -> Callable[..., Coroutine[Any, Any, T]]:
 56        """
 57        Decorator to create async version of sync function.
 58
 59        Example:
 60            @adapter.make_async
 61            def slow_io_operation(path: str) -> str:
 62                with open(path) as f:
 63                    return f.read()
 64
 65            # Now can be awaited
 66            content = await slow_io_operation("file.txt")
 67        """
 68        @functools.wraps(func)
 69        async def wrapper(*args: Any, **kwargs: Any) -> T:
 70            return await self.run(func, *args, **kwargs)
 71        return wrapper
 72
 73class SyncAdapter:
 74    """
 75    Adapter for calling async functions from sync code.
 76
 77    Example:
 78        adapter = SyncAdapter()
 79
 80        # Run async function synchronously
 81        result = adapter.run(async_function(arg1, arg2))
 82    """
 83
 84    @staticmethod
 85    def run(coro: Coroutine[Any, Any, T]) -> T:
 86        """
 87        Run a coroutine from synchronous code.
 88
 89        Automatically handles the case when an event loop
 90        is already running.
 91        """
 92        try:
 93            asyncio.get_running_loop()
 94            # Loop is running - use thread
 95            import concurrent.futures
 96            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
 97                future = ex.submit(asyncio.run, coro)
 98                return future.result()
 99        except RuntimeError:
100            # No running loop - safe to use asyncio.run
101            return asyncio.run(coro)
102
103    @staticmethod
104    def make_sync(
105        async_func: Callable[..., Coroutine[Any, Any, T]]
106    ) -> Callable[..., T]:
107        """
108        Decorator to create sync version of async function.
109
110        Example:
111            @SyncAdapter.make_sync
112            async def async_fetch(url: str) -> str:
113                async with aiohttp.get(url) as resp:
114                    return await resp.text()
115
116            # Now can be called synchronously
117            content = async_fetch("https://example.com")
118        """
119        @functools.wraps(async_func)
120        def wrapper(*args: Any, **kwargs: Any) -> T:
121            coro = async_func(*args, **kwargs)
122            return SyncAdapter.run(coro)
123        return wrapper

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Sync/Async Bridge for .claude/lib
  4
  5This module provides async wrappers for the synchronous
  6.claude/lib modules, enabling their use in async contexts
  7like FastAPI without blocking the event loop.
  8
  9Usage:
 10    # In async code (FastAPI, aiohttp, etc.)
 11    from lib_async import (
 12        async_get_current_branch,
 13        async_load_config,
 14        async_validate_hooks,
 15    )
 16
 17    branch = await async_get_current_branch()
 18
 19    # In sync code that needs parallelization
 20    from lib_async import parallel_validate_hooks
 21
 22    results = parallel_validate_hooks(hooks_dir)
 23"""
 24
 25import asyncio
 26import functools
 27from concurrent.futures import ThreadPoolExecutor
 28from pathlib import Path
 29from typing import TypeVar, Callable, Any, Optional, Coroutine
 30
 31# Import original sync modules
 32from lib.git_utils import (
 33    run_git_command,
 34    get_current_branch,
 35    get_project_root,
 36    get_worktree_list,
 37    is_protected_branch,
 38    is_allowed_branch,
 39)
 40from lib.config_loader import (
 41    load_config,
 42    load_agents_config,
 43    load_quality_rules,
 44)
 45from lib.hook_io import (
 46    read_hook_input,
 47    write_hook_output,
 48)
 49from lib.hook_validator import (
 50    validate_hook,
 51    validate_all_hooks,
 52    ValidationResult,
 53)
 54from lib.markdown_link_checker import (
 55    check_markdown_links,
 56    check_directory as check_markdown_directory,
 57    LinkCheckResult,
 58)
 59
 60T = TypeVar('T')
 61
 62# ===== Shared Resources =====
 63
 64# Thread pool for I/O-bound sync operations
 65_io_executor = ThreadPoolExecutor(
 66    max_workers=10,
 67    thread_name_prefix="lib_async_io"
 68)
 69
 70# ===== Core Utilities =====
 71
 72async def run_in_executor(
 73    func: Callable[..., T],
 74    *args: Any,
 75    **kwargs: Any
 76) -> T:
 77    """
 78    Run a synchronous function in the thread pool executor.
 79
 80    Args:
 81        func: Synchronous function to execute
 82        *args: Positional arguments
 83        **kwargs: Keyword arguments
 84
 85    Returns:
 86        Function result
 87    """
 88    loop = asyncio.get_running_loop()
 89
 90    if kwargs:
 91        func = functools.partial(func, **kwargs)
 92
 93    return await loop.run_in_executor(_io_executor, func, *args)
 94
 95def make_async(func: Callable[..., T]) -> Callable[..., Coroutine[Any, Any, T]]:
 96    """
 97    Decorator to create async version of a sync function.
 98
 99    Example:
100        @make_async
101        def slow_operation(x):
102            time.sleep(1)
103            return x * 2
104
105        result = await slow_operation(5)
106    """
107    @functools.wraps(func)
108    async def wrapper(*args: Any, **kwargs: Any) -> T:
109        return await run_in_executor(func, *args, **kwargs)
110    return wrapper
111
112# ===== Async Git Utils =====
113
114async def async_run_git_command(
115    args: list[str],
116    cwd: Optional[str] = None,
117    timeout: int = 10
118) -> tuple[bool, str]:
119    """Async version of run_git_command"""
120    return await run_in_executor(run_git_command, args, cwd=cwd, timeout=timeout)
121
122async def async_get_current_branch() -> Optional[str]:
123    """Async version of get_current_branch"""
124    return await run_in_executor(get_current_branch)
125
126async def async_get_project_root() -> str:
127    """Async version of get_project_root"""
128    return await run_in_executor(get_project_root)
129
130async def async_get_worktree_list() -> list[dict]:
131    """Async version of get_worktree_list"""
132    return await run_in_executor(get_worktree_list)
133
134# ===== Async Config Loader =====
135
136async def async_load_config(config_name: str) -> dict:
137    """Async version of load_config"""
138    return await run_in_executor(load_config, config_name)
139
140async def async_load_agents_config() -> dict:
141    """Async version of load_agents_config"""
142    return await run_in_executor(load_agents_config)
143
144async def async_load_quality_rules() -> dict:
145    """Async version of load_quality_rules"""
146    return await run_in_executor(load_quality_rules)
147
148# ===== Async Hook Validator =====
149
150async def async_validate_hook(hook_path: str) -> ValidationResult:
151    """Async version of validate_hook"""
152    return await run_in_executor(validate_hook, hook_path)
153
154async def async_validate_all_hooks(
155    hooks_dir: Optional[str] = None
156) -> list[ValidationResult]:
157    """
158    Validate all hooks in parallel.
159
160    Unlike the sync version that validates sequentially,
161    this version validates all hooks concurrently.
162    """
163    if hooks_dir is None:
164        hooks_dir = str(Path(await async_get_project_root()) / ".claude" / "hooks")
165
166    hooks_path = Path(hooks_dir)
167    if not hooks_path.is_dir():
168        return []
169
170    # Collect all hook files
171    hook_files = [
172        str(f) for f in sorted(hooks_path.glob("*.py"))
173        if not f.name.startswith("_")
174    ]
175
176    # Validate all in parallel
177    tasks = [async_validate_hook(hook) for hook in hook_files]
178    return await asyncio.gather(*tasks)
179
180# ===== Async Markdown Link Checker =====
181
182async def async_check_markdown_links(file_path: str) -> LinkCheckResult:
183    """Async version of check_markdown_links"""
184    return await run_in_executor(check_markdown_links, file_path)
185
186async def async_check_markdown_directory(
187    dir_path: str,
188    recursive: bool = True
189) -> list[LinkCheckResult]:
190    """
191    Check all markdown files in directory in parallel.
192    """
193    # Get file list synchronously (fast operation)
194    dir_path_obj = Path(dir_path)
195    if not dir_path_obj.is_dir():
196        return []
197
198    if recursive:
199        md_files = list(dir_path_obj.rglob("*.md"))
200    else:
201        md_files = list(dir_path_obj.glob("*.md"))
202
203    # Check all files in parallel
204    tasks = [async_check_markdown_links(str(f)) for f in md_files]
205    return await asyncio.gather(*tasks)
206
207# ===== Parallel Operations =====
208
209async def async_check_all_worktrees() -> dict[str, dict]:
210    """
211    Check status of all worktrees in parallel.
212
213    Returns:
214        dict: {path: {"branch": str, "status": str, "is_clean": bool}}
215    """
216    worktrees = await async_get_worktree_list()
217
218    async def check_one(wt: dict) -> tuple[str, dict]:
219        path = wt["path"]
220
221        # Run git status and branch in parallel for each worktree
222        status_task = async_run_git_command(["status", "-s"], cwd=path)
223        branch_task = async_run_git_command(["branch", "--show-current"], cwd=path)
224
225        (status_ok, status), (branch_ok, branch) = await asyncio.gather(
226            status_task, branch_task
227        )
228
229        return path, {
230            "branch": branch if branch_ok else wt.get("branch", "unknown"),
231            "status": status if status_ok else "error",
232            "is_clean": status_ok and not status,
233        }
234
235    tasks = [check_one(wt) for wt in worktrees]
236    results = await asyncio.gather(*tasks)
237
238    return dict(results)
239
240async def async_project_health_check() -> dict:
241    """
242    Comprehensive project health check with parallel execution.
243
244    Checks:
245    - Git status
246    - Configuration validity
247    - Hook compliance
248    - Documentation links
249
250    Returns:
251        dict: Health check results
252    """
253    # Run all checks in parallel
254    git_task = async_get_current_branch()
255    worktrees_task = async_check_all_worktrees()
256    config_task = async_load_agents_config()
257    hooks_task = async_validate_all_hooks()
258
259    branch, worktrees, config, hook_results = await asyncio.gather(
260        git_task, worktrees_task, config_task, hooks_task,
261        return_exceptions=True  # Don't fail if one check fails
262    )
263
264    return {
265        "git": {
266            "branch": branch if not isinstance(branch, Exception) else str(branch),
267            "worktrees": worktrees if not isinstance(worktrees, Exception) else {},
268        },
269        "config": {
270            "loaded": not isinstance(config, Exception),
271            "agents_count": len(config.get("known_agents", [])) if not isinstance(config, Exception) else 0,
272        },
273        "hooks": {
274            "total": len(hook_results) if not isinstance(hook_results, Exception) else 0,
275            "compliant": sum(1 for r in hook_results if r.is_compliant) if not isinstance(hook_results, Exception) else 0,
276        }
277    }
278
279# ===== Sync Wrappers for Async Functions =====
280
281def parallel_validate_hooks(hooks_dir: Optional[str] = None) -> list[ValidationResult]:
282    """
283    Synchronous API that uses async parallelization internally.
284
285    Use this when you want parallelization but are in sync context.
286    """
287    return asyncio.run(async_validate_all_hooks(hooks_dir))
288
289def parallel_check_worktrees() -> dict[str, dict]:
290    """
291    Synchronous API for parallel worktree checking.
292    """
293    return asyncio.run(async_check_all_worktrees())
294
295def project_health_check() -> dict:
296    """
297    Synchronous API for comprehensive health check.
298    """
299    return asyncio.run(async_project_health_check())
300
301# ===== Demo =====
302
303async def demo():
304    """Demonstrate the sync/async bridge capabilities"""
305    import time
306
307    print("=" * 60)
308    print("Sync/Async Bridge Demo")
309    print("=" * 60)
310
311    # 1. Basic async wrapper usage
312    print("\n1. Basic async wrapper:")
313    branch = await async_get_current_branch()
314    print(f"   Current branch: {branch}")
315
316    # 2. Parallel execution comparison
317    print("\n2. Parallel vs Sequential comparison:")
318
319    # Sequential (simulated)
320    start = time.perf_counter()
321    worktrees = await async_get_worktree_list()
322    seq_time = 0
323    for wt in worktrees:
324        _ = await async_run_git_command(["status", "-s"], cwd=wt["path"])
325        seq_time += time.perf_counter() - start
326        start = time.perf_counter()
327    print(f"   Sequential check: {seq_time:.3f}s")
328
329    # Parallel
330    start = time.perf_counter()
331    results = await async_check_all_worktrees()
332    par_time = time.perf_counter() - start
333    print(f"   Parallel check: {par_time:.3f}s")
334    print(f"   Speedup: {seq_time/par_time:.1f}x")
335
336    # 3. Project health check
337    print("\n3. Project health check (parallel):")
338    start = time.perf_counter()
339    health = await async_project_health_check()
340    elapsed = time.perf_counter() - start
341
342    print(f"   Branch: {health['git']['branch']}")
343    print(f"   Worktrees: {len(health['git']['worktrees'])}")
344    print(f"   Hooks compliant: {health['hooks']['compliant']}/{health['hooks']['total']}")
345    print(f"   Time: {elapsed:.3f}s")
346
347    print("\n" + "=" * 60)
348
349if __name__ == "__main__":
350    asyncio.run(demo())

使用範例

在 FastAPI 中使用同步函式

 1from fastapi import FastAPI, HTTPException
 2from lib_async import (
 3    async_get_current_branch,
 4    async_get_worktree_list,
 5    async_check_all_worktrees,
 6    async_validate_all_hooks,
 7    async_project_health_check,
 8)
 9
10app = FastAPI()
11
12@app.get("/git/branch")
13async def get_branch():
14    """
15    Get current git branch.
16
17    Uses async wrapper to prevent blocking the event loop.
18    """
19    branch = await async_get_current_branch()
20    if branch is None:
21        raise HTTPException(status_code=500, detail="Not a git repository")
22    return {"branch": branch}
23
24@app.get("/git/worktrees")
25async def get_worktrees():
26    """
27    Get all worktrees with their status.
28
29    Checks all worktrees in parallel for fast response.
30    """
31    worktrees = await async_check_all_worktrees()
32    return {"worktrees": worktrees}
33
34@app.get("/health")
35async def health_check():
36    """
37    Comprehensive project health check.
38
39    Runs multiple checks in parallel:
40    - Git status
41    - Configuration
42    - Hook compliance
43    """
44    health = await async_project_health_check()
45    return health
46
47@app.get("/hooks/validate")
48async def validate_hooks():
49    """
50    Validate all hooks in parallel.
51
52    Much faster than sequential validation for many hooks.
53    """
54    results = await async_validate_all_hooks()
55
56    return {
57        "total": len(results),
58        "compliant": sum(1 for r in results if r.is_compliant),
59        "issues": [
60            {
61                "hook": r.hook_path,
62                "issues": [
63                    {"level": i.level, "message": i.message}
64                    for i in r.issues
65                ]
66            }
67            for r in results
68            if not r.is_compliant
69        ]
70    }

在同步腳本中使用非同步函式

 1#!/usr/bin/env python3
 2"""
 3Synchronous script that leverages async parallelization internally.
 4"""
 5
 6from lib_async import (
 7    parallel_validate_hooks,
 8    parallel_check_worktrees,
 9    project_health_check,
10)
11
12def main():
13    print("Project Health Report")
14    print("=" * 50)
15
16    # These functions use asyncio internally for parallelization
17    # but provide a synchronous API
18
19    # 1. Check all worktrees in parallel
20    print("\n1. Worktree Status:")
21    worktrees = parallel_check_worktrees()
22    for path, info in worktrees.items():
23        status = "clean" if info["is_clean"] else "dirty"
24        print(f"   [{info['branch']}] {path}: {status}")
25
26    # 2. Validate all hooks in parallel
27    print("\n2. Hook Validation:")
28    results = parallel_validate_hooks()
29    compliant = sum(1 for r in results if r.is_compliant)
30    print(f"   Compliant: {compliant}/{len(results)}")
31
32    for result in results:
33        if not result.is_compliant:
34            print(f"   - {result.hook_path}:")
35            for issue in result.issues:
36                print(f"     [{issue.level}] {issue.message}")
37
38    # 3. Comprehensive health check
39    print("\n3. Overall Health:")
40    health = project_health_check()
41    print(f"   Git branch: {health['git']['branch']}")
42    print(f"   Config loaded: {health['config']['loaded']}")
43    print(f"   Hooks OK: {health['hooks']['compliant']}/{health['hooks']['total']}")
44
45if __name__ == "__main__":
46    main()

Python 3.9+ 使用 asyncio.to_thread

Python 3.9 引入了 asyncio.to_thread，提供更簡潔的語法：

 1import asyncio
 2from lib.git_utils import get_current_branch, run_git_command
 3from lib.config_loader import load_config
 4
 5# Python 3.9+ simplified syntax
 6async def async_get_current_branch_39() -> Optional[str]:
 7    """Using asyncio.to_thread (Python 3.9+)"""
 8    return await asyncio.to_thread(get_current_branch)
 9
10async def async_load_config_39(config_name: str) -> dict:
11    """Using asyncio.to_thread (Python 3.9+)"""
12    return await asyncio.to_thread(load_config, config_name)
13
14async def async_run_git_command_39(
15    args: list[str],
16    cwd: Optional[str] = None
17) -> tuple[bool, str]:
18    """Using asyncio.to_thread with keyword arguments"""
19    # to_thread supports kwargs directly in Python 3.9+
20    return await asyncio.to_thread(run_git_command, args, cwd)
21
22# Comparison: run_in_executor vs to_thread
23async def comparison_demo():
24    """
25    asyncio.to_thread vs run_in_executor
26
27    to_thread advantages:
28    - Simpler syntax
29    - Better default executor management
30    - Direct kwargs support
31
32    run_in_executor advantages:
33    - Works on Python 3.7+
34    - Can use custom executors
35    - More control over thread pool
36    """
37    # run_in_executor (Python 3.7+)
38    loop = asyncio.get_running_loop()
39    result1 = await loop.run_in_executor(None, get_current_branch)
40
41    # to_thread (Python 3.9+)
42    result2 = await asyncio.to_thread(get_current_branch)
43
44    assert result1 == result2

設計權衡

面向	run_in_executor	asyncio.run	asyncio.to_thread
方向	同步 -> 非同步	非同步 -> 同步	同步 -> 非同步
執行緒	使用執行緒池	建立新事件迴圈	使用預設執行緒池
適用場景	非同步環境呼叫同步 I/O	同步入口點執行非同步	非同步環境呼叫同步 I/O
限制	需要事件迴圈存在	不能巢狀呼叫	需要 Python 3.9+
效能	高（可重用執行緒）	中（建立新迴圈開銷）	高（優化的執行緒池）
複雜度	中	低	低

ThreadPoolExecutor vs ProcessPoolExecutor

面向	ThreadPoolExecutor	ProcessPoolExecutor
適用場景	I/O 密集操作	CPU 密集操作
記憶體	共享記憶體	獨立記憶體空間
GIL	受 GIL 限制	繞過 GIL
啟動成本	低	高（進程建立）
資料傳遞	直接傳遞	需要序列化

 1from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
 2
 3# I/O-bound: use ThreadPoolExecutor
 4io_executor = ThreadPoolExecutor(max_workers=10)
 5
 6# CPU-bound: use ProcessPoolExecutor
 7cpu_executor = ProcessPoolExecutor(max_workers=4)
 8
 9async def io_bound_task():
10    """File I/O, network calls, subprocess"""
11    loop = asyncio.get_running_loop()
12    return await loop.run_in_executor(io_executor, sync_io_function)
13
14async def cpu_bound_task():
15    """Heavy computation"""
16    loop = asyncio.get_running_loop()
17    return await loop.run_in_executor(cpu_executor, sync_cpu_function)

什麼時候該用這個技術？

適合使用

漸進式遷移到 asyncio：有大量同步程式碼，需要逐步遷移
在 FastAPI 中使用同步第三方庫：如 requests、boto3、資料庫驅動
提供同步/非同步雙 API：讓使用者選擇適合的模式
並行化現有同步操作：如批次檔案處理、多 API 呼叫
整合傳統程式碼：舊系統的同步函式需要在新非同步系統中使用

不建議使用

全新專案：直接用原生 asyncio 設計
CPU 密集操作：應用 multiprocessing 或 ProcessPoolExecutor
簡單的單一操作：不需要並行的情況
效能極度敏感：執行緒池有微小開銷
已有原生非同步替代方案：如用 aiohttp 替代 requests

練習

基礎練習

用 run_in_executor 包裝 requests.get

 1import requests
 2import asyncio
 3
 4# TODO: Implement this function
 5async def async_fetch(url: str) -> str:
 6    """
 7    Fetch URL content asynchronously using requests library.
 8
 9    Hint: Use run_in_executor to wrap requests.get
10    """
11    pass
12
13# Test your implementation
14async def test():
15    content = await async_fetch("https://httpbin.org/get")
16    print(content[:200])
17
18asyncio.run(test())

參考解答

案例：異常設計架構

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

本案例基於 .claude/lib/hook_io.py 的實際程式碼，展示如何設計清晰的異常階層，並用 ExceptionGroup 處理多重錯誤。

先備知識

入門系列 5.1 異常處理策略
3.5.2 異常設計架構

問題背景

現有設計

.claude/lib/hook_io.py 使用簡單的錯誤處理方式：

 1def read_hook_input() -> dict:
 2    """
 3    從 stdin 讀取 Hook 輸入
 4
 5    Returns:
 6        dict: 解析後的 JSON 資料，解析失敗時返回空字典
 7    """
 8    try:
 9        return json.load(sys.stdin)
10    except json.JSONDecodeError:
11        return {}
12    except Exception:
13        return {}

這個設計有以下特點：

捕獲所有異常：使用 except Exception 確保不會崩潰
靜默失敗：錯誤時返回空字典，不報告錯誤原因
無法區分錯誤類型：JSON 解析錯誤和其他錯誤用同樣方式處理

這個設計的優點

簡單可靠：Hook 不會因為輸入問題而崩潰
使用標準異常：不需要定義額外類別
API 簡潔：呼叫者不需要處理異常

這個設計的限制

當錯誤處理變複雜時，這個設計會遇到問題：

問題 1：無法區分不同來源的錯誤

1def process_hook():
2    input_data = read_hook_input()
3    if not input_data:
4        # 問題：不知道是 JSON 解析失敗還是 stdin 讀取失敗
5        # 無法給出有意義的錯誤訊息
6        return {"error": "unknown error"}

問題 2：多個錯誤只能報告第一個

1def validate_hook_config(config: dict) -> None:
2    """驗證 Hook 配置"""
3    if "tool_name" not in config:
4        raise ValueError("missing tool_name")  # 第一個錯誤後就停止
5    if "tool_input" not in config:
6        raise ValueError("missing tool_input")  # 永遠不會執行到

問題 3：錯誤恢復邏輯難以實作

1def handle_hook_error(error: Exception) -> dict:
2    """處理 Hook 錯誤"""
3    # 問題：只能用 isinstance 檢查，很難擴展
4    if isinstance(error, json.JSONDecodeError):
5        return {"error": "invalid json"}
6    elif isinstance(error, FileNotFoundError):
7        return {"error": "file not found"}
8    else:
9        return {"error": str(error)}

進階解決方案

設計目標

建立清晰的異常階層：不同錯誤類型有不同的異常類別
支援多重錯誤收集：使用 ExceptionGroup 收集多個驗證錯誤
提供豐富的錯誤資訊：異常攜帶足夠的上下文資訊
支援錯誤恢復策略：可以根據錯誤類型決定恢復方式

實作步驟

步驟 1：設計異常階層

設計異常階層時，要考慮錯誤的分類和繼承關係：

  1"""
  2Hook 異常階層設計
  3
  4Exception hierarchy:
  5    HookError (base)
  6    ├── HookConfigError (configuration issues)
  7    │   ├── ConfigNotFoundError
  8    │   ├── ConfigParseError
  9    │   └── ConfigValidationError
 10    ├── HookInputError (input processing)
 11    │   ├── InputReadError
 12    │   └── InputValidationError
 13    └── HookExecutionError (runtime issues)
 14        ├── ToolNotFoundError
 15        └── PermissionDeniedError
 16"""
 17
 18class HookError(Exception):
 19    """
 20    Hook 異常基礎類別
 21
 22    所有 Hook 相關的異常都繼承自這個類別，
 23    讓呼叫者可以用 `except HookError` 捕獲所有 Hook 錯誤。
 24    """
 25
 26    def __init__(self, message: str, *, context: dict | None = None):
 27        super().__init__(message)
 28        self.context = context or {}
 29
 30    def __str__(self) -> str:
 31        if self.context:
 32            ctx = ", ".join(f"{k}={v!r}" for k, v in self.context.items())
 33            return f"{self.args[0]} ({ctx})"
 34        return self.args[0]
 35
 36# === Configuration Errors ===
 37
 38class HookConfigError(HookError):
 39    """配置相關錯誤的基礎類別"""
 40    pass
 41
 42class ConfigNotFoundError(HookConfigError):
 43    """配置檔案不存在"""
 44
 45    def __init__(self, config_name: str, search_paths: list[str] | None = None):
 46        self.config_name = config_name
 47        self.search_paths = search_paths or []
 48        super().__init__(
 49            f"Config '{config_name}' not found",
 50            context={"config_name": config_name, "search_paths": self.search_paths}
 51        )
 52
 53class ConfigParseError(HookConfigError):
 54    """配置檔案解析失敗"""
 55
 56    def __init__(self, config_name: str, line: int | None = None, detail: str = ""):
 57        self.config_name = config_name
 58        self.line = line
 59        self.detail = detail
 60        msg = f"Failed to parse config '{config_name}'"
 61        if line:
 62            msg += f" at line {line}"
 63        if detail:
 64            msg += f": {detail}"
 65        super().__init__(msg, context={"config_name": config_name, "line": line})
 66
 67class ConfigValidationError(HookConfigError):
 68    """配置內容驗證失敗"""
 69
 70    def __init__(self, config_name: str, field: str, reason: str):
 71        self.config_name = config_name
 72        self.field = field
 73        self.reason = reason
 74        super().__init__(
 75            f"Invalid config '{config_name}': field '{field}' {reason}",
 76            context={"config_name": config_name, "field": field}
 77        )
 78
 79# === Input Errors ===
 80
 81class HookInputError(HookError):
 82    """輸入相關錯誤的基礎類別"""
 83    pass
 84
 85class InputReadError(HookInputError):
 86    """讀取輸入失敗"""
 87
 88    def __init__(self, source: str = "stdin", cause: Exception | None = None):
 89        self.source = source
 90        self.cause = cause
 91        super().__init__(
 92            f"Failed to read from {source}",
 93            context={"source": source}
 94        )
 95        if cause:
 96            self.__cause__ = cause
 97
 98class InputValidationError(HookInputError):
 99    """輸入驗證失敗"""
100
101    def __init__(self, field: str, expected: str, actual: str | None = None):
102        self.field = field
103        self.expected = expected
104        self.actual = actual
105        msg = f"Invalid input: field '{field}' {expected}"
106        if actual:
107            msg += f", got {actual!r}"
108        super().__init__(msg, context={"field": field, "expected": expected})
109
110# === Execution Errors ===
111
112class HookExecutionError(HookError):
113    """執行時錯誤的基礎類別"""
114    pass
115
116class ToolNotFoundError(HookExecutionError):
117    """工具不存在"""
118
119    def __init__(self, tool_name: str, available_tools: list[str] | None = None):
120        self.tool_name = tool_name
121        self.available_tools = available_tools or []
122        super().__init__(
123            f"Tool '{tool_name}' not found",
124            context={"tool_name": tool_name, "available": self.available_tools}
125        )
126
127class PermissionDeniedError(HookExecutionError):
128    """權限不足"""
129
130    def __init__(self, action: str, resource: str, reason: str = ""):
131        self.action = action
132        self.resource = resource
133        self.reason = reason
134        msg = f"Permission denied: cannot {action} '{resource}'"
135        if reason:
136            msg += f" ({reason})"
137        super().__init__(msg, context={"action": action, "resource": resource})

步驟 2：豐富的錯誤資訊

異常類別可以攜帶豐富的上下文資訊，幫助除錯和錯誤恢復：

  1from dataclasses import dataclass, field
  2from datetime import datetime
  3from typing import Any
  4
  5@dataclass
  6class ErrorContext:
  7    """
  8    錯誤上下文資訊
  9
 10    收集錯誤發生時的環境資訊，
 11    幫助除錯和錯誤報告。
 12    """
 13    timestamp: datetime = field(default_factory=datetime.now)
 14    hook_name: str = ""
 15    tool_name: str = ""
 16    tool_input: dict = field(default_factory=dict)
 17    environment: dict = field(default_factory=dict)
 18    stack_info: str = ""
 19
 20    def to_dict(self) -> dict[str, Any]:
 21        """轉換為字典，方便序列化"""
 22        return {
 23            "timestamp": self.timestamp.isoformat(),
 24            "hook_name": self.hook_name,
 25            "tool_name": self.tool_name,
 26            "tool_input": self.tool_input,
 27            "environment": self.environment,
 28        }
 29
 30class RichHookError(HookError):
 31    """
 32    帶有豐富上下文的 Hook 異常
 33
 34    提供詳細的錯誤資訊，包含：
 35    - 錯誤發生的時間
 36    - 相關的 Hook 和工具資訊
 37    - 環境變數
 38    - 建議的修復方式
 39    """
 40
 41    def __init__(
 42        self,
 43        message: str,
 44        *,
 45        error_code: str = "",
 46        error_context: ErrorContext | None = None,
 47        suggestions: list[str] | None = None,
 48        recoverable: bool = False,
 49    ):
 50        super().__init__(message)
 51        self.error_code = error_code
 52        self.error_context = error_context or ErrorContext()
 53        self.suggestions = suggestions or []
 54        self.recoverable = recoverable
 55
 56    def format_message(self) -> str:
 57        """格式化完整錯誤訊息"""
 58        lines = [f"[{self.error_code}] {self.args[0]}"]
 59
 60        if self.error_context.hook_name:
 61            lines.append(f"  Hook: {self.error_context.hook_name}")
 62        if self.error_context.tool_name:
 63            lines.append(f"  Tool: {self.error_context.tool_name}")
 64
 65        if self.suggestions:
 66            lines.append("\nSuggestions:")
 67            for i, suggestion in enumerate(self.suggestions, 1):
 68                lines.append(f"  {i}. {suggestion}")
 69
 70        return "\n".join(lines)
 71
 72    def to_response(self) -> dict[str, Any]:
 73        """轉換為 Hook 回應格式"""
 74        return {
 75            "error": True,
 76            "error_code": self.error_code,
 77            "message": str(self.args[0]),
 78            "context": self.error_context.to_dict(),
 79            "suggestions": self.suggestions,
 80            "recoverable": self.recoverable,
 81        }
 82
 83# Example: specific error with rich context
 84class HookValidationError(RichHookError):
 85    """
 86    Hook 驗證錯誤
 87
 88    當 Hook 輸入驗證失敗時拋出，
 89    提供詳細的錯誤資訊和修復建議。
 90    """
 91
 92    def __init__(
 93        self,
 94        field: str,
 95        reason: str,
 96        *,
 97        actual_value: Any = None,
 98        error_context: ErrorContext | None = None,
 99    ):
100        self.field = field
101        self.reason = reason
102        self.actual_value = actual_value
103
104        message = f"Validation failed for '{field}': {reason}"
105        suggestions = self._generate_suggestions(field, reason, actual_value)
106
107        super().__init__(
108            message,
109            error_code="HOOK_VALIDATION_ERROR",
110            error_context=error_context,
111            suggestions=suggestions,
112            recoverable=True,
113        )
114
115    def _generate_suggestions(
116        self,
117        field: str,
118        reason: str,
119        actual_value: Any
120    ) -> list[str]:
121        """根據錯誤類型生成修復建議"""
122        suggestions = []
123
124        if "required" in reason.lower():
125            suggestions.append(f"Add the required field '{field}' to your input")
126        if "type" in reason.lower():
127            suggestions.append(f"Check the type of '{field}' - expected type may differ")
128        if actual_value is not None:
129            suggestions.append(f"Current value: {actual_value!r}")
130
131        return suggestions

步驟 3：使用 ExceptionGroup（Python 3.11+）

Python 3.11 引入的 ExceptionGroup 可以同時報告多個錯誤：

  1from typing import Callable
  2
  3class ValidationCollector:
  4    """
  5    驗證錯誤收集器
  6
  7    收集多個驗證錯誤，最後用 ExceptionGroup 一次報告。
  8    這樣可以讓使用者一次看到所有錯誤，而不是修完一個才看到下一個。
  9    """
 10
 11    def __init__(self, context_name: str = "validation"):
 12        self.context_name = context_name
 13        self.errors: list[Exception] = []
 14
 15    def add_error(self, error: Exception) -> None:
 16        """新增一個錯誤"""
 17        self.errors.append(error)
 18
 19    def check(self, condition: bool, error: Exception) -> None:
 20        """
 21        檢查條件，失敗時收集錯誤
 22
 23        Args:
 24            condition: 要檢查的條件
 25            error: 條件為 False 時要收集的錯誤
 26        """
 27        if not condition:
 28            self.errors.append(error)
 29
 30    def has_errors(self) -> bool:
 31        """是否有錯誤"""
 32        return len(self.errors) > 0
 33
 34    def raise_if_errors(self) -> None:
 35        """
 36        如果有錯誤，拋出 ExceptionGroup
 37
 38        Raises:
 39            ExceptionGroup: 包含所有收集到的錯誤
 40        """
 41        if self.errors:
 42            raise ExceptionGroup(
 43                f"{self.context_name} failed with {len(self.errors)} error(s)",
 44                self.errors
 45            )
 46
 47def validate_hook_input(data: dict) -> dict:
 48    """
 49    驗證 Hook 輸入，收集所有錯誤
 50
 51    使用 ExceptionGroup 一次報告所有驗證錯誤，
 52    而不是只報告第一個錯誤。
 53
 54    Args:
 55        data: 待驗證的輸入資料
 56
 57    Returns:
 58        驗證後的資料
 59
 60    Raises:
 61        ExceptionGroup: 包含所有驗證錯誤
 62    """
 63    collector = ValidationCollector("Hook input validation")
 64
 65    # Check required fields
 66    collector.check(
 67        "tool_name" in data,
 68        InputValidationError("tool_name", "is required")
 69    )
 70    collector.check(
 71        "tool_input" in data,
 72        InputValidationError("tool_input", "is required")
 73    )
 74
 75    # Check types (only if fields exist)
 76    if "tool_name" in data:
 77        collector.check(
 78            isinstance(data["tool_name"], str),
 79            InputValidationError(
 80                "tool_name",
 81                "must be a string",
 82                actual=type(data["tool_name"]).__name__
 83            )
 84        )
 85
 86    if "tool_input" in data:
 87        collector.check(
 88            isinstance(data["tool_input"], dict),
 89            InputValidationError(
 90                "tool_input",
 91                "must be a dict",
 92                actual=type(data["tool_input"]).__name__
 93            )
 94        )
 95
 96    # Check tool-specific validation
 97    if data.get("tool_name") == "Write":
 98        collector.check(
 99            "file_path" in data.get("tool_input", {}),
100            InputValidationError("tool_input.file_path", "is required for Write tool")
101        )
102        collector.check(
103            "content" in data.get("tool_input", {}),
104            InputValidationError("tool_input.content", "is required for Write tool")
105        )
106
107    # Raise all errors at once
108    collector.raise_if_errors()
109
110    return data
111
112# Using except* to handle ExceptionGroup (Python 3.11+)
113def handle_validation_errors_demo():
114    """示範如何用 except* 處理 ExceptionGroup"""
115    try:
116        validate_hook_input({
117            "tool_name": 123,  # Wrong type
118            # Missing tool_input
119        })
120    except* InputValidationError as eg:
121        # Handle all InputValidationError instances
122        print(f"Found {len(eg.exceptions)} validation errors:")
123        for error in eg.exceptions:
124            print(f"  - {error.field}: {error.expected}")
125    except* HookError as eg:
126        # Handle other HookError instances
127        print(f"Found {len(eg.exceptions)} hook errors")

步驟 4：錯誤恢復策略

設計可以根據錯誤類型決定恢復方式的機制：

  1from abc import ABC, abstractmethod
  2from typing import TypeVar, Generic
  3
  4T = TypeVar("T")
  5
  6class RecoveryStrategy(ABC, Generic[T]):
  7    """
  8    錯誤恢復策略抽象基礎類別
  9
 10    定義錯誤恢復的介面，讓不同類型的錯誤
 11    可以有不同的恢復方式。
 12    """
 13
 14    @abstractmethod
 15    def can_recover(self, error: Exception) -> bool:
 16        """判斷是否可以恢復此錯誤"""
 17        pass
 18
 19    @abstractmethod
 20    def recover(self, error: Exception) -> T:
 21        """執行恢復邏輯，返回恢復後的結果"""
 22        pass
 23
 24class DefaultValueRecovery(RecoveryStrategy[dict]):
 25    """
 26    預設值恢復策略
 27
 28    當錯誤發生時，返回預設值。
 29    """
 30
 31    def __init__(self, default: dict):
 32        self.default = default
 33
 34    def can_recover(self, error: Exception) -> bool:
 35        return isinstance(error, (ConfigNotFoundError, InputReadError))
 36
 37    def recover(self, error: Exception) -> dict:
 38        return self.default.copy()
 39
 40class RetryRecovery(RecoveryStrategy[dict]):
 41    """
 42    重試恢復策略
 43
 44    當錯誤是暫時性的，嘗試重試。
 45    """
 46
 47    def __init__(
 48        self,
 49        operation: Callable[[], dict],
 50        max_retries: int = 3,
 51        recoverable_errors: tuple[type[Exception], ...] = (IOError,)
 52    ):
 53        self.operation = operation
 54        self.max_retries = max_retries
 55        self.recoverable_errors = recoverable_errors
 56
 57    def can_recover(self, error: Exception) -> bool:
 58        return isinstance(error, self.recoverable_errors)
 59
 60    def recover(self, error: Exception) -> dict:
 61        import time
 62
 63        last_error = error
 64        for attempt in range(self.max_retries):
 65            try:
 66                time.sleep(0.1 * (2 ** attempt))  # Exponential backoff
 67                return self.operation()
 68            except self.recoverable_errors as e:
 69                last_error = e
 70                continue
 71
 72        # All retries failed, re-raise the last error
 73        raise last_error
 74
 75class ErrorRecoveryChain:
 76    """
 77    錯誤恢復鏈
 78
 79    按順序嘗試多個恢復策略，
 80    直到找到可以處理的策略。
 81    """
 82
 83    def __init__(self):
 84        self.strategies: list[RecoveryStrategy] = []
 85
 86    def add_strategy(self, strategy: RecoveryStrategy) -> "ErrorRecoveryChain":
 87        """新增恢復策略"""
 88        self.strategies.append(strategy)
 89        return self
 90
 91    def try_recover(self, error: Exception) -> tuple[bool, Any]:
 92        """
 93        嘗試恢復錯誤
 94
 95        Args:
 96            error: 要恢復的錯誤
 97
 98        Returns:
 99            (是否成功恢復, 恢復結果或 None)
100        """
101        for strategy in self.strategies:
102            if strategy.can_recover(error):
103                try:
104                    result = strategy.recover(error)
105                    return (True, result)
106                except Exception:
107                    continue
108        return (False, None)
109
110def read_hook_input_with_recovery() -> dict:
111    """
112    讀取 Hook 輸入，帶有錯誤恢復機制
113
114    使用恢復鏈處理不同類型的錯誤。
115    """
116    import json
117    import sys
118
119    # Set up recovery chain
120    recovery = ErrorRecoveryChain()
121    recovery.add_strategy(DefaultValueRecovery({"tool_name": "", "tool_input": {}}))
122
123    try:
124        data = json.load(sys.stdin)
125        return validate_hook_input(data)
126
127    except json.JSONDecodeError as e:
128        # JSON parsing error - try to recover
129        error = InputReadError("stdin", cause=e)
130        recovered, result = recovery.try_recover(error)
131        if recovered:
132            return result
133        raise error from e
134
135    except ExceptionGroup as eg:
136        # Multiple validation errors
137        # Check if all errors are recoverable
138        all_recoverable = all(
139            isinstance(e, (InputValidationError,))
140            for e in eg.exceptions
141        )
142        if all_recoverable:
143            return {"tool_name": "", "tool_input": {}, "validation_errors": len(eg.exceptions)}
144        raise
145
146    except Exception as e:
147        # Unknown error
148        error = InputReadError("stdin", cause=e)
149        recovered, result = recovery.try_recover(error)
150        if recovered:
151            return result
152        raise error from e

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Hook Exception Hierarchy - Complete Example
  4
  5Demonstrates how to design a clear exception hierarchy
  6and use ExceptionGroup for multiple error handling.
  7"""
  8
  9from __future__ import annotations
 10
 11import json
 12import sys
 13from abc import ABC, abstractmethod
 14from dataclasses import dataclass, field
 15from datetime import datetime
 16from typing import Any, Callable, Generic, TypeVar
 17
 18T = TypeVar("T")
 19
 20# ===== Exception Hierarchy =====
 21
 22class HookError(Exception):
 23    """Base class for all Hook-related exceptions."""
 24
 25    def __init__(self, message: str, *, context: dict | None = None):
 26        super().__init__(message)
 27        self.context = context or {}
 28
 29    def __str__(self) -> str:
 30        if self.context:
 31            ctx = ", ".join(f"{k}={v!r}" for k, v in self.context.items())
 32            return f"{self.args[0]} ({ctx})"
 33        return self.args[0]
 34
 35class HookConfigError(HookError):
 36    """Configuration-related errors."""
 37    pass
 38
 39class ConfigNotFoundError(HookConfigError):
 40    """Config file not found."""
 41
 42    def __init__(self, config_name: str, search_paths: list[str] | None = None):
 43        self.config_name = config_name
 44        self.search_paths = search_paths or []
 45        super().__init__(
 46            f"Config '{config_name}' not found",
 47            context={"config_name": config_name, "search_paths": self.search_paths}
 48        )
 49
 50class ConfigParseError(HookConfigError):
 51    """Failed to parse config file."""
 52
 53    def __init__(self, config_name: str, line: int | None = None, detail: str = ""):
 54        self.config_name = config_name
 55        self.line = line
 56        self.detail = detail
 57        msg = f"Failed to parse config '{config_name}'"
 58        if line:
 59            msg += f" at line {line}"
 60        if detail:
 61            msg += f": {detail}"
 62        super().__init__(msg, context={"config_name": config_name, "line": line})
 63
 64class HookInputError(HookError):
 65    """Input-related errors."""
 66    pass
 67
 68class InputReadError(HookInputError):
 69    """Failed to read input."""
 70
 71    def __init__(self, source: str = "stdin", cause: Exception | None = None):
 72        self.source = source
 73        self.cause = cause
 74        super().__init__(f"Failed to read from {source}", context={"source": source})
 75        if cause:
 76            self.__cause__ = cause
 77
 78class InputValidationError(HookInputError):
 79    """Input validation failed."""
 80
 81    def __init__(self, field: str, expected: str, actual: str | None = None):
 82        self.field = field
 83        self.expected = expected
 84        self.actual = actual
 85        msg = f"Invalid input: field '{field}' {expected}"
 86        if actual:
 87            msg += f", got {actual!r}"
 88        super().__init__(msg, context={"field": field, "expected": expected})
 89
 90class HookExecutionError(HookError):
 91    """Execution-related errors."""
 92    pass
 93
 94class ToolNotFoundError(HookExecutionError):
 95    """Tool not found."""
 96
 97    def __init__(self, tool_name: str, available_tools: list[str] | None = None):
 98        self.tool_name = tool_name
 99        self.available_tools = available_tools or []
100        super().__init__(
101            f"Tool '{tool_name}' not found",
102            context={"tool_name": tool_name, "available": self.available_tools}
103        )
104
105class PermissionDeniedError(HookExecutionError):
106    """Permission denied."""
107
108    def __init__(self, action: str, resource: str, reason: str = ""):
109        self.action = action
110        self.resource = resource
111        self.reason = reason
112        msg = f"Permission denied: cannot {action} '{resource}'"
113        if reason:
114            msg += f" ({reason})"
115        super().__init__(msg, context={"action": action, "resource": resource})
116
117# ===== Error Context =====
118
119@dataclass
120class ErrorContext:
121    """Rich context information for errors."""
122
123    timestamp: datetime = field(default_factory=datetime.now)
124    hook_name: str = ""
125    tool_name: str = ""
126    tool_input: dict = field(default_factory=dict)
127    environment: dict = field(default_factory=dict)
128
129    def to_dict(self) -> dict[str, Any]:
130        return {
131            "timestamp": self.timestamp.isoformat(),
132            "hook_name": self.hook_name,
133            "tool_name": self.tool_name,
134            "tool_input": self.tool_input,
135            "environment": self.environment,
136        }
137
138# ===== Validation Collector =====
139
140class ValidationCollector:
141    """Collects validation errors and raises ExceptionGroup."""
142
143    def __init__(self, context_name: str = "validation"):
144        self.context_name = context_name
145        self.errors: list[Exception] = []
146
147    def add_error(self, error: Exception) -> None:
148        self.errors.append(error)
149
150    def check(self, condition: bool, error: Exception) -> None:
151        if not condition:
152            self.errors.append(error)
153
154    def has_errors(self) -> bool:
155        return len(self.errors) > 0
156
157    def raise_if_errors(self) -> None:
158        if self.errors:
159            raise ExceptionGroup(
160                f"{self.context_name} failed with {len(self.errors)} error(s)",
161                self.errors
162            )
163
164# ===== Recovery Strategies =====
165
166class RecoveryStrategy(ABC, Generic[T]):
167    """Abstract base class for error recovery strategies."""
168
169    @abstractmethod
170    def can_recover(self, error: Exception) -> bool:
171        pass
172
173    @abstractmethod
174    def recover(self, error: Exception) -> T:
175        pass
176
177class DefaultValueRecovery(RecoveryStrategy[dict]):
178    """Returns a default value when error occurs."""
179
180    def __init__(self, default: dict):
181        self.default = default
182
183    def can_recover(self, error: Exception) -> bool:
184        return isinstance(error, (ConfigNotFoundError, InputReadError))
185
186    def recover(self, error: Exception) -> dict:
187        return self.default.copy()
188
189class ErrorRecoveryChain:
190    """Chain of recovery strategies."""
191
192    def __init__(self):
193        self.strategies: list[RecoveryStrategy] = []
194
195    def add_strategy(self, strategy: RecoveryStrategy) -> "ErrorRecoveryChain":
196        self.strategies.append(strategy)
197        return self
198
199    def try_recover(self, error: Exception) -> tuple[bool, Any]:
200        for strategy in self.strategies:
201            if strategy.can_recover(error):
202                try:
203                    result = strategy.recover(error)
204                    return (True, result)
205                except Exception:
206                    continue
207        return (False, None)
208
209# ===== Main Functions =====
210
211def validate_hook_input(data: dict) -> dict:
212    """
213    Validate hook input, collecting all errors.
214
215    Uses ExceptionGroup to report all validation errors at once.
216    """
217    collector = ValidationCollector("Hook input validation")
218
219    # Required fields
220    collector.check(
221        "tool_name" in data,
222        InputValidationError("tool_name", "is required")
223    )
224    collector.check(
225        "tool_input" in data,
226        InputValidationError("tool_input", "is required")
227    )
228
229    # Type checks
230    if "tool_name" in data:
231        collector.check(
232            isinstance(data["tool_name"], str),
233            InputValidationError(
234                "tool_name",
235                "must be a string",
236                actual=type(data["tool_name"]).__name__
237            )
238        )
239
240    if "tool_input" in data:
241        collector.check(
242            isinstance(data["tool_input"], dict),
243            InputValidationError(
244                "tool_input",
245                "must be a dict",
246                actual=type(data["tool_input"]).__name__
247            )
248        )
249
250    collector.raise_if_errors()
251    return data
252
253def read_hook_input_safe() -> dict:
254    """
255    Read hook input with error recovery.
256
257    Enhanced version of the original read_hook_input()
258    with proper exception handling.
259    """
260    recovery = ErrorRecoveryChain()
261    recovery.add_strategy(DefaultValueRecovery({"tool_name": "", "tool_input": {}}))
262
263    try:
264        data = json.load(sys.stdin)
265        return validate_hook_input(data)
266
267    except json.JSONDecodeError as e:
268        error = InputReadError("stdin", cause=e)
269        recovered, result = recovery.try_recover(error)
270        if recovered:
271            return result
272        raise error from e
273
274    except ExceptionGroup:
275        # Re-raise validation errors as-is
276        raise
277
278    except Exception as e:
279        error = InputReadError("stdin", cause=e)
280        recovered, result = recovery.try_recover(error)
281        if recovered:
282            return result
283        raise error from e
284
285def create_error_response(error: HookError) -> dict:
286    """Create a standardized error response."""
287    return {
288        "decision": "deny",
289        "reason": str(error),
290        "error": {
291            "type": type(error).__name__,
292            "message": str(error.args[0]),
293            "context": error.context,
294        }
295    }
296
297# ===== Demo =====
298
299if __name__ == "__main__":
300    print("=== Exception Hierarchy Demo ===\n")
301
302    # Demo 1: Basic exception
303    print("1. Basic exception:")
304    try:
305        raise ConfigNotFoundError("agents", ["/path/1", "/path/2"])
306    except HookConfigError as e:
307        print(f"   Caught: {e}")
308        print(f"   Context: {e.context}")
309
310    # Demo 2: Exception chaining
311    print("\n2. Exception chaining:")
312    try:
313        try:
314            raise json.JSONDecodeError("Unexpected EOF", "", 0)
315        except json.JSONDecodeError as e:
316            raise InputReadError("stdin", cause=e) from e
317    except InputReadError as e:
318        print(f"   Caught: {e}")
319        print(f"   Caused by: {e.__cause__}")
320
321    # Demo 3: ExceptionGroup
322    print("\n3. ExceptionGroup (multiple errors):")
323    try:
324        validate_hook_input({"tool_name": 123})  # Wrong type, missing tool_input
325    except ExceptionGroup as eg:
326        print(f"   Caught ExceptionGroup: {eg}")
327        for i, err in enumerate(eg.exceptions, 1):
328            print(f"   Error {i}: {err}")
329
330    # Demo 4: except* syntax (Python 3.11+)
331    print("\n4. Using except* to handle specific error types:")
332    try:
333        validate_hook_input({})  # Missing both fields
334    except* InputValidationError as eg:
335        print(f"   Caught {len(eg.exceptions)} InputValidationError(s)")
336        for err in eg.exceptions:
337            print(f"   - {err.field}: {err.expected}")
338
339    # Demo 5: Error recovery
340    print("\n5. Error recovery:")
341    recovery = ErrorRecoveryChain()
342    recovery.add_strategy(DefaultValueRecovery({"default": True}))
343
344    error = ConfigNotFoundError("missing_config")
345    recovered, result = recovery.try_recover(error)
346    print(f"   Recovered: {recovered}, Result: {result}")
347
348    print("\n=== Demo Complete ===")

使用範例

基本使用

 1from hook_exceptions import (
 2    HookError,
 3    ConfigNotFoundError,
 4    InputValidationError,
 5    create_error_response,
 6)
 7
 8def process_hook():
 9    """處理 Hook 請求"""
10    try:
11        # Load configuration
12        config = load_config("agents")
13
14        # Validate input
15        data = validate_hook_input(read_input())
16
17        # Process...
18        return {"decision": "allow"}
19
20    except ConfigNotFoundError as e:
21        # Specific handling for missing config
22        print(f"Warning: {e}, using defaults")
23        return {"decision": "allow", "warning": str(e)}
24
25    except InputValidationError as e:
26        # Input validation error
27        return create_error_response(e)
28
29    except HookError as e:
30        # Catch-all for other hook errors
31        return create_error_response(e)

多重錯誤處理

 1def validate_batch_inputs(inputs: list[dict]) -> list[dict]:
 2    """
 3    驗證多個輸入，收集所有錯誤
 4
 5    即使某些輸入失敗，仍然處理其他輸入。
 6    """
 7    results = []
 8    all_errors = []
 9
10    for i, data in enumerate(inputs):
11        try:
12            validated = validate_hook_input(data)
13            results.append({"index": i, "data": validated, "valid": True})
14        except ExceptionGroup as eg:
15            # Collect errors from this input
16            all_errors.extend(eg.exceptions)
17            results.append({
18                "index": i,
19                "errors": [str(e) for e in eg.exceptions],
20                "valid": False
21            })
22        except HookError as e:
23            all_errors.append(e)
24            results.append({"index": i, "error": str(e), "valid": False})
25
26    # Report summary
27    if all_errors:
28        print(f"Validation completed with {len(all_errors)} total errors")
29
30    return results
31
32# Using except* to handle different error types differently
33def handle_mixed_errors():
34    """示範用 except* 分別處理不同類型的錯誤"""
35    try:
36        # This might raise ExceptionGroup with mixed errors
37        process_complex_operation()
38
39    except* InputValidationError as eg:
40        # Handle validation errors - maybe log and continue
41        for err in eg.exceptions:
42            log_validation_error(err)
43
44    except* PermissionDeniedError as eg:
45        # Handle permission errors - need to notify admin
46        for err in eg.exceptions:
47            notify_admin(err)
48
49    except* HookExecutionError as eg:
50        # Handle execution errors - maybe retry
51        for err in eg.exceptions:
52            schedule_retry(err)

異常鏈（Exception Chaining）

 1def load_config_with_chain(name: str) -> dict:
 2    """
 3    載入配置，保留原始錯誤資訊
 4
 5    使用 `raise ... from ...` 保留異常鏈，
 6    讓除錯時可以看到完整的錯誤來源。
 7    """
 8    import yaml
 9
10    config_path = f"/config/{name}.yaml"
11
12    try:
13        with open(config_path) as f:
14            return yaml.safe_load(f)
15
16    except FileNotFoundError as e:
17        # Wrap in domain-specific exception, preserve original
18        raise ConfigNotFoundError(name, [config_path]) from e
19
20    except yaml.YAMLError as e:
21        # Extract line number if available
22        line = getattr(e, "problem_mark", None)
23        line_num = line.line if line else None
24        raise ConfigParseError(name, line=line_num, detail=str(e)) from e
25
26    except PermissionError as e:
27        # Convert to domain exception
28        raise PermissionDeniedError("read", config_path, str(e)) from e
29
30# When catching, you can access the full chain
31def debug_config_error():
32    try:
33        config = load_config_with_chain("agents")
34    except HookConfigError as e:
35        print(f"Error: {e}")
36        print(f"Original cause: {e.__cause__}")
37
38        # Print full traceback including cause
39        import traceback
40        traceback.print_exception(type(e), e, e.__traceback__)

設計權衡

面向	標準異常	自定義階層	ExceptionGroup
學習成本	低	中	中高
錯誤辨識	困難	清晰	清晰
錯誤資訊	有限	豐富	豐富
多重錯誤	只報一個	只報一個	全部報告
恢復策略	難實作	易實作	可分類處理
Python 版本	所有版本	所有版本	3.11+
程式碼量	最少	中等	較多

何時使用哪種方案？

使用標準異常（如 `hook_io.py` 的做法）

簡單的腳本或工具
錯誤處理很簡單
不需要區分錯誤類型

使用自定義階層

函式庫或框架
需要區分不同錯誤類型
需要提供錯誤恢復建議

使用 ExceptionGroup

批次處理需要收集所有錯誤
驗證邏輯有多個檢查點
需要讓使用者一次看到所有問題

什麼時候該用這個技術？

適合使用：

需要區分不同錯誤類型的函式庫
批次處理需要收集所有錯誤
需要提供錯誤恢復建議
需要保留完整的錯誤來源（異常鏈）
Python 3.11+ 環境

不建議使用：

簡單的腳本
錯誤類型很少（< 3 種）
不需要精細的錯誤處理
需要支援舊版 Python（< 3.11）使用 ExceptionGroup

練習

基礎練習

設計異常階層：為一個配置載入模組設計異常階層，包含：
- 檔案不存在
- 格式錯誤
- 欄位缺失
- 型別錯誤

提示：先畫出階層圖，再實作類別。

進階練習

實作 ExceptionGroup 驗證器：寫一個表單驗證器，可以：
- 收集所有欄位的驗證錯誤
- 用 ExceptionGroup 一次報告
- 支援 except* 分類處理

 1# 目標 API
 2def validate_form(data: dict) -> dict:
 3    """驗證表單，收集所有錯誤"""
 4    collector = ValidationCollector("form")
 5
 6    collector.check(
 7        len(data.get("username", "")) >= 3,
 8        FieldError("username", "must be at least 3 characters")
 9    )
10    collector.check(
11        "@" in data.get("email", ""),
12        FieldError("email", "must contain @")
13    )
14
15    collector.raise_if_errors()
16    return data

挑戰題

實作帶有自動修復建議的異常：設計一個異常系統，可以：
- 根據錯誤類型自動生成修復建議
- 支援結構化的錯誤報告（JSON 格式）
- 提供「可能的修復」和「參考文件」連結

 1# 目標 API
 2try:
 3    validate_config(config)
 4except ConfigError as e:
 5    print(e.format_message())
 6    # Output:
 7    # [CONFIG_001] Invalid config 'agents.yaml'
 8    #   Field: known_agents
 9    #   Error: expected list, got string
10    #
11    # Suggestions:
12    #   1. Change 'known_agents: "basil"' to 'known_agents: ["basil"]'
13    #   2. See: https://docs.example.com/config#known_agents

延伸閱讀

上一章：插件架構設計 下一章：泛型驗證器

1.3 設計模式與最佳實踐

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹 asyncio 的常見設計模式，以及如何避免常見陷阱。

先備知識

1.2 協程與 Task 管理

本章目標

學完本章後，你將能夠：

使用異步上下文管理器管理資源
實作異步迭代器處理串流資料
使用 Semaphore 控制並發
避免阻塞事件迴圈的陷阱

【原理層】異步協議

異步上下文管理器

同步版本使用 __enter__ 和 __exit__，異步版本使用 __aenter__ 和 __aexit__：

 1class AsyncResource:
 2 async def __aenter__(self):
 3 print("獲取資源")
 4 await self.connect()
 5 return self
 6
 7 async def __aexit__(self, exc_type, exc_val, exc_tb):
 8 print("釋放資源")
 9 await self.disconnect()
10
11 async def connect(self):
12 await asyncio.sleep(0.1)
13
14 async def disconnect(self):
15 await asyncio.sleep(0.1)
16
17async def main():
18 async with AsyncResource() as resource:
19 print("使用資源")

異步迭代器

同步版本使用 __iter__ 和 __next__，異步版本使用 __aiter__ 和 __anext__：

 1class AsyncCounter:
 2 def __init__(self, stop):
 3 self.current = 0
 4 self.stop = stop
 5
 6 def __aiter__(self):
 7 return self
 8
 9 async def __anext__(self):
10 if self.current >= self.stop:
11 raise StopAsyncIteration
12 await asyncio.sleep(0.1) # 模擬異步操作
13 self.current += 1
14 return self.current
15
16async def main():
17 async for num in AsyncCounter(5):
18 print(num)

異步生成器

更簡潔的異步迭代器寫法：

1async def async_range(stop):
2 for i in range(stop):
3 await asyncio.sleep(0.1)
4 yield i
5
6async def main():
7 async for num in async_range(5):
8 print(num)

【設計層】常見模式

協程鏈（Chaining）

 1async def fetch(url):
 2 async with aiohttp.ClientSession() as session:
 3 async with session.get(url) as response:
 4 return await response.text()
 5
 6async def parse(html):
 7 # 假設這是 CPU 密集操作，應該放到執行緒池
 8 await asyncio.sleep(0) # 讓出控制權
 9 return html[:100]
10
11async def process(data):
12 await asyncio.sleep(0.1)
13 return f"處理完成：{data}"
14
15async def pipeline(url):
16 html = await fetch(url)
17 parsed = await parse(html)
18 result = await process(parsed)
19 return result

Semaphore 並發控制

限制同時執行的任務數量：

 1async def fetch_with_limit(sem, url):
 2 async with sem: # 獲取信號量
 3 return await fetch(url)
 4
 5async def main():
 6 sem = asyncio.Semaphore(10) # 最多 10 個並發
 7 urls = [f"https://example.com/{i}" for i in range(100)]
 8
 9 tasks = [fetch_with_limit(sem, url) for url in urls]
10 results = await asyncio.gather(*tasks)

生產者-消費者

 1async def producer(queue):
 2 for i in range(10):
 3 await asyncio.sleep(0.1)
 4 await queue.put(i)
 5 print(f"生產：{i}")
 6 await queue.put(None) # 結束信號
 7
 8async def consumer(queue):
 9 while True:
10 item = await queue.get()
11 if item is None:
12 break
13 await asyncio.sleep(0.2)
14 print(f"消費：{item}")
15
16async def main():
17 queue = asyncio.Queue(maxsize=5)
18 await asyncio.gather(
19 producer(queue),
20 consumer(queue)
21 )

【實作層】實用範例

異步 Rate Limiter

 1class RateLimiter:
 2 def __init__(self, rate, per):
 3 self.rate = rate
 4 self.per = per
 5 self.allowance = rate
 6 self.last_check = asyncio.get_event_loop().time()
 7
 8 async def acquire(self):
 9 current = asyncio.get_event_loop().time()
10 elapsed = current - self.last_check
11 self.last_check = current
12 self.allowance += elapsed * (self.rate / self.per)
13
14 if self.allowance > self.rate:
15 self.allowance = self.rate
16
17 if self.allowance < 1.0:
18 wait_time = (1.0 - self.allowance) * (self.per / self.rate)
19 await asyncio.sleep(wait_time)
20 self.allowance = 0
21 else:
22 self.allowance -= 1.0

重試模式

1async def retry(coro_func, max_retries=3, delay=1.0):
2 for attempt in range(max_retries):
3 try:
4 return await coro_func()
5 except Exception as e:
6 if attempt == max_retries - 1:
7 raise
8 print(f"重試 {attempt + 1}/{max_retries}")
9 await asyncio.sleep(delay * (attempt + 1))

【陷阱與避免】

阻塞事件迴圈

 1import time
 2
 3async def bad_example():
 4 time.sleep(1) # 阻塞！整個事件迴圈停止
 5
 6async def good_example():
 7 await asyncio.sleep(1) # 非阻塞
 8
 9# 如果必須執行同步阻塞函式
10async def run_blocking():
11 loop = asyncio.get_running_loop()
12 await loop.run_in_executor(None, time.sleep, 1)

資源洩漏

 1# 錯誤：沒有正確關閉
 2async def bad():
 3 session = aiohttp.ClientSession()
 4 response = await session.get("https://example.com")
 5 return await response.text()
 6
 7# 正確：使用 async with
 8async def good():
 9 async with aiohttp.ClientSession() as session:
10 async with session.get("https://example.com") as response:
11 return await response.text()

思考題

為什麼 Semaphore 在 asyncio 中不需要擔心執行緒安全？
異步生成器在什麼場景下比異步迭代器更適合？
如何檢測程式碼是否阻塞了事件迴圈？

實作練習

實作一個異步連線池
實作一個帶有指數退避的重試裝飾器
實作一個異步的 debounce 函式

延伸閱讀

上一章：協程與 Task 管理 下一章：實戰：與同步程式碼整合

3.5.3 進階上下文管理

Tue, 20 Jan 2026 00:00:00 +0000

入門系列介紹了 with 語句的基本使用。本章深入探討上下文管理器的實現原理與進階應用，包括 contextlib 工具、嵌套組合、以及非同步上下文管理。

先備知識

入門系列的 with 語句使用
基本的類別定義與魔術方法

上下文管理器協議

`enter` 與 `exit`

 1class ManagedResource:
 2    """展示上下文管理器協議"""
 3
 4    def __init__(self, name: str) -> None:
 5        self.name = name
 6        print(f"Creating {name}")
 7
 8    def __enter__(self) -> "ManagedResource":
 9        """進入 with 區塊時呼叫
10
11        Returns:
12            as 子句綁定的物件
13        """
14        print(f"Entering {self.name}")
15        return self  # 這會被 as 子句捕獲
16
17    def __exit__(
18        self,
19        exc_type: type[BaseException] | None,
20        exc_val: BaseException | None,
21        exc_tb: TracebackType | None
22    ) -> bool:
23        """離開 with 區塊時呼叫
24
25        Args:
26            exc_type: 異常類型（無異常時為 None）
27            exc_val: 異常實例（無異常時為 None）
28            exc_tb: 追蹤資訊（無異常時為 None）
29
30        Returns:
31            True 表示已處理異常，不再傳播
32            False 或 None 表示讓異常繼續傳播
33        """
34        print(f"Exiting {self.name}")
35        if exc_type is not None:
36            print(f"  Exception: {exc_type.__name__}: {exc_val}")
37        return False  # 讓異常繼續傳播
38
39# 使用
40with ManagedResource("test") as resource:
41    print(f"Using {resource.name}")
42    # raise ValueError("oops")  # 取消註解測試異常處理
43
44# 輸出：
45# Creating test
46# Entering test
47# Using test
48# Exiting test

`exit` 的異常處理

 1from types import TracebackType
 2
 3class SuppressErrors:
 4    """抑制特定異常的上下文管理器"""
 5
 6    def __init__(self, *exceptions: type[BaseException]) -> None:
 7        self.exceptions = exceptions
 8
 9    def __enter__(self) -> None:
10        pass
11
12    def __exit__(
13        self,
14        exc_type: type[BaseException] | None,
15        exc_val: BaseException | None,
16        exc_tb: TracebackType | None
17    ) -> bool:
18        # 如果是我們要抑制的異常類型，返回 True
19        if exc_type is not None and issubclass(exc_type, self.exceptions):
20            print(f"Suppressed: {exc_type.__name__}: {exc_val}")
21            return True  # 吞掉異常
22        return False
23
24# 使用
25with SuppressErrors(ValueError, KeyError):
26    raise ValueError("This will be suppressed")
27
28print("Continues normally")

返回值的重要性

 1class DatabaseConnection:
 2    """展示 __enter__ 返回值的用法"""
 3
 4    def __init__(self, url: str) -> None:
 5        self.url = url
 6        self._connection = None
 7
 8    def __enter__(self) -> "Cursor":
 9        self._connection = connect(self.url)
10        return self._connection.cursor()  # 返回 cursor，不是 self
11
12    def __exit__(self, *args) -> None:
13        if self._connection:
14            self._connection.close()
15
16# 使用
17with DatabaseConnection("postgres://...") as cursor:
18    cursor.execute("SELECT * FROM users")
19    # cursor 是 Cursor 物件，不是 DatabaseConnection

contextlib 工具

@contextmanager 裝飾器

用生成器函式建立上下文管理器，比定義類別更簡潔：

 1from contextlib import contextmanager
 2from typing import Iterator
 3
 4@contextmanager
 5def timer(name: str) -> Iterator[None]:
 6    """計時上下文管理器"""
 7    import time
 8    start = time.perf_counter()
 9    print(f"Starting {name}...")
10
11    try:
12        yield  # 這裡是 with 區塊執行的地方
13    finally:
14        elapsed = time.perf_counter() - start
15        print(f"{name} took {elapsed:.3f}s")
16
17# 使用
18with timer("data processing"):
19    process_large_dataset()
20
21# 如果需要返回值
22@contextmanager
23def temp_directory() -> Iterator[Path]:
24    """建立臨時目錄，結束後自動清理"""
25    import tempfile
26    import shutil
27    from pathlib import Path
28
29    path = Path(tempfile.mkdtemp())
30    try:
31        yield path  # path 會被 as 子句捕獲
32    finally:
33        shutil.rmtree(path)
34
35with temp_directory() as tmpdir:
36    (tmpdir / "test.txt").write_text("hello")

ExitStack

動態管理多個上下文管理器：

 1from contextlib import ExitStack
 2
 3def process_multiple_files(filenames: list[str]) -> list[str]:
 4    """處理多個檔案，確保全部關閉"""
 5    with ExitStack() as stack:
 6        files = [
 7            stack.enter_context(open(fn))
 8            for fn in filenames
 9        ]
10        return [f.read() for f in files]
11
12# 更複雜的例子：條件式資源
13def connect_services(config: dict) -> dict:
14    """根據配置連接多個服務"""
15    with ExitStack() as stack:
16        services = {}
17
18        if config.get("database"):
19            services["db"] = stack.enter_context(
20                DatabaseConnection(config["database"])
21            )
22
23        if config.get("cache"):
24            services["cache"] = stack.enter_context(
25                CacheConnection(config["cache"])
26            )
27
28        if config.get("queue"):
29            services["queue"] = stack.enter_context(
30                QueueConnection(config["queue"])
31            )
32
33        # 所有連接都會在離開時按相反順序關閉
34        return do_work(services)

ExitStack 的回調功能

 1from contextlib import ExitStack
 2
 3def complex_setup() -> None:
 4    with ExitStack() as stack:
 5        # 註冊清理回調
 6        stack.callback(print, "Cleanup 1")
 7        stack.callback(print, "Cleanup 2")
 8
 9        # 推遲上下文管理器
10        cm = some_context_manager()
11        stack.push(cm)  # 不立即進入，但會在結束時呼叫 __exit__
12
13        # 做一些工作...
14        pass
15
16    # 離開時會執行：
17    # 1. cm.__exit__()
18    # 2. print("Cleanup 2")
19    # 3. print("Cleanup 1")  # 注意順序是相反的

nullcontext

需要可選的上下文管理器時使用：

 1from contextlib import nullcontext
 2
 3def process_data(lock: Lock | None = None) -> None:
 4    """可選的鎖定"""
 5    with lock if lock else nullcontext():
 6        # 處理資料
 7        pass
 8
 9# 更清楚的寫法
10def process_data(lock: Lock | None = None) -> None:
11    cm = lock if lock else nullcontext()
12    with cm:
13        pass
14
15# 帶返回值的 nullcontext
16from contextlib import nullcontext
17
18def get_stream(filename: str | None) -> Iterator[TextIO]:
19    if filename:
20        return open(filename)
21    return nullcontext(sys.stdout)  # 返回 stdout
22
23with get_stream(None) as f:
24    f.write("Hello")  # 寫到 stdout

嵌套與組合上下文

資源的有序獲取與釋放

 1# 傳統嵌套
 2with open("input.txt") as infile:
 3    with open("output.txt", "w") as outfile:
 4        outfile.write(infile.read())
 5
 6# Python 3.9+ 可以用括號分組
 7with (
 8    open("input.txt") as infile,
 9    open("output.txt", "w") as outfile
10):
11    outfile.write(infile.read())
12
13# 多個資源：ExitStack 更靈活
14with ExitStack() as stack:
15    files = [stack.enter_context(open(f)) for f in filenames]

組合上下文管理器

 1from contextlib import contextmanager
 2from typing import Iterator
 3
 4@contextmanager
 5def database_transaction(db: Database) -> Iterator[Transaction]:
 6    """資料庫交易上下文"""
 7    tx = db.begin_transaction()
 8    try:
 9        yield tx
10        tx.commit()
11    except Exception:
12        tx.rollback()
13        raise
14
15@contextmanager
16def acquire_lock(lock: Lock, timeout: float = 30) -> Iterator[None]:
17    """帶超時的鎖定獲取"""
18    if not lock.acquire(timeout=timeout):
19        raise TimeoutError(f"Could not acquire lock within {timeout}s")
20    try:
21        yield
22    finally:
23        lock.release()
24
25# 組合使用
26@contextmanager
27def safe_update(db: Database, lock: Lock) -> Iterator[Transaction]:
28    """帶鎖定的安全更新"""
29    with acquire_lock(lock):
30        with database_transaction(db) as tx:
31            yield tx

async context manager

基本語法

 1class AsyncResource:
 2    """非同步上下文管理器"""
 3
 4    async def __aenter__(self) -> "AsyncResource":
 5        await self.connect()
 6        return self
 7
 8    async def __aexit__(
 9        self,
10        exc_type: type[BaseException] | None,
11        exc_val: BaseException | None,
12        exc_tb: TracebackType | None
13    ) -> bool:
14        await self.disconnect()
15        return False
16
17# 使用
18async def main():
19    async with AsyncResource() as resource:
20        await resource.do_something()

@asynccontextmanager

 1from contextlib import asynccontextmanager
 2from typing import AsyncIterator
 3
 4@asynccontextmanager
 5async def async_timer(name: str) -> AsyncIterator[None]:
 6    """非同步計時器"""
 7    import time
 8    start = time.perf_counter()
 9    print(f"Starting {name}...")
10
11    try:
12        yield
13    finally:
14        elapsed = time.perf_counter() - start
15        print(f"{name} took {elapsed:.3f}s")
16
17async def main():
18    async with async_timer("async task"):
19        await asyncio.sleep(1)

與 asyncio 模組的連結

 1import asyncio
 2from contextlib import asynccontextmanager
 3
 4@asynccontextmanager
 5async def managed_task(coro) -> AsyncIterator[asyncio.Task]:
 6    """管理 Task 生命週期"""
 7    task = asyncio.create_task(coro)
 8    try:
 9        yield task
10    finally:
11        if not task.done():
12            task.cancel()
13            try:
14                await task
15            except asyncio.CancelledError:
16                pass
17
18async def main():
19    async with managed_task(background_worker()) as task:
20        # 做一些工作
21        await asyncio.sleep(5)
22    # 離開時自動取消 task

實際範例：交易管理器

結合所有概念，建立一個完整的交易管理器：

  1from contextlib import contextmanager
  2from typing import Iterator, Protocol
  3from dataclasses import dataclass, field
  4from enum import Enum, auto
  5
  6class TransactionState(Enum):
  7    PENDING = auto()
  8    ACTIVE = auto()
  9    COMMITTED = auto()
 10    ROLLED_BACK = auto()
 11
 12class Transactional(Protocol):
 13    """可參與交易的資源協議"""
 14
 15    def begin(self) -> None:
 16        ...
 17
 18    def commit(self) -> None:
 19        ...
 20
 21    def rollback(self) -> None:
 22        ...
 23
 24@dataclass
 25class Transaction:
 26    """交易物件"""
 27    id: str
 28    resources: list[Transactional] = field(default_factory=list)
 29    state: TransactionState = TransactionState.PENDING
 30
 31    def add_resource(self, resource: Transactional) -> None:
 32        if self.state != TransactionState.ACTIVE:
 33            raise RuntimeError("Transaction is not active")
 34        resource.begin()
 35        self.resources.append(resource)
 36
 37    def commit(self) -> None:
 38        if self.state != TransactionState.ACTIVE:
 39            raise RuntimeError("Transaction is not active")
 40
 41        try:
 42            for resource in self.resources:
 43                resource.commit()
 44            self.state = TransactionState.COMMITTED
 45        except Exception:
 46            self.rollback()
 47            raise
 48
 49    def rollback(self) -> None:
 50        if self.state not in (TransactionState.ACTIVE, TransactionState.PENDING):
 51            return
 52
 53        errors = []
 54        for resource in reversed(self.resources):
 55            try:
 56                resource.rollback()
 57            except Exception as e:
 58                errors.append(e)
 59
 60        self.state = TransactionState.ROLLED_BACK
 61
 62        if errors:
 63            raise ExceptionGroup("Rollback failed", errors)
 64
 65class TransactionManager:
 66    """交易管理器"""
 67
 68    def __init__(self) -> None:
 69        self._tx_counter = 0
 70
 71    @contextmanager
 72    def transaction(self) -> Iterator[Transaction]:
 73        """建立新交易"""
 74        self._tx_counter += 1
 75        tx = Transaction(id=f"tx-{self._tx_counter}")
 76        tx.state = TransactionState.ACTIVE
 77
 78        try:
 79            yield tx
 80            tx.commit()
 81        except Exception:
 82            tx.rollback()
 83            raise
 84
 85# 使用範例
 86class DatabaseResource:
 87    """模擬資料庫資源"""
 88
 89    def __init__(self, name: str) -> None:
 90        self.name = name
 91
 92    def begin(self) -> None:
 93        print(f"{self.name}: BEGIN")
 94
 95    def commit(self) -> None:
 96        print(f"{self.name}: COMMIT")
 97
 98    def rollback(self) -> None:
 99        print(f"{self.name}: ROLLBACK")
100
101def main():
102    manager = TransactionManager()
103    db1 = DatabaseResource("primary")
104    db2 = DatabaseResource("replica")
105
106    with manager.transaction() as tx:
107        tx.add_resource(db1)
108        tx.add_resource(db2)
109
110        # 做一些操作...
111        print("Doing work in transaction")
112
113        # 如果拋出異常，兩個資源都會 rollback
114        # raise ValueError("Something went wrong")
115
116    # 正常結束時，兩個資源都會 commit

常見錯誤

1. 忘記 yield

1@contextmanager
2def broken():
3    print("enter")
4    # 忘記 yield！
5    print("exit")
6
7# 使用時會報錯：generator didn't yield

2. 在 finally 中 yield

1@contextmanager
2def also_broken():
3    try:
4        yield
5    finally:
6        yield  # 錯誤！不能在 finally 中 yield

3. 異常處理不當

 1@contextmanager
 2def risky():
 3    resource = acquire_resource()
 4    yield resource
 5    release_resource(resource)  # 如果 with 區塊拋異常，這行不會執行！
 6
 7# 正確做法
 8@contextmanager
 9def safe():
10    resource = acquire_resource()
11    try:
12        yield resource
13    finally:
14        release_resource(resource)  # 一定會執行

小結

概念	用途
`__enter__`/`__exit__`	上下文管理器協議
`@contextmanager`	用生成器建立上下文管理器
`ExitStack`	動態管理多個上下文
`nullcontext`	可選的上下文管理器
`async with`	非同步上下文管理
`@asynccontextmanager`	用非同步生成器建立上下文管理器

思考題

__exit__ 返回 True 和 False 的差別是什麼？
什麼時候應該用 ExitStack 而不是巢狀 with？
@contextmanager 中 yield 前後的程式碼分別對應什麼？

上一章：3.5.2 異常設計架構 下一章：3.5.4 插件系統設計

模組三：進階設計模式

Tue, 20 Jan 2026 00:00:00 +0000

本模組將元編程的「機制理解」轉化為「架構設計能力」，學習如何建立型別安全、錯誤處理完善、可擴展的 Python 系統。

為什麼需要這個模組？

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

型別提示的基礎用法
異常處理的基本策略
with 語句的使用
單例與快取模式

這些知識足以應付日常開發，但當你要設計：

可重用的 Repository 層：需要泛型進階技巧
大型專案的錯誤處理架構：需要異常層級設計
資源管理複雜的系統：需要進階上下文管理
支援擴展的框架：需要插件系統設計

你就需要本模組的進階設計模式。

模組定位

1模組二 元編程 → 模組 3.5 設計模式 → 模組三 CPython
2 (機制) (應用) (底層)

元編程教你「如何建立抽象機制」，本模組教你「如何應用這些機制設計系統」。

章節列表

章節	主題	關鍵收穫
3.1	泛型進階	建立型別安全的抽象層
3.2	異常設計架構	設計大型專案的錯誤處理
3.3	進階上下文管理	複雜資源的優雅管理
3.4	插件系統設計	建立可擴展的架構
3.5	設計模式整合案例	綜合應用所有模式
3.6	軟體設計的取捨藝術	取捨決策框架與業界經驗

案例研究

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

案例	素材	學習重點
快取生命週期管理	config_loader.py	Context Manager
插件架構設計	hook_validator.py	Protocol + 註冊機制
異常設計架構	hook_io.py	異常階層 + ExceptionGroup
泛型驗證器	hook_validator.py	Generic + TypeVar

先備知識

章節	需要先讀
3.1 泛型進階	入門系列 2.2 Optional、Union、泛型
3.2 異常設計	入門系列 5.1 異常處理策略
3.3 上下文管理	入門系列的 `with` 語句使用
3.4 插件系統	本進階系列模組二：元編程
3.5 整合案例	本模組 3.1-3.4
3.6 取捨藝術	本模組 3.1-3.5（應用全部設計模式的決策思維）

學習路徑

本模組適合以下學習路徑：

路徑 A（Web/API 開發）：asyncio → 設計模式 → 打包
路徑 B（框架開發）：元編程 → 設計模式 → CPython → 打包

學習時間

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

上一模組：模組二：元編程 下一模組：模組三：CPython 內部機制

案例：泛型驗證器

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

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何用 Generic 和 TypeVar 建立型別安全的通用驗證器。

先備知識

入門系列 2.2 Optional、Union、泛型
3.5.1 泛型進階

問題背景

現有設計

hook_validator.py 針對特定類型設計：

 1from dataclasses import dataclass, field
 2from pathlib import Path
 3from typing import Optional, List
 4
 5@dataclass
 6class ValidationIssue:
 7    """Single validation issue"""
 8    level: str  # "error" | "warning" | "info"
 9    message: str
10    line: Optional[int] = None
11    suggestion: Optional[str] = None
12
13@dataclass
14class ValidationResult:
15    """Validation result for a single hook"""
16    hook_path: str
17    issues: List[ValidationIssue] = field(default_factory=list)
18    is_compliant: bool = True
19
20    def __post_init__(self):
21        """Calculate is_compliant status"""
22        self.is_compliant = not any(
23            issue.level == "error" for issue in self.issues
24        )
25
26class HookValidator:
27    """Hook compliance validator - specific to Path type"""
28
29    def validate_hook(self, hook_path: str) -> ValidationResult:
30        """Validate a single hook file"""
31        hook_path = self._resolve_path(hook_path)
32
33        if not hook_path.exists():
34            return ValidationResult(
35                hook_path=str(hook_path),
36                issues=[ValidationIssue(
37                    level="error",
38                    message=f"Hook file not found: {hook_path}"
39                )]
40            )
41
42        # ... more validation logic ...
43        return ValidationResult(hook_path=str(hook_path))
44
45    def _resolve_path(self, path: str) -> Path:
46        """Resolve path to absolute path"""
47        p = Path(path)
48        return p if p.is_absolute() else Path.cwd() / p

這個設計的優點

針對具體需求設計：專為驗證 Hook 檔案設計，邏輯清晰
型別明確：輸入是 str，輸出是 ValidationResult

這個設計的限制

當需要驗證其他類型時：

需要複製大量相似程式碼：如果要驗證 API 回應、設定檔、表單輸入，需要寫多個類似的 Validator
驗證邏輯無法重用：「檢查是否為空」「檢查格式」這些通用邏輯無法跨 Validator 共享
型別檢查不夠通用：ValidationResult 綁定了 hook_path: str，無法用於其他場景

進階解決方案

設計目標

建立通用的驗證器介面：定義 Validator[T] 協議
支援任意輸入類型：可以驗證 Path、str、dict、自訂類別
保持型別安全：靜態型別檢查器能捕捉型別錯誤
支援驗證器組合：用 And、Or、Not 組合基本驗證器

實作步驟

步驟 1：定義泛型 Validator 協議

首先，我們需要定義「什麼是驗證器」。使用 Protocol 和 TypeVar 來建立泛型介面：

 1from typing import Protocol, TypeVar, Generic
 2from dataclasses import dataclass, field
 3from abc import abstractmethod
 4
 5# Define a type variable for the input type
 6T = TypeVar("T")
 7
 8# Type variable with contravariance for Protocol
 9T_contra = TypeVar("T_contra", contravariant=True)
10
11@dataclass
12class ValidationResult(Generic[T]):
13    """
14    Generic validation result
15
16    Type parameter T represents the validated value type.
17    This allows type-safe access to the validated value.
18    """
19    value: T
20    is_valid: bool = True
21    errors: list[str] = field(default_factory=list)
22    warnings: list[str] = field(default_factory=list)
23
24    def add_error(self, message: str) -> "ValidationResult[T]":
25        """Add an error and mark as invalid"""
26        self.errors.append(message)
27        self.is_valid = False
28        return self
29
30    def add_warning(self, message: str) -> "ValidationResult[T]":
31        """Add a warning (does not affect validity)"""
32        self.warnings.append(message)
33        return self
34
35class Validator(Protocol[T_contra]):
36    """
37    Generic validator protocol
38
39    Any class that implements validate(value: T) -> ValidationResult[T]
40    is considered a Validator[T].
41
42    Using contravariant type variable because validators consume values.
43    A Validator[Animal] can validate Dog (subtype), so it's contravariant.
44    """
45
46    def validate(self, value: T_contra) -> ValidationResult:
47        """Validate the given value and return the result"""
48        ...

關鍵設計決策：

T_contra 使用逆變（contravariant），因為驗證器是「消費者」
ValidationResult[T] 是泛型，讓結果可以攜帶原始值的型別資訊
Protocol 而非 ABC，支援結構型子型別（不需要顯式繼承）

步驟 2：實作具體驗證器

接下來實作幾個常用的基礎驗證器：

 1from pathlib import Path
 2import re
 3
 4class NotEmptyValidator:
 5    """Validate that a string is not empty"""
 6
 7    def validate(self, value: str) -> ValidationResult[str]:
 8        result = ValidationResult(value=value)
 9        if not value or not value.strip():
10            result.add_error("Value cannot be empty")
11        return result
12
13class PathExistsValidator:
14    """Validate that a path exists"""
15
16    def __init__(self, must_be_file: bool = False, must_be_dir: bool = False):
17        self.must_be_file = must_be_file
18        self.must_be_dir = must_be_dir
19
20    def validate(self, value: Path) -> ValidationResult[Path]:
21        result = ValidationResult(value=value)
22
23        if not value.exists():
24            result.add_error(f"Path does not exist: {value}")
25        elif self.must_be_file and not value.is_file():
26            result.add_error(f"Path is not a file: {value}")
27        elif self.must_be_dir and not value.is_dir():
28            result.add_error(f"Path is not a directory: {value}")
29
30        return result
31
32class PatternValidator:
33    """Validate that a string matches a regex pattern"""
34
35    def __init__(self, pattern: str, error_message: str | None = None):
36        self.pattern = re.compile(pattern)
37        self.error_message = error_message or f"Value must match pattern: {pattern}"
38
39    def validate(self, value: str) -> ValidationResult[str]:
40        result = ValidationResult(value=value)
41        if not self.pattern.match(value):
42            result.add_error(self.error_message)
43        return result
44
45class RangeValidator:
46    """Validate that a number is within a range"""
47
48    def __init__(
49        self,
50        min_value: float | None = None,
51        max_value: float | None = None
52    ):
53        self.min_value = min_value
54        self.max_value = max_value
55
56    def validate(self, value: float | int) -> ValidationResult[float | int]:
57        result = ValidationResult(value=value)
58
59        if self.min_value is not None and value < self.min_value:
60            result.add_error(f"Value {value} is below minimum {self.min_value}")
61        if self.max_value is not None and value > self.max_value:
62            result.add_error(f"Value {value} is above maximum {self.max_value}")
63
64        return result

步驟 3：驗證器組合（And、Or、Not）

驗證器的威力來自於組合。實作三個組合器：

 1from typing import Sequence
 2
 3class AndValidator(Generic[T]):
 4    """
 5    Combine multiple validators with AND logic
 6
 7    All validators must pass for the result to be valid.
 8    """
 9
10    def __init__(self, validators: Sequence[Validator[T]]):
11        self.validators = validators
12
13    def validate(self, value: T) -> ValidationResult[T]:
14        result = ValidationResult(value=value)
15
16        for validator in self.validators:
17            sub_result = validator.validate(value)
18            result.errors.extend(sub_result.errors)
19            result.warnings.extend(sub_result.warnings)
20
21        result.is_valid = len(result.errors) == 0
22        return result
23
24class OrValidator(Generic[T]):
25    """
26    Combine multiple validators with OR logic
27
28    At least one validator must pass for the result to be valid.
29    """
30
31    def __init__(self, validators: Sequence[Validator[T]]):
32        self.validators = validators
33
34    def validate(self, value: T) -> ValidationResult[T]:
35        result = ValidationResult(value=value)
36        all_errors: list[str] = []
37
38        for validator in self.validators:
39            sub_result = validator.validate(value)
40            if sub_result.is_valid:
41                # At least one passed, return success
42                result.warnings.extend(sub_result.warnings)
43                return result
44            all_errors.extend(sub_result.errors)
45
46        # All failed
47        result.add_error(
48            f"None of the validators passed. Errors: {'; '.join(all_errors)}"
49        )
50        return result
51
52class NotValidator(Generic[T]):
53    """
54    Negate a validator
55
56    The result is valid if the inner validator fails.
57    """
58
59    def __init__(self, validator: Validator[T], error_message: str | None = None):
60        self.validator = validator
61        self.error_message = error_message or "Validation should have failed"
62
63    def validate(self, value: T) -> ValidationResult[T]:
64        result = ValidationResult(value=value)
65        sub_result = self.validator.validate(value)
66
67        if sub_result.is_valid:
68            result.add_error(self.error_message)
69        # If inner failed, outer succeeds
70        return result

步驟 4：型別安全的建構器

為了讓組合更流暢，加入建構器模式：

 1from typing import Callable
 2
 3class ValidatorBuilder(Generic[T]):
 4    """
 5    Fluent builder for composing validators
 6
 7    Provides a chainable API for building complex validators.
 8    """
 9
10    def __init__(self):
11        self._validators: list[Validator[T]] = []
12
13    def add(self, validator: Validator[T]) -> "ValidatorBuilder[T]":
14        """Add a validator to the chain"""
15        self._validators.append(validator)
16        return self
17
18    def add_if(
19        self,
20        condition: bool,
21        validator: Validator[T]
22    ) -> "ValidatorBuilder[T]":
23        """Conditionally add a validator"""
24        if condition:
25            self._validators.append(validator)
26        return self
27
28    def build(self) -> Validator[T]:
29        """Build the final AND-combined validator"""
30        if len(self._validators) == 1:
31            return self._validators[0]
32        return AndValidator(self._validators)
33
34    def build_or(self) -> Validator[T]:
35        """Build with OR logic instead of AND"""
36        if len(self._validators) == 1:
37            return self._validators[0]
38        return OrValidator(self._validators)
39
40def validator_for(type_hint: type[T]) -> ValidatorBuilder[T]:
41    """
42    Create a type-safe validator builder
43
44    Usage:
45        validator = (
46            validator_for(str)
47            .add(NotEmptyValidator())
48            .add(PatternValidator(r"^[a-z]+$"))
49            .build()
50        )
51    """
52    return ValidatorBuilder[T]()

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Generic Validator System
  4
  5A type-safe, composable validation framework using Generic and TypeVar.
  6"""
  7
  8from __future__ import annotations
  9from abc import abstractmethod
 10from dataclasses import dataclass, field
 11from pathlib import Path
 12from typing import (
 13    Callable,
 14    Generic,
 15    Protocol,
 16    Sequence,
 17    TypeVar,
 18    runtime_checkable,
 19)
 20import re
 21
 22# ===== Type Variables =====
 23
 24T = TypeVar("T")
 25T_contra = TypeVar("T_contra", contravariant=True)
 26
 27# ===== Core Types =====
 28
 29@dataclass
 30class ValidationResult(Generic[T]):
 31    """
 32    Generic validation result
 33
 34    Attributes:
 35        value: The validated value (preserves type information)
 36        is_valid: Whether validation passed
 37        errors: List of error messages (cause validation failure)
 38        warnings: List of warning messages (informational only)
 39    """
 40    value: T
 41    is_valid: bool = True
 42    errors: list[str] = field(default_factory=list)
 43    warnings: list[str] = field(default_factory=list)
 44
 45    def add_error(self, message: str) -> ValidationResult[T]:
 46        """Add an error and mark as invalid"""
 47        self.errors.append(message)
 48        self.is_valid = False
 49        return self
 50
 51    def add_warning(self, message: str) -> ValidationResult[T]:
 52        """Add a warning (does not affect validity)"""
 53        self.warnings.append(message)
 54        return self
 55
 56    def __bool__(self) -> bool:
 57        """Allow using result in boolean context"""
 58        return self.is_valid
 59
 60@runtime_checkable
 61class Validator(Protocol[T_contra]):
 62    """
 63    Generic validator protocol
 64
 65    Any class implementing validate(value) -> ValidationResult
 66    satisfies this protocol.
 67    """
 68
 69    def validate(self, value: T_contra) -> ValidationResult:
 70        """Validate the given value"""
 71        ...
 72
 73# ===== Basic Validators =====
 74
 75class NotEmptyValidator:
 76    """Validate that a string is not empty"""
 77
 78    def validate(self, value: str) -> ValidationResult[str]:
 79        result = ValidationResult(value=value)
 80        if not value or not value.strip():
 81            result.add_error("Value cannot be empty")
 82        return result
 83
 84class PathExistsValidator:
 85    """Validate that a path exists"""
 86
 87    def __init__(
 88        self,
 89        must_be_file: bool = False,
 90        must_be_dir: bool = False
 91    ):
 92        self.must_be_file = must_be_file
 93        self.must_be_dir = must_be_dir
 94
 95    def validate(self, value: Path) -> ValidationResult[Path]:
 96        result = ValidationResult(value=value)
 97
 98        if not value.exists():
 99            result.add_error(f"Path does not exist: {value}")
100        elif self.must_be_file and not value.is_file():
101            result.add_error(f"Path is not a file: {value}")
102        elif self.must_be_dir and not value.is_dir():
103            result.add_error(f"Path is not a directory: {value}")
104
105        return result
106
107class PatternValidator:
108    """Validate string matches a regex pattern"""
109
110    def __init__(self, pattern: str, error_message: str | None = None):
111        self.pattern = re.compile(pattern)
112        self.error_message = error_message or f"Must match pattern: {pattern}"
113
114    def validate(self, value: str) -> ValidationResult[str]:
115        result = ValidationResult(value=value)
116        if not self.pattern.match(value):
117            result.add_error(self.error_message)
118        return result
119
120class RangeValidator:
121    """Validate number is within range"""
122
123    def __init__(
124        self,
125        min_value: float | None = None,
126        max_value: float | None = None
127    ):
128        self.min_value = min_value
129        self.max_value = max_value
130
131    def validate(self, value: float | int) -> ValidationResult[float | int]:
132        result = ValidationResult(value=value)
133        if self.min_value is not None and value < self.min_value:
134            result.add_error(f"Value {value} < minimum {self.min_value}")
135        if self.max_value is not None and value > self.max_value:
136            result.add_error(f"Value {value} > maximum {self.max_value}")
137        return result
138
139class LengthValidator:
140    """Validate string length"""
141
142    def __init__(
143        self,
144        min_length: int | None = None,
145        max_length: int | None = None
146    ):
147        self.min_length = min_length
148        self.max_length = max_length
149
150    def validate(self, value: str) -> ValidationResult[str]:
151        result = ValidationResult(value=value)
152        length = len(value)
153
154        if self.min_length is not None and length < self.min_length:
155            result.add_error(f"Length {length} < minimum {self.min_length}")
156        if self.max_length is not None and length > self.max_length:
157            result.add_error(f"Length {length} > maximum {self.max_length}")
158
159        return result
160
161class TypeValidator(Generic[T]):
162    """Validate value is of expected type"""
163
164    def __init__(self, expected_type: type[T], type_name: str | None = None):
165        self.expected_type = expected_type
166        self.type_name = type_name or expected_type.__name__
167
168    def validate(self, value: object) -> ValidationResult[T]:
169        if isinstance(value, self.expected_type):
170            return ValidationResult(value=value)  # type: ignore
171        else:
172            result = ValidationResult(value=value)  # type: ignore
173            result.add_error(
174                f"Expected {self.type_name}, got {type(value).__name__}"
175            )
176            return result
177
178# ===== Composite Validators =====
179
180class AndValidator(Generic[T]):
181    """Combine validators with AND logic (all must pass)"""
182
183    def __init__(self, validators: Sequence[Validator[T]]):
184        self.validators = list(validators)
185
186    def validate(self, value: T) -> ValidationResult[T]:
187        result = ValidationResult(value=value)
188
189        for validator in self.validators:
190            sub_result = validator.validate(value)
191            result.errors.extend(sub_result.errors)
192            result.warnings.extend(sub_result.warnings)
193
194        result.is_valid = len(result.errors) == 0
195        return result
196
197class OrValidator(Generic[T]):
198    """Combine validators with OR logic (at least one must pass)"""
199
200    def __init__(self, validators: Sequence[Validator[T]]):
201        self.validators = list(validators)
202
203    def validate(self, value: T) -> ValidationResult[T]:
204        result = ValidationResult(value=value)
205        all_errors: list[str] = []
206
207        for validator in self.validators:
208            sub_result = validator.validate(value)
209            if sub_result.is_valid:
210                result.warnings.extend(sub_result.warnings)
211                return result
212            all_errors.extend(sub_result.errors)
213
214        result.add_error(f"No validator passed: {'; '.join(all_errors)}")
215        return result
216
217class NotValidator(Generic[T]):
218    """Negate a validator (passes if inner validator fails)"""
219
220    def __init__(self, validator: Validator[T], error_message: str | None = None):
221        self.validator = validator
222        self.error_message = error_message or "Validation should have failed"
223
224    def validate(self, value: T) -> ValidationResult[T]:
225        result = ValidationResult(value=value)
226        sub_result = self.validator.validate(value)
227
228        if sub_result.is_valid:
229            result.add_error(self.error_message)
230
231        return result
232
233# ===== Builder =====
234
235class ValidatorBuilder(Generic[T]):
236    """Fluent builder for composing validators"""
237
238    def __init__(self):
239        self._validators: list[Validator[T]] = []
240
241    def add(self, validator: Validator[T]) -> ValidatorBuilder[T]:
242        """Add a validator"""
243        self._validators.append(validator)
244        return self
245
246    def add_if(
247        self,
248        condition: bool,
249        validator: Validator[T]
250    ) -> ValidatorBuilder[T]:
251        """Conditionally add a validator"""
252        if condition:
253            self._validators.append(validator)
254        return self
255
256    def build(self) -> Validator[T]:
257        """Build AND-combined validator"""
258        if len(self._validators) == 0:
259            raise ValueError("No validators added")
260        if len(self._validators) == 1:
261            return self._validators[0]
262        return AndValidator(self._validators)
263
264    def build_or(self) -> Validator[T]:
265        """Build OR-combined validator"""
266        if len(self._validators) == 0:
267            raise ValueError("No validators added")
268        if len(self._validators) == 1:
269            return self._validators[0]
270        return OrValidator(self._validators)
271
272def validator_for(type_hint: type[T]) -> ValidatorBuilder[T]:
273    """Create a type-safe validator builder"""
274    return ValidatorBuilder[T]()
275
276# ===== List Validator =====
277
278class ListValidator(Generic[T]):
279    """Validate each element in a list"""
280
281    def __init__(
282        self,
283        element_validator: Validator[T],
284        min_length: int | None = None,
285        max_length: int | None = None
286    ):
287        self.element_validator = element_validator
288        self.min_length = min_length
289        self.max_length = max_length
290
291    def validate(self, value: list[T]) -> ValidationResult[list[T]]:
292        result = ValidationResult(value=value)
293
294        # Check list length
295        if self.min_length is not None and len(value) < self.min_length:
296            result.add_error(f"List length {len(value)} < minimum {self.min_length}")
297        if self.max_length is not None and len(value) > self.max_length:
298            result.add_error(f"List length {len(value)} > maximum {self.max_length}")
299
300        # Validate each element
301        for i, item in enumerate(value):
302            sub_result = self.element_validator.validate(item)
303            for error in sub_result.errors:
304                result.add_error(f"[{i}] {error}")
305            for warning in sub_result.warnings:
306                result.add_warning(f"[{i}] {warning}")
307
308        return result
309
310# ===== Demo =====
311
312if __name__ == "__main__":
313    print("=== Generic Validator Demo ===\n")
314
315    # Example 1: Basic validators
316    print("1. Basic Validators")
317    print("-" * 40)
318
319    not_empty = NotEmptyValidator()
320    print(f"  NotEmpty(''): {not_empty.validate('')}")
321    print(f"  NotEmpty('hello'): {not_empty.validate('hello')}")
322
323    # Example 2: Path validator
324    print("\n2. Path Validator")
325    print("-" * 40)
326
327    path_validator = PathExistsValidator(must_be_file=True)
328    result = path_validator.validate(Path("/etc/hosts"))
329    print(f"  /etc/hosts: valid={result.is_valid}")
330
331    result = path_validator.validate(Path("/nonexistent"))
332    print(f"  /nonexistent: valid={result.is_valid}, errors={result.errors}")
333
334    # Example 3: Composed validators
335    print("\n3. Composed Validators (AND)")
336    print("-" * 40)
337
338    username_validator = AndValidator[str]([
339        NotEmptyValidator(),
340        LengthValidator(min_length=3, max_length=20),
341        PatternValidator(r"^[a-z][a-z0-9_]*$", "Must be lowercase alphanumeric"),
342    ])
343
344    test_usernames = ["", "ab", "valid_user", "Invalid", "a" * 25]
345    for username in test_usernames:
346        result = username_validator.validate(username)
347        status = "PASS" if result.is_valid else "FAIL"
348        print(f"  '{username}': {status}")
349        if not result.is_valid:
350            for error in result.errors:
351                print(f"    - {error}")
352
353    # Example 4: Builder pattern
354    print("\n4. Builder Pattern")
355    print("-" * 40)
356
357    email_validator = (
358        validator_for(str)
359        .add(NotEmptyValidator())
360        .add(PatternValidator(
361            r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$",
362            "Invalid email format"
363        ))
364        .build()
365    )
366
367    test_emails = ["", "invalid", "test@example.com"]
368    for email in test_emails:
369        result = email_validator.validate(email)
370        status = "PASS" if result.is_valid else "FAIL"
371        print(f"  '{email}': {status}")
372
373    # Example 5: List validator
374    print("\n5. List Validator")
375    print("-" * 40)
376
377    tags_validator = ListValidator(
378        element_validator=AndValidator[str]([
379            NotEmptyValidator(),
380            LengthValidator(max_length=20),
381        ]),
382        min_length=1,
383        max_length=5
384    )
385
386    test_tags = [
387        ["python", "typing"],
388        [],
389        ["valid", "", "also-valid"],
390    ]
391
392    for tags in test_tags:
393        result = tags_validator.validate(tags)
394        status = "PASS" if result.is_valid else "FAIL"
395        print(f"  {tags}: {status}")
396        if not result.is_valid:
397            for error in result.errors:
398                print(f"    - {error}")
399
400    print("\n=== Demo Complete ===")

使用範例

基本使用

 1from pathlib import Path
 2
 3# Create validators
 4not_empty = NotEmptyValidator()
 5path_exists = PathExistsValidator(must_be_file=True)
 6
 7# Validate string
 8result = not_empty.validate("hello")
 9print(result.is_valid)  # True
10
11result = not_empty.validate("")
12print(result.is_valid)  # False
13print(result.errors)    # ["Value cannot be empty"]
14
15# Validate path
16result = path_exists.validate(Path("/etc/hosts"))
17print(result.is_valid)  # True (on Unix systems)
18
19# Using ValidationResult in boolean context
20if not_empty.validate("test"):
21    print("Validation passed!")

組合驗證

 1# Username validator: non-empty, 3-20 chars, lowercase alphanumeric
 2username_validator = AndValidator[str]([
 3    NotEmptyValidator(),
 4    LengthValidator(min_length=3, max_length=20),
 5    PatternValidator(r"^[a-z][a-z0-9_]*$"),
 6])
 7
 8# Test cases
 9result = username_validator.validate("valid_user")
10print(result.is_valid)  # True
11
12result = username_validator.validate("ab")
13print(result.is_valid)  # False
14print(result.errors)    # ["Length 2 < minimum 3"]
15
16# OR validation: accept either email or username format
17login_validator = OrValidator[str]([
18    PatternValidator(r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"),
19    PatternValidator(r"^[a-z][a-z0-9_]{2,19}$"),
20])
21
22print(login_validator.validate("user@example.com").is_valid)  # True
23print(login_validator.validate("valid_user").is_valid)        # True
24print(login_validator.validate("X").is_valid)                  # False

使用 Builder 模式

 1# Fluent API for building validators
 2password_validator = (
 3    validator_for(str)
 4    .add(NotEmptyValidator())
 5    .add(LengthValidator(min_length=8, max_length=128))
 6    .add(PatternValidator(r".*[A-Z].*", "Must contain uppercase"))
 7    .add(PatternValidator(r".*[a-z].*", "Must contain lowercase"))
 8    .add(PatternValidator(r".*[0-9].*", "Must contain digit"))
 9    .build()
10)
11
12result = password_validator.validate("weakpass")
13print(result.errors)
14# ["Must contain uppercase", "Must contain digit"]
15
16result = password_validator.validate("Strong1Password")
17print(result.is_valid)  # True

驗證列表元素

 1# Validate a list of tags
 2tag_validator = NotEmptyValidator()
 3tags_validator = ListValidator(
 4    element_validator=tag_validator,
 5    min_length=1,
 6    max_length=10
 7)
 8
 9result = tags_validator.validate(["python", "typing", "generic"])
10print(result.is_valid)  # True
11
12result = tags_validator.validate(["valid", "", "also-valid"])
13print(result.is_valid)  # False
14print(result.errors)    # ["[1] Value cannot be empty"]

設計權衡

面向	具體類型	泛型設計
重用性	低：每個類型需要獨立實作	高：一次實作，多處使用
型別推導	簡單：型別固定	需要技巧：需正確標註 TypeVar
學習曲線	低：直覺易懂	中：需理解 Generic、Protocol
IDE 支援	完整：型別明確	需要正確標註才能獲得完整支援
執行效能	略佳：無泛型開銷	略差：有 Protocol 檢查開銷
錯誤訊息	清晰：直接指出問題	可能較模糊：泛型相關錯誤不易讀

何時選擇泛型設計？

選擇泛型設計當：

驗證邏輯會用於多種類型
需要組合多個驗證器
正在建立可重用的驗證函式庫
重視編譯時期的型別安全

選擇具體類型當：

只驗證單一特定類型
驗證邏輯非常簡單
團隊對泛型不熟悉
效能是關鍵考量

什麼時候該用這個技術？

適合使用：

需要驗證多種類型的函式庫
驗證邏輯需要組合重用
重視型別安全
API 設計需要表達「這個驗證器接受 T 類型」

不建議使用：

只驗證單一類型
驗證邏輯很簡單（幾行 if-else 就能搞定）
團隊不熟悉泛型語法
程式碼不會被重用

練習

基礎練習

1. 實作 `RangeValidator[int]` 和 `LengthValidator[str]`

參考上面的 RangeValidator 實作，確保它可以正確驗證整數範圍。測試案例：

1age_validator = RangeValidator(min_value=0, max_value=150)
2assert age_validator.validate(25).is_valid
3assert not age_validator.validate(-1).is_valid
4assert not age_validator.validate(200).is_valid

2. 實作 `EmailValidator`

建立一個 Email 驗證器，組合 NotEmptyValidator 和 PatternValidator：

1email_validator = EmailValidator()
2assert email_validator.validate("user@example.com").is_valid
3assert not email_validator.validate("invalid").is_valid

進階練習

1. 實作 `ListValidator[T]` 驗證列表中的每個元素

建立一個泛型列表驗證器，可以：

驗證列表長度
對每個元素執行子驗證器
收集所有錯誤，標註元素索引

1int_list_validator = ListValidator(
2    element_validator=RangeValidator(min_value=0),
3    min_length=1
4)
5result = int_list_validator.validate([1, 2, -3, 4])
6# errors: ["[2] Value -3 < minimum 0"]

2. 實作 `ConditionalValidator[T]`

建立一個條件驗證器，只在條件成立時執行驗證：

1# Only validate age if it's provided (not None)
2optional_age_validator = ConditionalValidator(
3    condition=lambda x: x is not None,
4    validator=RangeValidator(min_value=0, max_value=150)
5)

挑戰題

1. 實作 `SchemaValidator` 驗證字典結構

建立一個驗證器，可以驗證字典的結構和值：

 1user_schema = SchemaValidator({
 2    "name": NotEmptyValidator(),
 3    "age": RangeValidator(min_value=0, max_value=150),
 4    "email": EmailValidator(),
 5}, required_keys=["name", "email"])
 6
 7result = user_schema.validate({
 8    "name": "Alice",
 9    "age": 30,
10    "email": "alice@example.com"
11})
12assert result.is_valid
13
14result = user_schema.validate({
15    "name": "",
16    "age": -5,
17})
18# errors: ["name: Value cannot be empty", "age: Value -5 < minimum 0", "Missing required key: email"]

提示：

使用 dict[str, Validator[Any]] 作為 schema 類型
處理可選欄位和必填欄位
考慮巢狀 schema 的支援

延伸閱讀

上一章：異常設計架構 返回：模組 3.5：進階設計模式

3.5.4 插件系統設計

Tue, 20 Jan 2026 00:00:00 +0000

插件系統讓應用程式可以在不修改核心程式碼的情況下擴展功能。本章介紹三種常見的插件架構模式，以及如何使用 Python 的動態載入機制實現它們。

先備知識

本進階系列模組二：元編程
特別是 Metaclass 與 __init_subclass__

插件架構模式

模式一：基於繼承

最簡單的插件模式，插件必須繼承基類：

 1from abc import ABC, abstractmethod
 2from typing import ClassVar
 3
 4class Plugin(ABC):
 5    """插件基類"""
 6    name: ClassVar[str]  # 每個插件必須定義名稱
 7
 8    @abstractmethod
 9    def execute(self, context: dict) -> dict:
10        """執行插件邏輯"""
11        ...
12
13class LoggingPlugin(Plugin):
14    name = "logging"
15
16    def execute(self, context: dict) -> dict:
17        print(f"Processing: {context}")
18        return context
19
20class ValidationPlugin(Plugin):
21    name = "validation"
22
23    def execute(self, context: dict) -> dict:
24        if not context.get("valid"):
25            raise ValueError("Invalid context")
26        return context

優點：簡單明確，IDE 支援好缺點：強制耦合，無法使用第三方類別

模式二：基於註冊

使用裝飾器或顯式註冊，更靈活：

 1from typing import Callable, TypeAlias
 2
 3PluginFunc: TypeAlias = Callable[[dict], dict]
 4
 5class PluginRegistry:
 6    """插件註冊表"""
 7
 8    def __init__(self) -> None:
 9        self._plugins: dict[str, PluginFunc] = {}
10
11    def register(self, name: str) -> Callable[[PluginFunc], PluginFunc]:
12        """裝飾器：註冊插件"""
13        def decorator(func: PluginFunc) -> PluginFunc:
14            if name in self._plugins:
15                raise ValueError(f"Plugin '{name}' already registered")
16            self._plugins[name] = func
17            return func
18        return decorator
19
20    def get(self, name: str) -> PluginFunc | None:
21        return self._plugins.get(name)
22
23    def list_plugins(self) -> list[str]:
24        return list(self._plugins.keys())
25
26# 全域註冊表
27registry = PluginRegistry()
28
29@registry.register("uppercase")
30def uppercase_plugin(context: dict) -> dict:
31    context["text"] = context.get("text", "").upper()
32    return context
33
34@registry.register("lowercase")
35def lowercase_plugin(context: dict) -> dict:
36    context["text"] = context.get("text", "").lower()
37    return context
38
39# 使用
40plugin = registry.get("uppercase")
41if plugin:
42    result = plugin({"text": "Hello"})

優點：靈活，支援函式和類別缺點：需要顯式註冊

模式三：基於發現（使用 `__init_subclass__`）

利用 Python 的元編程機制自動發現插件：

 1from typing import ClassVar
 2
 3class AutoRegisterPlugin:
 4    """自動註冊的插件基類"""
 5    _registry: ClassVar[dict[str, type["AutoRegisterPlugin"]]] = {}
 6    name: ClassVar[str]
 7
 8    def __init_subclass__(cls, **kwargs) -> None:
 9        super().__init_subclass__(**kwargs)
10        # 跳過沒有定義 name 的中間類別
11        if hasattr(cls, "name") and cls.name:
12            if cls.name in AutoRegisterPlugin._registry:
13                raise ValueError(f"Plugin '{cls.name}' already registered")
14            AutoRegisterPlugin._registry[cls.name] = cls
15
16    @classmethod
17    def get_plugin(cls, name: str) -> type["AutoRegisterPlugin"] | None:
18        return cls._registry.get(name)
19
20    @classmethod
21    def list_plugins(cls) -> list[str]:
22        return list(cls._registry.keys())
23
24    def execute(self, context: dict) -> dict:
25        raise NotImplementedError
26
27# 定義插件只需要繼承，自動註冊
28class FormatPlugin(AutoRegisterPlugin):
29    name = "format"
30
31    def execute(self, context: dict) -> dict:
32        context["formatted"] = True
33        return context
34
35class CompressPlugin(AutoRegisterPlugin):
36    name = "compress"
37
38    def execute(self, context: dict) -> dict:
39        context["compressed"] = True
40        return context
41
42# 自動發現
43print(AutoRegisterPlugin.list_plugins())  # ['format', 'compress']

優點：無需顯式註冊，只要繼承就會被發現缺點：必須繼承基類，Python 專屬

使用 Metaclass 的進階版本

 1from typing import ClassVar
 2
 3class PluginMeta(type):
 4    """插件元類別"""
 5    _registry: dict[str, type] = {}
 6
 7    def __new__(mcs, name: str, bases: tuple, namespace: dict) -> type:
 8        cls = super().__new__(mcs, name, bases, namespace)
 9
10        # 跳過基類
11        if bases and hasattr(cls, "plugin_name"):
12            plugin_name = cls.plugin_name
13            if plugin_name in mcs._registry:
14                raise ValueError(f"Plugin '{plugin_name}' already registered")
15            mcs._registry[plugin_name] = cls
16
17        return cls
18
19    @classmethod
20    def get_plugin(mcs, name: str) -> type | None:
21        return mcs._registry.get(name)
22
23class PluginBase(metaclass=PluginMeta):
24    """插件基類"""
25    plugin_name: ClassVar[str]
26
27    def run(self) -> None:
28        raise NotImplementedError
29
30class MyPlugin(PluginBase):
31    plugin_name = "my_plugin"
32
33    def run(self) -> None:
34        print("MyPlugin running")
35
36# 使用
37plugin_cls = PluginMeta.get_plugin("my_plugin")
38if plugin_cls:
39    plugin_cls().run()

動態載入模組

importlib 基礎

 1import importlib
 2from types import ModuleType
 3
 4def load_module(module_path: str) -> ModuleType:
 5    """動態載入模組"""
 6    return importlib.import_module(module_path)
 7
 8def load_class(module_path: str, class_name: str) -> type:
 9    """從模組載入類別"""
10    module = importlib.import_module(module_path)
11    return getattr(module, class_name)
12
13# 使用
14# 假設有 myapp/plugins/custom.py 定義了 CustomPlugin
15plugin_cls = load_class("myapp.plugins.custom", "CustomPlugin")
16plugin = plugin_cls()

從檔案路徑載入

 1import importlib.util
 2from pathlib import Path
 3from types import ModuleType
 4
 5def load_module_from_path(path: Path) -> ModuleType:
 6    """從檔案路徑載入模組"""
 7    spec = importlib.util.spec_from_file_location(
 8        path.stem,  # 模組名稱
 9        path        # 檔案路徑
10    )
11    if spec is None or spec.loader is None:
12        raise ImportError(f"Cannot load module from {path}")
13
14    module = importlib.util.module_from_spec(spec)
15    spec.loader.exec_module(module)
16    return module
17
18# 使用
19plugin_module = load_module_from_path(Path("./plugins/custom_plugin.py"))

importlib.metadata 的 entry_points（現代做法）

這是 Python 套件生態系統推薦的插件發現機制：

 1# 在 pyproject.toml 中定義 entry points
 2"""
 3[project.entry-points."myapp.plugins"]
 4format = "myapp_format_plugin:FormatPlugin"
 5compress = "myapp_compress_plugin:CompressPlugin"
 6"""
 7
 8from importlib.metadata import entry_points
 9
10def discover_plugins(group: str) -> dict[str, type]:
11    """發現已安裝套件中的插件"""
12    plugins = {}
13
14    # Python 3.10+
15    eps = entry_points(group=group)
16
17    for ep in eps:
18        try:
19            plugin_cls = ep.load()
20            plugins[ep.name] = plugin_cls
21        except Exception as e:
22            print(f"Failed to load plugin {ep.name}: {e}")
23
24    return plugins
25
26# 發現所有 myapp.plugins 群組的插件
27plugins = discover_plugins("myapp.plugins")
28for name, cls in plugins.items():
29    print(f"Found plugin: {name} -> {cls}")

優點：

標準化的發現機制
支援第三方套件提供插件
pip 安裝即可使用

實際範例一：Hook 系統的插件化改造

基於入門系列的 Hook 系統概念，設計一個插件化的 Hook 框架：

  1from abc import ABC, abstractmethod
  2from dataclasses import dataclass
  3from enum import Enum
  4from pathlib import Path
  5from typing import ClassVar
  6import importlib.util
  7
  8class HookEvent(Enum):
  9    PRE_TOOL_USE = "PreToolUse"
 10    POST_TOOL_USE = "PostToolUse"
 11    SESSION_START = "SessionStart"
 12    SESSION_END = "SessionEnd"
 13
 14@dataclass
 15class HookContext:
 16    """Hook 執行的上下文"""
 17    event: HookEvent
 18    tool_name: str | None = None
 19    input_data: dict | None = None
 20
 21@dataclass
 22class HookResult:
 23    """Hook 執行結果"""
 24    success: bool
 25    message: str
 26    modified_context: HookContext | None = None
 27
 28class HookPlugin(ABC):
 29    """Hook 插件基類"""
 30    _registry: ClassVar[dict[str, list[type["HookPlugin"]]]] = {}
 31
 32    # 子類別必須定義的屬性
 33    name: ClassVar[str]
 34    events: ClassVar[list[HookEvent]]
 35    priority: ClassVar[int] = 100  # 預設優先級
 36
 37    def __init_subclass__(cls, **kwargs) -> None:
 38        super().__init_subclass__(**kwargs)
 39        if hasattr(cls, "name") and hasattr(cls, "events"):
 40            for event in cls.events:
 41                event_name = event.value
 42                if event_name not in HookPlugin._registry:
 43                    HookPlugin._registry[event_name] = []
 44                HookPlugin._registry[event_name].append(cls)
 45                # 按優先級排序
 46                HookPlugin._registry[event_name].sort(
 47                    key=lambda c: c.priority
 48                )
 49
 50    @abstractmethod
 51    def execute(self, context: HookContext) -> HookResult:
 52        """執行 Hook 邏輯"""
 53        ...
 54
 55    @classmethod
 56    def get_hooks_for_event(cls, event: HookEvent) -> list[type["HookPlugin"]]:
 57        """取得特定事件的所有 Hook"""
 58        return cls._registry.get(event.value, [])
 59
 60# 定義具體的 Hook 插件
 61class SecurityCheckHook(HookPlugin):
 62    """安全檢查 Hook"""
 63    name = "security_check"
 64    events = [HookEvent.PRE_TOOL_USE]
 65    priority = 10  # 高優先級，先執行
 66
 67    DANGEROUS_PATTERNS = ["rm -rf", "DROP TABLE", "sudo"]
 68
 69    def execute(self, context: HookContext) -> HookResult:
 70        if context.input_data:
 71            command = context.input_data.get("command", "")
 72            for pattern in self.DANGEROUS_PATTERNS:
 73                if pattern in command:
 74                    return HookResult(
 75                        success=False,
 76                        message=f"Blocked dangerous pattern: {pattern}"
 77                    )
 78        return HookResult(success=True, message="Security check passed")
 79
 80class LoggingHook(HookPlugin):
 81    """日誌記錄 Hook"""
 82    name = "logging"
 83    events = [HookEvent.PRE_TOOL_USE, HookEvent.POST_TOOL_USE]
 84    priority = 1000  # 低優先級，最後執行
 85
 86    def execute(self, context: HookContext) -> HookResult:
 87        print(f"[{context.event.value}] Tool: {context.tool_name}")
 88        return HookResult(success=True, message="Logged")
 89
 90# Hook 執行器
 91class HookRunner:
 92    """執行 Hook 的管理器"""
 93
 94    def run_hooks(self, event: HookEvent, context: HookContext) -> list[HookResult]:
 95        """執行特定事件的所有 Hook"""
 96        results = []
 97        hook_classes = HookPlugin.get_hooks_for_event(event)
 98
 99        for hook_cls in hook_classes:
100            hook = hook_cls()
101            try:
102                result = hook.execute(context)
103                results.append(result)
104                # 如果 Hook 失敗且事件是 PRE，中斷執行
105                if not result.success and event == HookEvent.PRE_TOOL_USE:
106                    break
107            except Exception as e:
108                results.append(HookResult(
109                    success=False,
110                    message=f"Hook {hook_cls.name} failed: {e}"
111                ))
112
113        return results
114
115# 使用
116runner = HookRunner()
117context = HookContext(
118    event=HookEvent.PRE_TOOL_USE,
119    tool_name="Bash",
120    input_data={"command": "ls -la"}
121)
122results = runner.run_hooks(HookEvent.PRE_TOOL_USE, context)

實際範例二：通用插件框架設計

一個更通用的插件框架，支援動態載入和生命週期管理：

  1from abc import ABC, abstractmethod
  2from dataclasses import dataclass, field
  3from enum import Enum, auto
  4from pathlib import Path
  5from typing import Any
  6import importlib.util
  7
  8class PluginState(Enum):
  9    UNLOADED = auto()
 10    LOADED = auto()
 11    ACTIVE = auto()
 12    ERROR = auto()
 13
 14@dataclass
 15class PluginInfo:
 16    """插件元資訊"""
 17    name: str
 18    version: str
 19    description: str
 20    author: str = ""
 21    dependencies: list[str] = field(default_factory=list)
 22
 23class BasePlugin(ABC):
 24    """插件基類"""
 25
 26    @property
 27    @abstractmethod
 28    def info(self) -> PluginInfo:
 29        """返回插件資訊"""
 30        ...
 31
 32    def on_load(self) -> None:
 33        """插件載入時呼叫"""
 34        pass
 35
 36    def on_unload(self) -> None:
 37        """插件卸載時呼叫"""
 38        pass
 39
 40    def on_activate(self) -> None:
 41        """插件啟用時呼叫"""
 42        pass
 43
 44    def on_deactivate(self) -> None:
 45        """插件停用時呼叫"""
 46        pass
 47
 48@dataclass
 49class LoadedPlugin:
 50    """已載入的插件包裝"""
 51    plugin: BasePlugin
 52    state: PluginState = PluginState.UNLOADED
 53    error: str | None = None
 54
 55class PluginManager:
 56    """插件管理器"""
 57
 58    def __init__(self, plugin_dir: Path | None = None) -> None:
 59        self._plugins: dict[str, LoadedPlugin] = {}
 60        self._plugin_dir = plugin_dir
 61
 62    def load_plugin(self, path: Path) -> str:
 63        """從檔案載入插件"""
 64        try:
 65            # 動態載入模組
 66            spec = importlib.util.spec_from_file_location(
 67                path.stem, path
 68            )
 69            if spec is None or spec.loader is None:
 70                raise ImportError(f"Cannot load {path}")
 71
 72            module = importlib.util.module_from_spec(spec)
 73            spec.loader.exec_module(module)
 74
 75            # 尋找 BasePlugin 的子類別
 76            plugin_cls = None
 77            for attr_name in dir(module):
 78                attr = getattr(module, attr_name)
 79                if (isinstance(attr, type) and
 80                    issubclass(attr, BasePlugin) and
 81                    attr is not BasePlugin):
 82                    plugin_cls = attr
 83                    break
 84
 85            if plugin_cls is None:
 86                raise ImportError(f"No plugin class found in {path}")
 87
 88            # 實例化插件
 89            plugin = plugin_cls()
 90            plugin_name = plugin.info.name
 91
 92            # 檢查依賴
 93            for dep in plugin.info.dependencies:
 94                if dep not in self._plugins:
 95                    raise ImportError(f"Missing dependency: {dep}")
 96
 97            # 呼叫生命週期方法
 98            plugin.on_load()
 99
100            self._plugins[plugin_name] = LoadedPlugin(
101                plugin=plugin,
102                state=PluginState.LOADED
103            )
104
105            return plugin_name
106
107        except Exception as e:
108            raise ImportError(f"Failed to load plugin from {path}: {e}")
109
110    def unload_plugin(self, name: str) -> None:
111        """卸載插件"""
112        if name not in self._plugins:
113            raise KeyError(f"Plugin '{name}' not found")
114
115        loaded = self._plugins[name]
116
117        # 先停用
118        if loaded.state == PluginState.ACTIVE:
119            self.deactivate_plugin(name)
120
121        # 呼叫生命週期方法
122        loaded.plugin.on_unload()
123
124        del self._plugins[name]
125
126    def activate_plugin(self, name: str) -> None:
127        """啟用插件"""
128        if name not in self._plugins:
129            raise KeyError(f"Plugin '{name}' not found")
130
131        loaded = self._plugins[name]
132        if loaded.state != PluginState.LOADED:
133            raise RuntimeError(f"Plugin '{name}' is not in LOADED state")
134
135        try:
136            loaded.plugin.on_activate()
137            loaded.state = PluginState.ACTIVE
138        except Exception as e:
139            loaded.state = PluginState.ERROR
140            loaded.error = str(e)
141            raise
142
143    def deactivate_plugin(self, name: str) -> None:
144        """停用插件"""
145        if name not in self._plugins:
146            raise KeyError(f"Plugin '{name}' not found")
147
148        loaded = self._plugins[name]
149        if loaded.state != PluginState.ACTIVE:
150            return
151
152        loaded.plugin.on_deactivate()
153        loaded.state = PluginState.LOADED
154
155    def discover_plugins(self) -> list[Path]:
156        """發現插件目錄中的所有插件"""
157        if self._plugin_dir is None:
158            return []
159
160        return list(self._plugin_dir.glob("*.py"))
161
162    def load_all_plugins(self) -> dict[str, str | None]:
163        """載入所有發現的插件"""
164        results: dict[str, str | None] = {}
165        for path in self.discover_plugins():
166            try:
167                name = self.load_plugin(path)
168                results[name] = None
169            except Exception as e:
170                results[path.stem] = str(e)
171        return results
172
173    def get_plugin(self, name: str) -> BasePlugin | None:
174        """取得插件實例"""
175        loaded = self._plugins.get(name)
176        return loaded.plugin if loaded else None
177
178    def list_plugins(self) -> list[PluginInfo]:
179        """列出所有已載入的插件"""
180        return [lp.plugin.info for lp in self._plugins.values()]
181
182# 範例插件（放在獨立檔案中）
183class GreeterPlugin(BasePlugin):
184    """簡單的問候插件"""
185
186    @property
187    def info(self) -> PluginInfo:
188        return PluginInfo(
189            name="greeter",
190            version="1.0.0",
191            description="A simple greeting plugin"
192        )
193
194    def on_activate(self) -> None:
195        print("Greeter plugin activated!")
196
197    def greet(self, name: str) -> str:
198        return f"Hello, {name}!"
199
200# 使用
201manager = PluginManager(Path("./plugins"))
202manager.load_all_plugins()
203manager.activate_plugin("greeter")
204
205greeter = manager.get_plugin("greeter")
206if isinstance(greeter, GreeterPlugin):
207    print(greeter.greet("World"))

設計考量

安全性

 1# 限制插件可以存取的模組
 2import sys
 3from types import ModuleType
 4
 5class SandboxedImporter:
 6    """限制插件可以 import 的模組"""
 7    ALLOWED_MODULES = {"json", "re", "datetime", "typing"}
 8
 9    def find_module(self, name: str, path=None):
10        if name.split(".")[0] not in self.ALLOWED_MODULES:
11            return self  # 攔截
12        return None
13
14    def load_module(self, name: str) -> ModuleType:
15        raise ImportError(f"Module '{name}' is not allowed in plugins")
16
17# 使用時插入到 sys.meta_path
18# sys.meta_path.insert(0, SandboxedImporter())

版本相容性

 1from packaging import version
 2
 3def check_compatibility(
 4    plugin_info: PluginInfo,
 5    app_version: str
 6) -> bool:
 7    """檢查插件與應用程式版本相容性"""
 8    # 插件可以定義 min_app_version 屬性
 9    min_version = getattr(plugin_info, "min_app_version", "0.0.0")
10    return version.parse(app_version) >= version.parse(min_version)

小結

模式	適用場景
基於繼承	簡單場景，需要型別安全
基於註冊	需要靈活性，支援函式插件
基於發現	自動發現，減少樣板程式碼
entry_points	套件生態系統，第三方插件

思考題

三種插件模式各有什麼優缺點？
如何實現插件之間的依賴管理？
如何確保插件的安全性？

上一章：3.5.3 進階上下文管理 下一章：3.5.5 設計模式整合案例

3.5.5 設計模式整合案例

Tue, 20 Jan 2026 00:00:00 +0000

本章透過兩個完整案例，展示如何將前四章的設計模式結合應用。每個案例都會說明各模式的協作關係。

先備知識

本模組 3.5.1-3.5.4 所有章節

案例一：迷你 ORM 框架

建立一個簡化的 ORM（Object-Relational Mapping）框架，展示各模式的整合。

設計概覽

1┌─────────────────────────────────────────────────────────┐
2│                     MiniORM Framework                    │
3├─────────────────────────────────────────────────────────┤
4│  泛型        │ Repository[T] - 型別安全的資料存取       │
5│  異常        │ 階層式異常 - 精確的錯誤處理              │
6│  上下文      │ Transaction - 交易管理                   │
7│  插件        │ FieldType - 可擴展的欄位型別             │
8└─────────────────────────────────────────────────────────┘

異常層級設計

 1# miniorm/exceptions.py
 2
 3class ORMError(Exception):
 4    """ORM 框架的基礎異常"""
 5
 6    def __init__(self, message: str, code: str | None = None) -> None:
 7        super().__init__(message)
 8        self.message = message
 9        self.code = code
10
11class ConnectionError(ORMError):
12    """資料庫連接錯誤"""
13    pass
14
15class QueryError(ORMError):
16    """查詢執行錯誤"""
17    pass
18
19class EntityNotFoundError(ORMError):
20    """實體不存在"""
21
22    def __init__(self, model: str, pk: int | str) -> None:
23        super().__init__(f"{model} with pk={pk} not found", code="NOT_FOUND")
24        self.model = model
25        self.pk = pk
26
27class ValidationError(ORMError):
28    """資料驗證錯誤"""
29
30    def __init__(self, field: str, message: str) -> None:
31        super().__init__(f"Validation failed for '{field}': {message}", code="VALIDATION")
32        self.field = field
33
34class TransactionError(ORMError):
35    """交易錯誤"""
36    pass

插件系統：可擴展的欄位型別

  1# miniorm/fields.py
  2
  3from abc import ABC, abstractmethod
  4from typing import Any, ClassVar
  5from datetime import datetime
  6
  7class FieldType(ABC):
  8    """欄位型別插件基類"""
  9    _registry: ClassVar[dict[str, type["FieldType"]]] = {}
 10
 11    # 子類別必須定義
 12    type_name: ClassVar[str]
 13    python_type: ClassVar[type]
 14
 15    def __init_subclass__(cls, **kwargs) -> None:
 16        super().__init_subclass__(**kwargs)
 17        if hasattr(cls, "type_name"):
 18            FieldType._registry[cls.type_name] = cls
 19
 20    @abstractmethod
 21    def to_db(self, value: Any) -> Any:
 22        """Python 值轉換為資料庫值"""
 23        ...
 24
 25    @abstractmethod
 26    def from_db(self, value: Any) -> Any:
 27        """資料庫值轉換為 Python 值"""
 28        ...
 29
 30    @abstractmethod
 31    def validate(self, value: Any) -> None:
 32        """驗證值，失敗時拋出 ValidationError"""
 33        ...
 34
 35    @classmethod
 36    def get_type(cls, name: str) -> type["FieldType"] | None:
 37        return cls._registry.get(name)
 38
 39# 內建欄位型別
 40class IntegerField(FieldType):
 41    type_name = "integer"
 42    python_type = int
 43
 44    def to_db(self, value: Any) -> int:
 45        return int(value)
 46
 47    def from_db(self, value: Any) -> int:
 48        return int(value) if value is not None else 0
 49
 50    def validate(self, value: Any) -> None:
 51        if value is not None and not isinstance(value, int):
 52            raise ValidationError("value", f"Expected int, got {type(value).__name__}")
 53
 54class StringField(FieldType):
 55    type_name = "string"
 56    python_type = str
 57
 58    def __init__(self, max_length: int = 255) -> None:
 59        self.max_length = max_length
 60
 61    def to_db(self, value: Any) -> str:
 62        return str(value)
 63
 64    def from_db(self, value: Any) -> str:
 65        return str(value) if value is not None else ""
 66
 67    def validate(self, value: Any) -> None:
 68        if value is not None:
 69            if not isinstance(value, str):
 70                raise ValidationError("value", f"Expected str, got {type(value).__name__}")
 71            if len(value) > self.max_length:
 72                raise ValidationError("value", f"Max length is {self.max_length}")
 73
 74class DateTimeField(FieldType):
 75    type_name = "datetime"
 76    python_type = datetime
 77
 78    def to_db(self, value: Any) -> str:
 79        if isinstance(value, datetime):
 80            return value.isoformat()
 81        return str(value)
 82
 83    def from_db(self, value: Any) -> datetime:
 84        if isinstance(value, datetime):
 85            return value
 86        return datetime.fromisoformat(str(value))
 87
 88    def validate(self, value: Any) -> None:
 89        if value is not None and not isinstance(value, datetime):
 90            raise ValidationError("value", f"Expected datetime, got {type(value).__name__}")
 91
 92# 使用者可以擴展新的欄位型別
 93class JSONField(FieldType):
 94    """自訂欄位型別範例"""
 95    type_name = "json"
 96    python_type = dict
 97
 98    def to_db(self, value: Any) -> str:
 99        import json
100        return json.dumps(value)
101
102    def from_db(self, value: Any) -> dict:
103        import json
104        if isinstance(value, dict):
105            return value
106        return json.loads(str(value))
107
108    def validate(self, value: Any) -> None:
109        if value is not None and not isinstance(value, (dict, list)):
110            raise ValidationError("value", "Expected dict or list")

泛型 Repository

 1# miniorm/repository.py
 2
 3from typing import TypeVar, Generic, Protocol, ClassVar
 4from abc import abstractmethod
 5
 6class HasId(Protocol):
 7    """具有 id 屬性的協議"""
 8    id: int
 9
10T = TypeVar("T", bound=HasId)
11
12class Repository(Generic[T]):
13    """泛型 Repository 基類"""
14
15    model_class: ClassVar[type]
16
17    def __init__(self, connection: "Connection") -> None:
18        self._connection = connection
19
20    @abstractmethod
21    def get(self, pk: int) -> T | None:
22        """根據主鍵取得實體"""
23        ...
24
25    @abstractmethod
26    def save(self, entity: T) -> T:
27        """儲存實體"""
28        ...
29
30    @abstractmethod
31    def delete(self, pk: int) -> bool:
32        """刪除實體"""
33        ...
34
35    @abstractmethod
36    def find_all(self) -> list[T]:
37        """取得所有實體"""
38        ...
39
40    def get_or_raise(self, pk: int) -> T:
41        """取得實體，不存在時拋出異常"""
42        entity = self.get(pk)
43        if entity is None:
44            raise EntityNotFoundError(self.model_class.__name__, pk)
45        return entity
46
47class InMemoryRepository(Repository[T]):
48    """記憶體實作的 Repository"""
49
50    def __init__(self, connection: "Connection") -> None:
51        super().__init__(connection)
52        self._storage: dict[int, T] = {}
53        self._next_id = 1
54
55    def get(self, pk: int) -> T | None:
56        return self._storage.get(pk)
57
58    def save(self, entity: T) -> T:
59        # 驗證欄位
60        self._validate_entity(entity)
61
62        if entity.id == 0:
63            entity.id = self._next_id
64            self._next_id += 1
65        self._storage[entity.id] = entity
66        return entity
67
68    def delete(self, pk: int) -> bool:
69        if pk in self._storage:
70            del self._storage[pk]
71            return True
72        return False
73
74    def find_all(self) -> list[T]:
75        return list(self._storage.values())
76
77    def _validate_entity(self, entity: T) -> None:
78        """驗證實體的所有欄位"""
79        # 這裡可以整合 FieldType 的驗證邏輯
80        pass

上下文管理：交易

 1# miniorm/transaction.py
 2
 3from contextlib import contextmanager
 4from typing import Iterator
 5from dataclasses import dataclass
 6from enum import Enum, auto
 7
 8class TransactionState(Enum):
 9    ACTIVE = auto()
10    COMMITTED = auto()
11    ROLLED_BACK = auto()
12
13@dataclass
14class Transaction:
15    """交易物件"""
16    id: int
17    state: TransactionState = TransactionState.ACTIVE
18    _operations: list = None
19
20    def __post_init__(self):
21        self._operations = []
22
23    def add_operation(self, op: dict) -> None:
24        if self.state != TransactionState.ACTIVE:
25            raise TransactionError("Transaction is not active")
26        self._operations.append(op)
27
28    def commit(self) -> None:
29        if self.state != TransactionState.ACTIVE:
30            raise TransactionError("Transaction is not active")
31        # 實際應用中這裡會提交到資料庫
32        self.state = TransactionState.COMMITTED
33
34    def rollback(self) -> None:
35        if self.state == TransactionState.COMMITTED:
36            raise TransactionError("Cannot rollback committed transaction")
37        # 實際應用中這裡會回滾操作
38        self._operations.clear()
39        self.state = TransactionState.ROLLED_BACK
40
41class Connection:
42    """資料庫連接"""
43
44    def __init__(self, url: str) -> None:
45        self.url = url
46        self._tx_counter = 0
47        self._current_tx: Transaction | None = None
48
49    @contextmanager
50    def transaction(self) -> Iterator[Transaction]:
51        """交易上下文管理器"""
52        if self._current_tx is not None:
53            raise TransactionError("Nested transactions not supported")
54
55        self._tx_counter += 1
56        tx = Transaction(id=self._tx_counter)
57        self._current_tx = tx
58
59        try:
60            yield tx
61            if tx.state == TransactionState.ACTIVE:
62                tx.commit()
63        except Exception:
64            if tx.state == TransactionState.ACTIVE:
65                tx.rollback()
66            raise
67        finally:
68            self._current_tx = None
69
70    @property
71    def in_transaction(self) -> bool:
72        return self._current_tx is not None

整合使用範例

 1# 定義 Model
 2from dataclasses import dataclass, field
 3from datetime import datetime
 4
 5@dataclass
 6class User:
 7    id: int = 0
 8    name: str = ""
 9    email: str = ""
10    created_at: datetime = field(default_factory=datetime.now)
11
12# 定義具體的 Repository
13class UserRepository(InMemoryRepository[User]):
14    model_class = User
15
16# 使用
17def main():
18    # 建立連接
19    conn = Connection("memory://")
20
21    # 建立 Repository
22    users = UserRepository(conn)
23
24    # 使用交易
25    with conn.transaction() as tx:
26        # 建立使用者
27        user = User(name="Alice", email="alice@example.com")
28        users.save(user)
29
30        # 更多操作...
31        user.name = "Alice Smith"
32        users.save(user)
33
34    # 交易外的操作
35    try:
36        found = users.get_or_raise(999)
37    except EntityNotFoundError as e:
38        print(f"Error: {e.message}")
39
40    # 列出所有使用者
41    for user in users.find_all():
42        print(f"User: {user.name} ({user.email})")

案例二：任務排程器

建立一個支援並行執行的任務排程器。

設計概覽

1┌─────────────────────────────────────────────────────────┐
2│                    Task Scheduler                        │
3├─────────────────────────────────────────────────────────┤
4│  泛型        │ Task[T] - 型別安全的任務定義             │
5│  異常        │ ExceptionGroup - 並行錯誤處理            │
6│  上下文      │ TaskContext - 資源生命週期               │
7│  插件        │ TaskHandler - 可擴展的處理器             │
8└─────────────────────────────────────────────────────────┘

異常設計

 1# scheduler/exceptions.py
 2
 3class SchedulerError(Exception):
 4    """排程器基礎異常"""
 5    pass
 6
 7class TaskError(SchedulerError):
 8    """任務執行錯誤"""
 9
10    def __init__(self, task_id: str, message: str, cause: Exception | None = None) -> None:
11        super().__init__(f"Task '{task_id}' failed: {message}")
12        self.task_id = task_id
13        if cause:
14            self.__cause__ = cause
15
16class TimeoutError(TaskError):
17    """任務超時"""
18    pass
19
20class DependencyError(TaskError):
21    """依賴任務失敗"""
22
23    def __init__(self, task_id: str, failed_deps: list[str]) -> None:
24        super().__init__(task_id, f"Dependencies failed: {failed_deps}")
25        self.failed_deps = failed_deps

泛型任務定義

 1# scheduler/task.py
 2
 3from typing import TypeVar, Generic, Callable, Any
 4from dataclasses import dataclass, field
 5from enum import Enum, auto
 6from datetime import datetime
 7
 8T = TypeVar("T")
 9
10class TaskStatus(Enum):
11    PENDING = auto()
12    RUNNING = auto()
13    COMPLETED = auto()
14    FAILED = auto()
15    CANCELLED = auto()
16
17@dataclass
18class TaskResult(Generic[T]):
19    """任務執行結果"""
20    value: T | None = None
21    error: Exception | None = None
22    started_at: datetime | None = None
23    completed_at: datetime | None = None
24
25    @property
26    def success(self) -> bool:
27        return self.error is None
28
29    @property
30    def duration(self) -> float | None:
31        if self.started_at and self.completed_at:
32            return (self.completed_at - self.started_at).total_seconds()
33        return None
34
35@dataclass
36class Task(Generic[T]):
37    """泛型任務"""
38    id: str
39    handler: Callable[["TaskContext"], T]
40    dependencies: list[str] = field(default_factory=list)
41    timeout: float | None = None
42    status: TaskStatus = TaskStatus.PENDING
43    result: TaskResult[T] | None = None
44
45    def execute(self, ctx: "TaskContext") -> TaskResult[T]:
46        """執行任務"""
47        result = TaskResult[T](/python-advanced/03-design-patterns/integration/started_at=datetime.now())
48        self.status = TaskStatus.RUNNING
49
50        try:
51            value = self.handler(ctx)
52            result.value = value
53            self.status = TaskStatus.COMPLETED
54        except Exception as e:
55            result.error = e
56            self.status = TaskStatus.FAILED
57        finally:
58            result.completed_at = datetime.now()
59
60        self.result = result
61        return result

插件系統：任務處理器

 1# scheduler/handlers.py
 2
 3from typing import Any, ClassVar, Protocol
 4from abc import abstractmethod
 5
 6class TaskHandlerProtocol(Protocol):
 7    """任務處理器協議"""
 8
 9    def can_handle(self, task_type: str) -> bool:
10        ...
11
12    def handle(self, ctx: "TaskContext", payload: dict) -> Any:
13        ...
14
15class TaskHandler:
16    """任務處理器基類（基於註冊）"""
17    _registry: ClassVar[dict[str, "TaskHandler"]] = {}
18
19    task_type: ClassVar[str]
20
21    def __init_subclass__(cls, **kwargs) -> None:
22        super().__init_subclass__(**kwargs)
23        if hasattr(cls, "task_type"):
24            TaskHandler._registry[cls.task_type] = cls()
25
26    @abstractmethod
27    def handle(self, ctx: "TaskContext", payload: dict) -> Any:
28        """處理任務"""
29        ...
30
31    @classmethod
32    def get_handler(cls, task_type: str) -> "TaskHandler | None":
33        return cls._registry.get(task_type)
34
35# 具體的處理器
36class HttpRequestHandler(TaskHandler):
37    """HTTP 請求處理器"""
38    task_type = "http_request"
39
40    def handle(self, ctx: "TaskContext", payload: dict) -> dict:
41        import urllib.request
42        url = payload["url"]
43        method = payload.get("method", "GET")
44
45        # 簡化的實作
46        with urllib.request.urlopen(url) as response:
47            return {
48                "status": response.status,
49                "body": response.read().decode()
50            }
51
52class ShellCommandHandler(TaskHandler):
53    """Shell 命令處理器"""
54    task_type = "shell"
55
56    def handle(self, ctx: "TaskContext", payload: dict) -> dict:
57        import subprocess
58        command = payload["command"]
59        timeout = payload.get("timeout", 30)
60
61        result = subprocess.run(
62            command,
63            shell=True,
64            capture_output=True,
65            text=True,
66            timeout=timeout
67        )
68
69        return {
70            "returncode": result.returncode,
71            "stdout": result.stdout,
72            "stderr": result.stderr
73        }
74
75class DataProcessHandler(TaskHandler):
76    """資料處理器"""
77    task_type = "data_process"
78
79    def handle(self, ctx: "TaskContext", payload: dict) -> Any:
80        # 從上下文取得共享資源
81        data = ctx.get_resource("data")
82        operation = payload.get("operation", "identity")
83
84        if operation == "transform":
85            return [item * 2 for item in data]
86        elif operation == "filter":
87            return [item for item in data if item > 0]
88        else:
89            return data

上下文管理：任務上下文

 1# scheduler/context.py
 2
 3from contextlib import contextmanager, ExitStack
 4from typing import Any, Iterator
 5from dataclasses import dataclass, field
 6
 7@dataclass
 8class TaskContext:
 9    """任務執行上下文"""
10    task_id: str
11    _resources: dict[str, Any] = field(default_factory=dict)
12    _cleanup_callbacks: list = field(default_factory=list)
13
14    def set_resource(self, name: str, value: Any) -> None:
15        """設定共享資源"""
16        self._resources[name] = value
17
18    def get_resource(self, name: str) -> Any | None:
19        """取得共享資源"""
20        return self._resources.get(name)
21
22    def add_cleanup(self, callback) -> None:
23        """註冊清理回調"""
24        self._cleanup_callbacks.append(callback)
25
26    def cleanup(self) -> None:
27        """執行所有清理回調"""
28        errors = []
29        for callback in reversed(self._cleanup_callbacks):
30            try:
31                callback()
32            except Exception as e:
33                errors.append(e)
34
35        if errors:
36            raise ExceptionGroup("Cleanup failed", errors)
37
38@contextmanager
39def task_context(task_id: str) -> Iterator[TaskContext]:
40    """任務上下文管理器"""
41    ctx = TaskContext(task_id=task_id)
42
43    try:
44        yield ctx
45    finally:
46        ctx.cleanup()

排程器：整合所有模式

 1# scheduler/scheduler.py
 2
 3import asyncio
 4from typing import Any
 5from dataclasses import dataclass, field
 6
 7@dataclass
 8class Scheduler:
 9    """任務排程器"""
10    _tasks: dict[str, Task] = field(default_factory=dict)
11    _results: dict[str, TaskResult] = field(default_factory=dict)
12
13    def add_task(self, task: Task) -> None:
14        """新增任務"""
15        self._tasks[task.id] = task
16
17    def _get_execution_order(self) -> list[list[str]]:
18        """計算執行順序（拓撲排序）"""
19        # 簡化實作：按依賴深度分層
20        layers: list[list[str]] = []
21        remaining = set(self._tasks.keys())
22        completed: set[str] = set()
23
24        while remaining:
25            # 找出所有依賴已完成的任務
26            ready = [
27                tid for tid in remaining
28                if all(dep in completed for dep in self._tasks[tid].dependencies)
29            ]
30
31            if not ready:
32                # 有循環依賴
33                raise SchedulerError(f"Circular dependency detected: {remaining}")
34
35            layers.append(ready)
36            for tid in ready:
37                remaining.remove(tid)
38                completed.add(tid)
39
40        return layers
41
42    async def run_async(self) -> dict[str, TaskResult]:
43        """非同步執行所有任務"""
44        layers = self._get_execution_order()
45
46        for layer in layers:
47            # 同一層的任務可以並行執行
48            tasks_to_run = []
49
50            for task_id in layer:
51                task = self._tasks[task_id]
52
53                # 檢查依賴是否成功
54                failed_deps = [
55                    dep for dep in task.dependencies
56                    if dep in self._results and not self._results[dep].success
57                ]
58
59                if failed_deps:
60                    # 依賴失敗，跳過此任務
61                    result = TaskResult(
62                        error=DependencyError(task_id, failed_deps)
63                    )
64                    self._results[task_id] = result
65                    continue
66
67                tasks_to_run.append(self._run_task_async(task))
68
69            # 並行執行，收集所有錯誤
70            if tasks_to_run:
71                try:
72                    async with asyncio.TaskGroup() as tg:
73                        for coro in tasks_to_run:
74                            tg.create_task(coro)
75                except* TaskError as eg:
76                    # 記錄錯誤但繼續執行
77                    for e in eg.exceptions:
78                        print(f"Task failed: {e}")
79
80        return self._results
81
82    async def _run_task_async(self, task: Task) -> None:
83        """執行單個任務"""
84        with task_context(task.id) as ctx:
85            # 設定共享資源（從依賴任務的結果）
86            for dep_id in task.dependencies:
87                if dep_id in self._results:
88                    ctx.set_resource(f"result_{dep_id}", self._results[dep_id].value)
89
90            result = task.execute(ctx)
91            self._results[task.id] = result
92
93            if result.error:
94                raise TaskError(task.id, str(result.error), result.error)
95
96    def run(self) -> dict[str, TaskResult]:
97        """同步執行"""
98        return asyncio.run(self.run_async())

完整使用範例

 1# 建立排程器
 2scheduler = Scheduler()
 3
 4# 定義任務
 5def fetch_data(ctx: TaskContext) -> list[int]:
 6    """模擬取得資料"""
 7    return [1, 2, 3, 4, 5]
 8
 9def process_data(ctx: TaskContext) -> list[int]:
10    """處理資料"""
11    data = ctx.get_resource("result_fetch")
12    return [x * 2 for x in data]
13
14def save_result(ctx: TaskContext) -> str:
15    """儲存結果"""
16    data = ctx.get_resource("result_process")
17    return f"Saved {len(data)} items"
18
19# 新增任務（有依賴關係）
20scheduler.add_task(Task(
21    id="fetch",
22    handler=fetch_data
23))
24
25scheduler.add_task(Task(
26    id="process",
27    handler=process_data,
28    dependencies=["fetch"]
29))
30
31scheduler.add_task(Task(
32    id="save",
33    handler=save_result,
34    dependencies=["process"]
35))
36
37# 執行
38results = scheduler.run()
39
40# 檢查結果
41for task_id, result in results.items():
42    if result.success:
43        print(f"[OK] {task_id}: {result.value} ({result.duration:.3f}s)")
44    else:
45        print(f"[FAIL] {task_id}: {result.error}")

模式協作關係圖

 1┌─────────────────────────────────────────────────────────────────┐
 2│                         應用程式                                 │
 3├─────────────────────────────────────────────────────────────────┤
 4│                                                                  │
 5│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
 6│   │   泛型      │────▶│   異常      │────▶│   上下文    │       │
 7│   │ Repository  │     │ 層級設計    │     │ Transaction │       │
 8│   │ Task[T]     │     │ 異常鏈      │     │ TaskContext │       │
 9│   └─────────────┘     └─────────────┘     └─────────────┘       │
10│          │                   │                   │               │
11│          │                   │                   │               │
12│          ▼                   ▼                   ▼               │
13│   ┌─────────────────────────────────────────────────────┐       │
14│   │                      插件系統                        │       │
15│   │  FieldType  │  TaskHandler  │  HookPlugin          │       │
16│   └─────────────────────────────────────────────────────┘       │
17│                                                                  │
18└─────────────────────────────────────────────────────────────────┘
19
20協作方式：
211. 泛型確保型別安全，在編譯期捕獲錯誤
222. 異常提供精確的錯誤處理，支援錯誤傳播和轉換
233. 上下文管理資源生命週期，確保正確清理
244. 插件系統提供擴展點，允許自訂行為

設計原則總結

模式	解決的問題	使用時機
泛型	型別安全的重用	容器、Repository、服務介面
異常層級	精確的錯誤處理	大型專案、API 設計
上下文管理	資源生命週期	連接、交易、臨時資源
插件系統	可擴展性	框架設計、開放式架構

思考題

如何在這些案例中加入日誌記錄？
如果要支援分散式執行，需要修改哪些部分？
如何為這些框架加入效能監控？

上一章：3.5.4 插件系統設計 回到模組目錄：模組 3.5：進階設計模式

3.5.6 軟體設計的取捨藝術

Wed, 04 Mar 2026 00:00:00 +0000

前五章介紹了泛型、異常設計、上下文管理、插件系統等進階設計模式。但在真實專案中，最困難的往往不是「如何實作」，而是「該不該這樣做」。本章從英文技術社群的經驗中提煉出實用的取捨決策框架，幫助你在面對兩難時做出更好的判斷。

先備知識

本模組 3.5.1-3.5.5 所有章節
入門系列模組四：物件導向設計

為什麼取捨不可避免？

Stack Overflow 的技術部落格曾發表一篇文章 Plan for Tradeoffs，核心論點是：你無法同時最佳化所有軟體品質屬性。

該文列出了 17 項核心品質屬性，包含可用性、效能、安全性、可維護性、可移植性等。它們之間存在天然的衝突：

安全性 vs 易用性：多因素驗證提高了安全性，但增加了使用步驟
可重用性 vs 效率：泛用型元件的效能不如針對特定場景最佳化的程式碼
效能 vs 可移植性：平台特定的最佳化降低了跨平台能力

取捨是軟體開發的數學本質，跟工程師能力無關。每個設計決策都在一個多維空間中選擇一個點，無法讓每個維度都處於最佳值。

Python 的哲學立場

Python 的設計者 Tim Peters 在 PEP 20 – The Zen of Python 中早已預見了這個問題，其中幾條格言直接反映了取捨思維：

1Simple is better than complex.
2Complex is better than complicated.
3Special cases aren't special enough to break the rules.
4Although practicality beats purity.

「Although practicality beats purity」（務實勝於純粹）是整個 Python 設計哲學的關鍵。它承認完美方案不存在，鼓勵工程師在原則和現實之間找到平衡。

六個核心取捨維度

從業界經驗中，我們可以歸納出六個最常見的取捨維度。

維度一：重複 vs 錯誤抽象

這是軟體設計中最經典的取捨之一，近年來因為 Sandi Metz 的 “The Wrong Abstraction” 和 Kent C. Dodds 的 AHA Programming 而被重新審視。

傳統觀點 – DRY（Don’t Repeat Yourself）

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

DRY 原則要求消除所有重複。這在很多情況下是正確的，但當它成為教條時，工程師會為了消除表面上的重複而建立過度複雜的抽象。

反思觀點 – AHA（Avoid Hasty Abstractions）

Kent C. Dodds 提出了 AHA 程式設計的概念：不要急於抽象，等到模式自然浮現。核心洞察是：

重複的程式碼容易在之後重構
但錯誤的抽象拆除起來痛苦得多

Sandi Metz 的名言精準地總結了這個觀點：

“Duplication is far cheaper than the wrong abstraction.”

（重複的成本遠低於錯誤抽象的成本。）

錯誤抽象的演化過程

Metz 描述了一個在真實專案中反覆出現的模式：

工程師發現兩段重複程式碼，提取出抽象
新需求出現，幾乎但不完全符合現有抽象
後繼者加入參數和條件分支來適應新需求
更多變體出現，更多條件被加入
抽象變得難以理解，但沒人敢重寫（沉沒成本謬誤）
所有人都害怕這段程式碼

Python 實際案例

 1# 階段 1：發現重複，提取函式
 2def process_user_data(data: dict) -> dict:
 3    """最初只處理使用者資料"""
 4    validated = validate_fields(data)
 5    normalized = normalize_strings(validated)
 6    return save_to_db(normalized)
 7
 8# 階段 2：「訂單資料也差不多嘛」，加入參數
 9def process_data(data: dict, data_type: str = "user") -> dict:
10    validated = validate_fields(data)
11    normalized = normalize_strings(validated)
12    if data_type == "order":
13        normalized = calculate_totals(normalized)
14    return save_to_db(normalized)
15
16# 階段 3：更多類型，更多分支
17def process_data(
18    data: dict,
19    data_type: str = "user",
20    skip_validation: bool = False,
21    custom_normalizer: Callable | None = None,
22    dry_run: bool = False,
23) -> dict:
24    if not skip_validation:
25        validated = validate_fields(data, strict=(data_type == "payment"))
26    else:
27        validated = data
28
29    if custom_normalizer:
30        normalized = custom_normalizer(validated)
31    else:
32        normalized = normalize_strings(validated)
33
34    if data_type == "order":
35        normalized = calculate_totals(normalized)
36    elif data_type == "payment":
37        normalized = encrypt_sensitive(normalized)
38    elif data_type == "inventory":
39        normalized = check_stock_levels(normalized)
40
41    if dry_run:
42        return normalized
43    return save_to_db(normalized, table=TABLE_MAP[data_type])

到了階段 3，這個函式已經違反了單一職責原則，而且任何修改都可能影響所有資料類型的處理。

更好的做法：讓每個資料類型擁有自己的處理流程

 1from abc import ABC, abstractmethod
 2
 3class DataProcessor(ABC):
 4    """定義處理流程的骨架，但不強制共用邏輯"""
 5
 6    @abstractmethod
 7    def validate(self, data: dict) -> dict: ...
 8
 9    @abstractmethod
10    def normalize(self, data: dict) -> dict: ...
11
12    @abstractmethod
13    def save(self, data: dict) -> dict: ...
14
15    def process(self, data: dict) -> dict:
16        validated = self.validate(data)
17        normalized = self.normalize(validated)
18        return self.save(normalized)
19
20class UserDataProcessor(DataProcessor):
21    def validate(self, data: dict) -> dict:
22        return validate_fields(data)
23
24    def normalize(self, data: dict) -> dict:
25        return normalize_strings(data)
26
27    def save(self, data: dict) -> dict:
28        return save_to_db(data, table="users")
29
30class PaymentDataProcessor(DataProcessor):
31    def validate(self, data: dict) -> dict:
32        return validate_fields(data, strict=True)
33
34    def normalize(self, data: dict) -> dict:
35        normalized = normalize_strings(data)
36        return encrypt_sensitive(normalized)
37
38    def save(self, data: dict) -> dict:
39        return save_to_db(data, table="payments")

注意：UserDataProcessor 和 PaymentDataProcessor 的 validate 方法有些重複（都呼叫 validate_fields），但這是可接受的重複。每個處理器獨立演化，不會因為支付系統的新需求而影響用戶資料的處理。

決策指引

情境	建議
兩段程式碼目前看起來一樣	先保持重複，觀察是否真的有共同的演化方向
三處以上相同且穩定不變	提取抽象，但保持介面簡單
現有抽象開始出現 `if type == ...`	考慮拆回獨立實作
修改一處總是需要同時修改抽象的其他使用者	抽象方向錯了，回到重複再重新評估

維度二：效能 vs 可讀性

Python 社群有一句話經常被引用：

“Premature optimization is the root of all evil.” – Donald Knuth

但完整的引用其實是：

“We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%.”

這段話包含了兩個同樣重要的訊息：97% 的時候不要優化，但那關鍵的 3% 不能錯過。

Python 的定位

Python 的設計選擇（動態型別、簡潔語法、豐富的標準庫）大幅降低了開發時間。Dev.to 上的一篇分析指出，效能不僅用 CPU 週期衡量，也用 time-to-solution 衡量。程式碼可能在 0.5 秒內執行完畢，但如果需要三天來撰寫和除錯，你損失的生產力可能超過執行速度帶來的收益。

Python 中效能與可讀性的典型衝突

 1# 可讀版本：清楚表達意圖
 2def find_active_premium_users(users: list[User]) -> list[User]:
 3    """找出活躍的付費用戶"""
 4    active_users = [u for u in users if u.is_active]
 5    premium_users = [u for u in active_users if u.plan == "premium"]
 6    recent_users = [u for u in premium_users if u.last_login > cutoff_date]
 7    return recent_users
 8
 9# 效能版本：單次遍歷，但意圖較不明顯
10def find_active_premium_users(users: list[User]) -> list[User]:
11    """找出活躍的付費用戶"""
12    return [
13        u for u in users
14        if u.is_active
15        and u.plan == "premium"
16        and u.last_login > cutoff_date
17    ]
18
19# 極致效能版本：犧牲可讀性
20def find_active_premium_users(users: list[User]) -> list[User]:
21    _is = True.__eq__  # 避免屬性查找
22    _pr = "premium".__eq__
23    _dt = cutoff_date
24    return [u for u in users if _is(u.is_active) and _pr(u.plan) and u.last_login > _dt]

在這個例子中，第一個版本建立了三個中間列表，但最清楚；第二個版本是合理的平衡；第三個版本的微優化在 99% 的場景中毫無意義，卻犧牲了所有可讀性。

決策框架：何時該優化？

 1# 決策流程（虛擬碼）
 2def should_optimize(code_section) -> str:
 3    # 步驟 1：有實際效能問題嗎？
 4    if not is_performance_bottleneck(code_section):
 5        return "維持可讀版本"
 6
 7    # 步驟 2：瓶頸在這裡嗎？
 8    profiling_result = profile(code_section)
 9    if profiling_result.time_percentage < 5:
10        return "瓶頸不在這裡，維持可讀版本"
11
12    # 步驟 3：有不犧牲可讀性的優化方案嗎？
13    if can_use_better_algorithm():
14        return "換演算法（通常不影響可讀性）"
15
16    if can_use_better_data_structure():
17        return "換資料結構（通常不影響可讀性）"
18
19    # 步驟 4：真的需要犧牲可讀性
20    return "優化，但加上詳細註解說明為什麼"

資料結構選擇的隱性取捨

 1# 場景：頻繁的成員檢查
 2
 3# list -- O(n) 查找，但保留順序、允許重複
 4users_list: list[str] = ["alice", "bob", "charlie"]
 5if "alice" in users_list:  # 線性掃描
 6    pass
 7
 8# set -- O(1) 查找，但不保留順序、不允許重複
 9users_set: set[str] = {"alice", "bob", "charlie"}
10if "alice" in users_set:  # 雜湊查找
11    pass
12
13# 取捨考量：
14# - 集合 < 100 個元素：差異可忽略，選擇語義更清楚的
15# - 集合 > 10000 個元素且頻繁查找：set 是明確的選擇
16# - 需要保留順序 + 快速查找：dict.fromkeys() 或 OrderedDict

維度三：Build vs Buy

這是影響範圍最大的取捨之一。Antoine Sauvinet 在 Build vs Buy in 2026 中指出，67% 的軟體專案失敗源於錯誤的 build vs buy 決策（引用 Forrester 研究）。

核心判斷原則：這是你的競爭優勢嗎？

如果你正在建造的東西能在市場上區隔你和競爭者，那值得自建。否則，不要重新發明輪子。

這個原則被稱為 NIH 症候群（Not Invented Here Syndrome）的解藥。一篇分析 Hacker News 上的 build vs buy 失敗經驗後發現，最常見的錯誤是：

低估了維護自建方案的長期成本
高估了「我們的需求很特殊」的程度
忽略了開源社群數百位貢獻者的累積優勢

Python 生態系統的案例

 1# 反面案例：自建 HTTP 請求函式庫
 2# 「我們只需要 GET 和 POST，寫一個很簡單」
 3import socket
 4
 5def simple_get(url: str) -> str:
 6    # 解析 URL、建立 socket、處理 SSL、
 7    # 處理重導向、處理分塊傳輸、處理超時...
 8    # 三個月後，你重新實作了 requests 的 30%
 9    # 但缺少了 cookie 管理、連接池、代理支援...
10    pass
11
12# 正確做法：用 requests 或 httpx
13import httpx
14
15response = httpx.get("https://api.example.com/data")

 1# 合理的自建案例：核心業務邏輯的定價引擎
 2# 這是你的競爭優勢，沒有通用方案能完全符合
 3class PricingEngine:
 4    """公司專有的定價策略，包含多年的業務經驗"""
 5
 6    def calculate(self, product: Product, customer: Customer) -> Price:
 7        base = self._base_price(product)
 8        adjusted = self._apply_customer_tier(base, customer)
 9        seasonal = self._seasonal_adjustment(adjusted)
10        return self._apply_regulatory_constraints(seasonal)

決策矩陣

因素	傾向自建	傾向採用
核心競爭力	是你的差異化所在	是基礎設施
團隊能力	有相關領域專家	需要從零學習
維護預算	有長期維護資源	只需要「能用就好」
特殊需求	市面方案無法滿足 > 70% 需求	市面方案滿足 > 80% 需求
時間壓力	可以投入 3+ 個月	需要在數週內交付

維度四：快速失敗 vs 預先驗證

Fail Fast 原則

DZone 上的文章 The Fail-Fast Principle in Software Development 指出：fail-fast 系統在遇到非預期狀態時立即停止，而不是嘗試繼續執行可能產生不正確結果的操作。

Enterprise Craftsmanship 的部落格進一步說明：因為 fail-fast 程式碼在第一時間就失敗了，回報的錯誤或例外通常非常接近實際的根因，大幅減少了除錯時間。

Python 中的 Fail Fast

1# Fail Fast 風格：立即驗證，立即失敗
2def transfer_money(from_account: str, to_account: str, amount: Decimal) -> None:
3    if amount <= 0:
4        raise ValueError(f"轉帳金額必須為正數，收到: {amount}")
5    if from_account == to_account:
6        raise ValueError("不能轉帳給自己")
7    # ... 執行轉帳

 1# 預先驗證風格：收集所有錯誤後一次回報
 2def transfer_money(from_account: str, to_account: str, amount: Decimal) -> None:
 3    errors: list[str] = []
 4    if amount <= 0:
 5        errors.append(f"轉帳金額必須為正數，收到: {amount}")
 6    if from_account == to_account:
 7        errors.append("不能轉帳給自己")
 8    if not account_exists(from_account):
 9        errors.append(f"來源帳戶不存在: {from_account}")
10    if not account_exists(to_account):
11        errors.append(f"目標帳戶不存在: {to_account}")
12
13    if errors:
14        raise ValidationError(errors)
15    # ... 執行轉帳

何時用哪種？

場景	建議策略	理由
程式內部邏輯	Fail Fast	不應該出現的狀態要立即暴露
API 請求驗證	預先驗證	使用者需要一次看到所有錯誤
資料管線	Fail Fast + 重試	單筆失敗不應阻塞整個管線
表單提交	預先驗證	UX 考量：使用者不想重複提交
系統啟動	Fail Fast	配置錯誤要在啟動時就發現

Python 的 assert 是 Fail Fast 的工具（但有限制）

1def process_batch(items: list[Item]) -> list[Result]:
2    # assert 適合標記「這裡不應該發生」的情況
3    assert items, "process_batch 不應該收到空列表"
4
5    # 但注意：python -O 會移除所有 assert
6    # 所以不要用 assert 做業務驗證
7    # 以下是錯誤用法：
8    assert user.is_authenticated, "使用者未登入"  # 不要這樣做

維度五：嚴格型別 vs 靈活鴨子型別

Python 同時支援靜態型別提示和動態鴨子型別，這在其他語言中比較少見。

 1from typing import Protocol
 2
 3# 方案 A：嚴格的型別定義
 4class Serializable(Protocol):
 5    def to_dict(self) -> dict: ...
 6    def from_dict(cls, data: dict) -> "Serializable": ...
 7
 8def save_strict(obj: Serializable) -> None:
 9    data = obj.to_dict()
10    # ... 儲存
11
12# 方案 B：鴨子型別，依賴約定
13def save_flexible(obj: object) -> None:
14    if not hasattr(obj, "to_dict"):
15        raise TypeError(f"{type(obj).__name__} 缺少 to_dict 方法")
16    data = obj.to_dict()  # type: ignore
17    # ... 儲存
18
19# 方案 C：Protocol 的平衡點（推薦）
20# Protocol 提供靜態檢查，但不要求繼承
21class Persistable(Protocol):
22    def to_dict(self) -> dict: ...
23
24def save_balanced(obj: Persistable) -> None:
25    data = obj.to_dict()
26    # ... 儲存
27
28# 任何有 to_dict 方法的類別都自動滿足 Persistable
29# 不需要顯式繼承，保留了鴨子型別的靈活性
30class User:
31    def to_dict(self) -> dict:
32        return {"name": self.name}
33
34save_balanced(User())  # mypy 檢查通過，無需繼承

決策指引

專案特性	建議
團隊 > 5 人	傾向嚴格型別，降低溝通成本
快速原型	鴨子型別，快速迭代
長期維護的框架	Protocol（平衡點）
資料管線/ETL	嚴格型別，錯誤代價高
個人腳本	鴨子型別，效率優先

維度六：技術債務的策略性管理

Oskar Dudycz 在 Architecture Weekly 上發表了一篇引人深思的文章 Tech Debt Doesn’t Exist, But Trade-offs Do。他認為「技術債務」這個標籤讓我們可以承認問題的存在而不去解決它。他主張用「取捨」取代「債務」的思維：

說「我們有技術債」是一種藉口。真正的問題是：「我們當時做了什麼取捨，現在的代價是什麼？」

策略性技術債務 vs 魯莽的技術債務

 1# 策略性技術債務：有意識地選擇，有計畫地償還
 2# 場景：MVP 需要在兩週內上線驗證市場
 3
 4# 目前的實作：直接用 JSON 檔案儲存
 5# 取捨決策：放棄資料庫，節省 3 天開發時間
 6# 償還計畫：驗證成功後第二個 sprint 遷移到 PostgreSQL
 7import json
 8from pathlib import Path
 9
10# TRADE-OFF: 使用 JSON 檔案而非資料庫
11# 原因: MVP 階段，使用者 < 100 人，讀寫頻率低
12# 風險: 無並行安全、無交易支援、效能隨資料量線性下降
13# 償還條件: 使用者 > 50 或資料 > 10MB 時遷移
14DATA_FILE = Path("data/users.json")
15
16def save_user(user: dict) -> None:
17    data = json.loads(DATA_FILE.read_text()) if DATA_FILE.exists() else []
18    data.append(user)
19    DATA_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2))

 1# 魯莽的技術債務：沒有意識到代價
 2# 場景：「先讓它動起來再說」
 3def handle_request(req):
 4    try:
 5        # 100 行沒有型別提示、沒有錯誤處理、沒有測試的程式碼
 6        data = req["data"]  # 可能是 None
 7        result = process(data)  # process 可能拋出任何異常
 8        db.save(result)  # 沒有交易管理
 9        return {"ok": True}
10    except:  # 裸 except：吞掉所有錯誤
11        return {"ok": False}

關鍵區別：策略性債務是有意識的取捨，附帶償還計畫和觸發條件。魯莽的債務是無意識的品質下降。

決策框架：面對取捨的系統性方法

綜合上述六個維度的經驗，以下是一個通用的取捨決策框架。

三步決策法

步驟一：辨識取捨的存在

很多時候，工程師沒有意識到自己正在做取捨。以下信號表明你正面對一個取捨決策：

「兩種做法各有優缺點」
「如果我們選 A，就會失去 B」
團隊成員對同一個問題有不同偏好
解決方案中出現了 “it depends”

步驟二：量化代價

不要用直覺判斷，盡量量化每個選項的代價：

 1# 取捨評估模板
 2class TradeoffEvaluation:
 3    """用結構化方式記錄取捨決策"""
 4
 5    def __init__(self, decision: str):
 6        self.decision = decision
 7        self.options: list[dict] = []
 8
 9    def add_option(
10        self,
11        name: str,
12        benefits: list[str],
13        costs: list[str],
14        risks: list[str],
15        reversibility: str,  # "easy" | "moderate" | "difficult"
16    ) -> None:
17        self.options.append({
18            "name": name,
19            "benefits": benefits,
20            "costs": costs,
21            "risks": risks,
22            "reversibility": reversibility,
23        })
24
25    def evaluate(self) -> str:
26        """產出決策摘要"""
27        lines = [f"## 決策: {self.decision}\n"]
28        for opt in self.options:
29            lines.append(f"### 方案: {opt['name']}")
30            lines.append(f"- 可逆性: {opt['reversibility']}")
31            lines.append(f"- 優點: {', '.join(opt['benefits'])}")
32            lines.append(f"- 代價: {', '.join(opt['costs'])}")
33            lines.append(f"- 風險: {', '.join(opt['risks'])}")
34            lines.append("")
35        return "\n".join(lines)

步驟三：偏好可逆的決策

Amazon 的 Jeff Bezos 將決策分為兩類：

Type 1 決策（單向門）：不可逆，需要深思熟慮。例如選擇程式語言、資料庫架構。
Type 2 決策（雙向門）：可逆，應該快速做出。例如 API 命名、函式拆分方式。

 1# Type 2 決策：函式簽名可以之後改
 2# 先用簡單版本，有需要再擴展
 3def send_notification(user_id: str, message: str) -> bool:
 4    """現在只支援 email，之後可以擴展"""
 5    return send_email(user_id, message)
 6
 7# 之後需要時再擴展，改動成本很低
 8def send_notification(
 9    user_id: str,
10    message: str,
11    channel: str = "email",
12) -> bool:
13    """支援多種通知管道"""
14    sender = CHANNEL_MAP[channel]
15    return sender(user_id, message)

 1# Type 1 決策：資料庫 schema 設計
 2# 上線後很難改，需要仔細評估
 3
 4# 決策記錄（Architecture Decision Record）
 5# ADR-007: 使用者地址儲存方式
 6#
 7# 狀態: 已採納
 8# 日期: 2026-03-01
 9#
10# 背景:
11#   使用者可能有多個地址（家、公司、寄送地址）
12#
13# 考慮的方案:
14#   A. JSON 欄位：靈活但難以查詢和索引
15#   B. 獨立 address 表：標準化但查詢需要 JOIN
16#   C. 嵌入式欄位（home_addr, work_addr）：簡單但不可擴展
17#
18# 決策: 方案 B（獨立表）
19# 理由: 地址需要獨立查詢（物流系統需求），
20#        且未來可能增加地址類型

可逆性評估表

決策類型	可逆性	建議決策速度
變數/函式命名	高（全域替換）	秒級
模組拆分方式	中（需要重構）	分鐘級
API 介面設計	低（外部依賴）	小時級
資料庫 schema	很低（資料遷移）	天級
程式語言選擇	極低（全部重寫）	週級

經典案例研究

案例一：Food-Tech 新創的技術債務危機

一家 Food-Tech 新創公司在六個月內推出了 MVP，快速獲得了數千名用戶和可觀的投資。但開發團隊為了搶市場，犧牲了文件、測試和可擴展的架構。

一次特別糟糕的產品發布導致了嚴重的停機和大量客戶投訴。CTO 終於意識到，短期搶快的收益已經被長期的不穩定和效率低下所抵消。

教訓：這是一個策略性債務失控的例子。初始的取捨（速度優先）是合理的，但缺少了「償還計畫」和「觸發條件」。如果團隊在 MVP 驗證成功後立即投入技術債務償還，結果會完全不同。

來源：Medium - Technical Debt vs. Innovation

案例二：可觀測性的成本爆炸

Honeycomb 的工程部落格描述了可觀測性工具面臨的成本危機：微服務架構產生的日誌、指標和追蹤資料量呈指數成長，但大部分資料從未被查看。

典型的取捨是取樣率：10% 的取樣可以大幅降低成本，但可能錯過關鍵的請求。

業界的解決方案：

 1# 概念示意：基於重要性的取樣策略
 2import random
 3
 4# 不是所有請求都值得完整記錄
 5SAMPLING_RULES = {
 6    "health_check": 0.001,    # 0.1% -- 幾乎不需要
 7    "static_asset": 0.01,     # 1% -- 很少出問題
 8    "api_read": 0.1,          # 10% -- 標準取樣
 9    "api_write": 0.5,         # 50% -- 寫入操作更重要
10    "payment": 1.0,           # 100% -- 永遠完整記錄
11    "error": 1.0,             # 100% -- 錯誤永遠記錄
12}
13
14def should_sample(request_type: str) -> bool:
15    rate = SAMPLING_RULES.get(request_type, 0.1)
16    return random.random() < rate

來源：Honeycomb - The Cost Crisis in Observability Tooling

案例三：B2B 企業的 4 億美元技術債

McKinsey 報導了一家大型 B2B 企業的案例：他們識別出了數十個現代化計畫，可以帶來 20 億美元的利潤提升，但其中 70% 的計畫依賴的技術需要 4 億美元的投入來償還多年累積的技術債務。

教訓：技術債務的成本不是線性的。每一次「之後再處理」都會增加下一次修改的難度。當債務累積到一定程度，甚至連修改的機會成本都變成天文數字。

來源：McKinsey - Breaking Technical Debt’s Vicious Cycle

Python 特有的取捨考量

“There should be one obvious way to do it” vs 現實

The Zen of Python 說：

1There should be one-- and preferably only one --obvious way to do it.

但在實際的 Python 開發中，你經常面對多種方案的選擇：

 1# 格式化字串：三種方式
 2name = "World"
 3
 4# % 格式化（最老，但 logging 模組仍在用）
 5message = "Hello, %s" % name
 6
 7# str.format()（Python 2.6+，某些場景更靈活）
 8message = "Hello, {}".format(name)
 9
10# f-string（Python 3.6+，通常是最佳選擇）
11message = f"Hello, {name}"

 1# 合併字典：多種方式
 2dict_a = {"a": 1}
 3dict_b = {"b": 2}
 4
 5# 方式 1：update（原地修改）
 6merged = dict_a.copy()
 7merged.update(dict_b)
 8
 9# 方式 2：解包（Python 3.5+，建立新字典）
10merged = {**dict_a, **dict_b}
11
12# 方式 3：聯集運算子（Python 3.9+，最 Pythonic）
13merged = dict_a | dict_b

如何選擇？ 優先考慮：

團隊共識 – 統一比「最佳」更重要
Python 版本相容性 – 如果要支援 3.8，就不能用 |
語境適合度 – logging 中用 % 是慣例，不需要改成 f-string

型別提示的漸進策略

 1# 階段 1：不加型別提示（快速原型）
 2def process(data):
 3    return [item["name"] for item in data if item.get("active")]
 4
 5# 階段 2：關鍵介面加型別提示（公開 API）
 6def process(data: list[dict[str, Any]]) -> list[str]:
 7    return [item["name"] for item in data if item.get("active")]
 8
 9# 階段 3：完整型別定義（長期維護）
10from dataclasses import dataclass
11
12@dataclass
13class Item:
14    name: str
15    active: bool = True
16
17def process(data: list[Item]) -> list[str]:
18    return [item.name for item in data if item.active]

每個階段都是合理的，關鍵在於根據專案的生命週期選擇正確的階段。個人腳本停在階段 1 完全合理；團隊共同維護的服務應該至少在階段 2；核心業務邏輯應該達到階段 3。

EAFP vs LBYL

Python 社群有兩種錯誤處理哲學：

 1# LBYL (Look Before You Leap) -- 先檢查再行動
 2def get_value_lbyl(data: dict, key: str) -> str | None:
 3    if key in data:
 4        value = data[key]
 5        if isinstance(value, str):
 6            return value
 7    return None
 8
 9# EAFP (Easier to Ask Forgiveness than Permission) -- 先嘗試再處理異常
10def get_value_eafp(data: dict, key: str) -> str | None:
11    try:
12        value = data[key]
13        if not isinstance(value, str):
14            return None
15        return value
16    except KeyError:
17        return None

因素	LBYL	EAFP
Race condition	檢查和使用之間狀態可能改變	原子操作，無此問題
效能（正常路徑）	額外的檢查開銷	無額外開銷
效能（異常路徑）	無額外開銷	例外處理有成本
可讀性	意圖明確	需要理解例外流程
Python 慣例	較少使用	更 Pythonic

實用建議：如果異常是真正的「例外情況」（發生率 < 5%），EAFP 通常更好。如果「異常」其實是常見情況（例如字典中 30% 的 key 不存在），LBYL 的效能更好。

取捨決策清單

面對需要做取捨的設計決策時，依序確認以下項目：

決策前

我是否辨識出了取捨的存在？（不是只有一個「正確答案」）
我列出了至少兩個可行方案嗎？
每個方案的優點、代價和風險都有記錄嗎？
這個決策的可逆性如何？（Type 1 還是 Type 2？）
有沒有可以參考的業界經驗或先例？

評估中

我是否量化了代價，而不只是用直覺判斷？
我有沒有考慮到長期維護成本？
團隊其他成員的意見是什麼？
最壞的情況是什麼？我們能承受嗎？
有沒有第三個方案是我忽略的？

決策後

決策理由有記錄嗎？（ADR 或程式碼註解）
取捨的代價有告知相關人員嗎？
如果是策略性技術債務，償還計畫和觸發條件是什麼？
什麼條件下需要重新評估這個決策？

本章重點整理

核心觀念

取捨是軟體工程的本質，不是能力不足的表現
「務實勝於純粹」– Python 的設計哲學本身就是取捨的產物
錯誤的抽象比重複更昂貴（Sandi Metz）
不要急於抽象，等模式自然浮現（AHA Programming）
優先做可逆的決策，謹慎對待不可逆的決策

實用原則

效能優化前先量測，97% 的時候可讀性優先
只有核心競爭力才值得自建
策略性技術債務需要「償還計畫」和「觸發條件」
型別提示的嚴格程度應匹配專案的生命週期
決策理由比決策本身更值得記錄

案例研究：設計模式實戰

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

本系列案例基於 .claude/lib 的實際程式碼，展示如何用進階設計模式解決實際問題。

案例列表

案例	素材	進階技術	難度
快取生命週期管理	config_loader.py	Context Manager	中階
插件架構設計	hook_validator.py	Protocol + 註冊機制	高階
異常設計架構	hook_io.py	異常階層 + ExceptionGroup	中階
泛型驗證器	hook_validator.py	Generic + TypeVar	高階

學習路徑

1快取生命週期管理（入門）
2 ↓
3異常設計架構（基礎）
4 ↓
5插件架構設計（進階）
6 ↓
7泛型驗證器（整合）

先備知識

建議先完成以下章節：

返回：模組三：進階設計模式