案例研究：設計模式實戰 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 管理快取？

適合使用：

案例：插件架構設計

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

延伸閱讀

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

案例：異常設計架構

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

延伸閱讀

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

案例：泛型驗證器

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：進階設計模式

案例研究：設計模式實戰 on Tarragon

案例：快取生命週期管理

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

問題 1：測試難以隔離

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

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

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

設計目標

實作步驟

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

步驟 2：加入 Context Manager 支援

步驟 3：加入便利方法

完整程式碼

使用範例

基本使用

測試中使用

相容舊 API

設計權衡

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

案例：插件架構設計

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

進階解決方案

設計目標

實作步驟

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

為什麼用 Protocol 而不是 ABC？

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

步驟 3：支援 entry_points 自動發現

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

完整程式碼

使用範例

建立插件

註冊插件

使用 entry_points

設計權衡

什麼時候該用這個技術？

練習

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

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

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

延伸閱讀

案例：異常設計架構

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

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

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

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

進階解決方案

設計目標

實作步驟

步驟 1：設計異常階層

步驟 2：豐富的錯誤資訊

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

步驟 4：錯誤恢復策略

完整程式碼

使用範例

基本使用

多重錯誤處理

異常鏈（Exception Chaining）

設計權衡

何時使用哪種方案？

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

使用自定義階層

使用 ExceptionGroup

什麼時候該用這個技術？

練習

基礎練習

進階練習

挑戰題

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

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

2. 實作 `EmailValidator`

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

2. 實作 `ConditionalValidator[T]`

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