Oop on Tarragon

4.1 類別設計原則

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

Python 支援物件導向程式設計，但並不強制使用。本章介紹何時該使用類別，以及如何設計清晰的類別介面。

何時使用類別？

使用類別的情況

封裝狀態和行為

1class MarkdownLinkChecker:
2    def __init__(self, project_root):
3        self.project_root = Path(project_root)
4
5    def check_file(self, path):
6        ...
7
8    def check_directory(self, path):
9        ...

需要多個實例

1checker1 = MarkdownLinkChecker("/project1")
2checker2 = MarkdownLinkChecker("/project2")

有複雜的初始化邏輯

使用函式的情況

無狀態的操作

1def run_git_command(args):
2    # 不需要保存狀態
3    ...

簡單的工具函式

1def is_protected_branch(branch):
2    return branch in PROTECTED_BRANCHES

實際範例：Hook 驗證器

來自 .claude/lib/hook_validator.py：

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 類別常數
 5    HOOK_IO_PATTERNS = [
 6        r"from\s+hook_io\s+import",
 7        r"from\s+lib\.hook_io\s+import",
 8    ]
 9
10    def __init__(self, project_root: Optional[str] = None):
11        """
12        初始化驗證器
13
14        Args:
15            project_root: 專案根目錄
16        """
17        if project_root is None:
18            project_root = os.environ.get(
19                "CLAUDE_PROJECT_DIR",
20                os.getcwd()
21            )
22        self.project_root = Path(project_root)
23
24    def validate_hook(self, hook_path: str) -> ValidationResult:
25        """驗證單個 Hook 檔案"""
26        hook_path = self._resolve_path(hook_path)
27        # ... 驗證邏輯 ...
28        return ValidationResult(...)
29
30    def validate_all_hooks(self, hooks_dir: Optional[str] = None):
31        """驗證所有 Hook 檔案"""
32        ...
33
34    # 私有方法
35    def _resolve_path(self, path: str) -> Path:
36        """解析路徑為絕對路徑"""
37        p = Path(path)
38        if p.is_absolute():
39            return p
40        return self.project_root / p

設計分析

元素	說明
類別常數	`HOOK_IO_PATTERNS` - 共用的配置
實例變數	`self.project_root` - 每個實例可能不同
公開方法	`validate_hook()`, `validate_all_hooks()`
私有方法	`_resolve_path()` - 內部使用

類別設計原則

1. 單一職責原則（SRP）

每個類別只負責一件事：

 1# 好：每個類別有單一職責
 2class MarkdownLinkChecker:
 3    """只負責檢查 Markdown 連結"""
 4    def check_file(self, path): ...
 5    def check_directory(self, path): ...
 6
 7class HookValidator:
 8    """只負責驗證 Hook"""
 9    def validate_hook(self, path): ...
10    def validate_all_hooks(self): ...
11
12# 不好：一個類別做太多事
13class FileProcessor:
14    def check_links(self): ...
15    def validate_hooks(self): ...
16    def format_code(self): ...
17    def run_tests(self): ...

2. 封裝

隱藏內部實作，只暴露必要的介面：

 1class MarkdownLinkChecker:
 2    # 私有常數（Python 慣例用底線）
 3    _EXTERNAL_PATTERNS = [r'^https?://', r'^mailto:']
 4
 5    def __init__(self, project_root):
 6        # 私有屬性
 7        self._project_root = Path(project_root)
 8
 9    # 公開方法
10    def check_file(self, path):
11        return self._do_check(path)
12
13    # 私有方法
14    def _do_check(self, path):
15        ...
16
17    def _is_external_link(self, target):
18        ...

3. 明確的初始化

__init__ 應該完成所有必要的初始化：

 1class HookValidator:
 2    def __init__(self, project_root: Optional[str] = None):
 3        # 處理預設值
 4        if project_root is None:
 5            project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 6
 7        # 初始化所有實例變數
 8        self.project_root = Path(project_root)
 9
10        # 不要在這裡做複雜的 I/O 操作

實際範例：Markdown 連結檢查器

來自 .claude/lib/markdown_link_checker.py：

 1class MarkdownLinkChecker:
 2    """Markdown 連結檢查器"""
 3
 4    # 編譯好的正則表達式（類別常數）
 5    INLINE_LINK_PATTERN = re.compile(
 6        r'(?
 7    )
 8
 9    EXTERNAL_PATTERNS = [
10        r'^https?://',
11        r'^mailto:',
12        r'^tel:',
13    ]
14
15    def __init__(self, project_root: Optional[str] = None):
16        if project_root is None:
17            project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
18        self.project_root = Path(project_root)
19
20    def check_file(self, file_path: str) -> LinkCheckResult:
21        """檢查單個 Markdown 檔案"""
22        file_path = self._resolve_path(file_path)
23
24        if not file_path.exists():
25            return self._create_error_result(file_path, "檔案不存在")
26
27        content = file_path.read_text(encoding="utf-8")
28        links = self.parse_markdown_links(content)
29        broken_links = self._check_links(links, file_path.parent)
30
31        return LinkCheckResult(
32            file_path=str(file_path),
33            total_links=len(links),
34            broken_links=broken_links
35        )
36
37    def check_directory(self, dir_path: str, recursive=True):
38        """檢查目錄下所有 Markdown 檔案"""
39        ...
40
41    def parse_markdown_links(self, content: str) -> list[dict]:
42        """解析 Markdown 中的連結"""
43        ...
44
45    # === 私有方法 ===
46
47    def _resolve_path(self, path: str) -> Path:
48        p = Path(path)
49        return p if p.is_absolute() else self.project_root / p
50
51    def _is_external_link(self, target: str) -> bool:
52        return any(re.match(p, target) for p in self.EXTERNAL_PATTERNS)
53
54    def _create_error_result(self, path, message):
55        ...

類別與模組函式的搭配

提供方便的模組層級函式：

 1# markdown_link_checker.py
 2
 3class MarkdownLinkChecker:
 4    """類別實作"""
 5    ...
 6
 7# 方便使用的模組函式
 8def check_markdown_links(file_path: str, project_root: Optional[str] = None):
 9    """
10    檢查單個檔案（便捷函式）
11
12    Example:
13        result = check_markdown_links("docs/README.md")
14    """
15    checker = MarkdownLinkChecker(project_root)
16    return checker.check_file(file_path)
17
18def check_directory(dir_path: str, project_root: Optional[str] = None):
19    """檢查目錄（便捷函式）"""
20    checker = MarkdownLinkChecker(project_root)
21    return checker.check_directory(dir_path)

文檔字串

類別文檔

 1class HookValidator:
 2    """
 3    Hook 合規性驗證器
 4
 5    驗證 Hook 腳本是否遵循專案規範，包含：
 6    - 共用模組導入檢查
 7    - 輸出格式檢查
 8    - 測試存在性檢查
 9
10    Attributes:
11        project_root: 專案根目錄路徑
12
13    Example:
14        validator = HookValidator()
15        result = validator.validate_hook("my_hook.py")
16        if not result.is_compliant:
17            print(result.issues)
18    """

方法文檔

 1def validate_hook(self, hook_path: str) -> ValidationResult:
 2    """
 3    驗證單個 Hook 檔案
 4
 5    Args:
 6        hook_path: Hook 檔案路徑（相對或絕對）
 7
 8    Returns:
 9        ValidationResult: 驗證結果
10
11    Raises:
12        FileNotFoundError: 如果檔案不存在
13
14    Example:
15        result = validator.validate_hook(".claude/hooks/my_hook.py")
16    """

最佳實踐

1. 優先使用組合而非繼承

1# 好：組合
2class HookValidator:
3    def __init__(self):
4        self.link_checker = MarkdownLinkChecker()
5        self.config_loader = ConfigLoader()
6
7# 避免：深層繼承
8class SpecialValidator(HookValidator, LinkChecker, ConfigLoader):
9    ...

2. 保持類別小巧

1# 如果類別太大，考慮拆分
2class ValidationEngine:
3    def __init__(self):
4        self.import_checker = ImportChecker()
5        self.format_checker = FormatChecker()
6        self.test_checker = TestChecker()

3. 使用有意義的命名

1# 好
2class MarkdownLinkChecker:
3    def check_file(self, path): ...
4
5# 不好
6class Checker:
7    def do_it(self, x): ...

思考題

什麼時候應該使用類別，什麼時候應該使用函式？
_method 和 __method 有什麼區別？
為什麼 Hook 系統同時提供類別和便捷函式？

實作練習

將一組相關的函式重構為一個類別
為現有類別添加完整的文檔字串
實作一個遵循單一職責原則的驗證器類別

4.2 抽象基類 ABC

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

抽象基類（Abstract Base Class，ABC）用於定義介面契約，確保子類別實作必要的方法。這在建立可擴展的框架時特別有用。

為什麼需要抽象基類？

問題場景

假設我們有多種檔案解析器：

 1class JsonParser:
 2    def parse(self, content: str) -> dict:
 3        return json.loads(content)
 4
 5class YamlParser:
 6    def parse(self, content: str) -> dict:
 7        return yaml.safe_load(content)
 8
 9class XmlParser:
10    # 忘記實作 parse 方法！
11    def read(self, content: str) -> dict:  # 方法名稱錯誤
12        ...

問題：沒有強制的介面，容易出錯。

使用 ABC 解決

 1from abc import ABC, abstractmethod
 2
 3class BaseParser(ABC):
 4    """解析器抽象基類"""
 5
 6    @abstractmethod
 7    def parse(self, content: str) -> dict:
 8        """解析內容並返回字典"""
 9        pass
10
11class XmlParser(BaseParser):
12    # 如果沒有實作 parse，會報錯
13    def parse(self, content: str) -> dict:
14        ...

基本語法

定義抽象基類

 1from abc import ABC, abstractmethod
 2from typing import Optional
 3
 4class BaseParser(ABC):
 5    """解析器基類"""
 6
 7    def __init__(self, encoding: str = "utf-8"):
 8        self.encoding = encoding
 9
10    @abstractmethod
11    def parse(self, content: str) -> dict:
12        """
13        解析內容（子類別必須實作）
14
15        Args:
16            content: 要解析的內容
17
18        Returns:
19            dict: 解析後的資料
20        """
21        pass
22
23    @abstractmethod
24    def validate(self, content: str) -> bool:
25        """驗證內容格式（子類別必須實作）"""
26        pass
27
28    def parse_file(self, path: str) -> dict:
29        """
30        解析檔案（共用方法）
31
32        這是具體實作，子類別可以直接使用或覆寫。
33        """
34        with open(path, encoding=self.encoding) as f:
35            content = f.read()
36        return self.parse(content)

實作子類別

 1class JsonParser(BaseParser):
 2    """JSON 解析器"""
 3
 4    def parse(self, content: str) -> dict:
 5        return json.loads(content)
 6
 7    def validate(self, content: str) -> bool:
 8        try:
 9            json.loads(content)
10            return True
11        except json.JSONDecodeError:
12            return False
13
14class YamlParser(BaseParser):
15    """YAML 解析器"""
16
17    def parse(self, content: str) -> dict:
18        return yaml.safe_load(content) or {}
19
20    def validate(self, content: str) -> bool:
21        try:
22            yaml.safe_load(content)
23            return True
24        except yaml.YAMLError:
25            return False

抽象屬性

除了方法，也可以定義抽象屬性：

 1from abc import ABC, abstractmethod
 2
 3class BaseParser(ABC):
 4
 5    @property
 6    @abstractmethod
 7    def file_extension(self) -> str:
 8        """支援的檔案副檔名"""
 9        pass
10
11    @property
12    @abstractmethod
13    def mime_type(self) -> str:
14        """MIME 類型"""
15        pass
16
17class JsonParser(BaseParser):
18
19    @property
20    def file_extension(self) -> str:
21        return ".json"
22
23    @property
24    def mime_type(self) -> str:
25        return "application/json"

範本方法模式

ABC 常與範本方法模式搭配使用：

 1from abc import ABC, abstractmethod
 2
 3class DataProcessor(ABC):
 4    """資料處理器基類"""
 5
 6    def process(self, data: str) -> dict:
 7        """
 8        範本方法：定義處理流程
 9
10        1. 驗證
11        2. 前處理
12        3. 解析
13        4. 後處理
14        """
15        # 步驟 1：驗證（子類別實作）
16        if not self.validate(data):
17            raise ValueError("Invalid data")
18
19        # 步驟 2：前處理（可選覆寫）
20        data = self.preprocess(data)
21
22        # 步驟 3：解析（子類別實作）
23        result = self.parse(data)
24
25        # 步驟 4：後處理（可選覆寫）
26        return self.postprocess(result)
27
28    @abstractmethod
29    def validate(self, data: str) -> bool:
30        """驗證資料（子類別必須實作）"""
31        pass
32
33    @abstractmethod
34    def parse(self, data: str) -> dict:
35        """解析資料（子類別必須實作）"""
36        pass
37
38    def preprocess(self, data: str) -> str:
39        """前處理（預設不做任何處理）"""
40        return data
41
42    def postprocess(self, result: dict) -> dict:
43        """後處理（預設不做任何處理）"""
44        return result

實作檢查

無法直接實例化

1class BaseParser(ABC):
2    @abstractmethod
3    def parse(self, content: str) -> dict:
4        pass
5
6# 錯誤：無法實例化抽象類別
7parser = BaseParser()  # TypeError!

必須實作所有抽象方法

1class IncompleteParser(BaseParser):
2    # 沒有實作 parse 方法
3    pass
4
5# 錯誤：無法實例化
6parser = IncompleteParser()  # TypeError!

檢查子類別關係

 1from abc import ABC
 2
 3class BaseParser(ABC):
 4    pass
 5
 6class JsonParser(BaseParser):
 7    pass
 8
 9# 使用 isinstance 和 issubclass
10parser = JsonParser()
11isinstance(parser, BaseParser)     # True
12issubclass(JsonParser, BaseParser) # True

與 Protocol 的比較

Python 3.8+ 引入了 Protocol，提供結構化子型別（Structural Subtyping）：

ABC（名義子型別）

 1from abc import ABC, abstractmethod
 2
 3class Parseable(ABC):
 4    @abstractmethod
 5    def parse(self, content: str) -> dict:
 6        pass
 7
 8# 必須明確繼承
 9class JsonParser(Parseable):  # 必須繼承 Parseable
10    def parse(self, content: str) -> dict:
11        return json.loads(content)

Protocol（結構化子型別）

 1from typing import Protocol
 2
 3class Parseable(Protocol):
 4    def parse(self, content: str) -> dict:
 5        ...
 6
 7# 不需要繼承，只要有相同的方法
 8class JsonParser:  # 不需要繼承
 9    def parse(self, content: str) -> dict:
10        return json.loads(content)
11
12def process(parser: Parseable) -> None:
13    parser.parse("...")
14
15# JsonParser 自動符合 Parseable 協議
16process(JsonParser())  # OK

何時使用哪個？

特性	ABC	Protocol
需要繼承	是	否
執行時檢查	支援	有限支援
可以有共用方法	是	是（3.8+）
適合場景	框架設計	型別提示

最佳實踐

1. 保持介面簡潔

 1# 好：專注於核心方法
 2class BaseParser(ABC):
 3    @abstractmethod
 4    def parse(self, content: str) -> dict:
 5        pass
 6
 7# 不好：太多抽象方法
 8class BaseParser(ABC):
 9    @abstractmethod
10    def parse(self): pass
11    @abstractmethod
12    def validate(self): pass
13    @abstractmethod
14    def preprocess(self): pass
15    @abstractmethod
16    def postprocess(self): pass
17    @abstractmethod
18    def format(self): pass

2. 提供有用的預設實作

1class BaseParser(ABC):
2    @abstractmethod
3    def parse(self, content: str) -> dict:
4        pass
5
6    # 有預設實作的方法
7    def parse_file(self, path: str) -> dict:
8        with open(path) as f:
9            return self.parse(f.read())

3. 清晰的文檔

 1class BaseParser(ABC):
 2    """
 3    解析器抽象基類
 4
 5    所有解析器都應繼承此類別並實作 parse 方法。
 6
 7    Example:
 8        class MyParser(BaseParser):
 9            def parse(self, content: str) -> dict:
10                return {"data": content}
11    """
12
13    @abstractmethod
14    def parse(self, content: str) -> dict:
15        """
16        解析內容
17
18        Args:
19            content: 要解析的字串內容
20
21        Returns:
22            dict: 解析後的字典
23
24        Raises:
25            ParseError: 如果解析失敗
26        """
27        pass

思考題

什麼時候應該使用 ABC，什麼時候使用 Protocol？
抽象方法可以有實作嗎？有什麼用途？
如何測試抽象基類？

實作練習

設計一個 BaseValidator 抽象基類，定義驗證器的介面
實作兩個繼承自 BaseValidator 的具體驗證器
使用範本方法模式實作一個多步驟的資料處理流程

4.3 工廠模式

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

工廠模式用於封裝物件的建立邏輯，讓使用者不需要知道具體的類別名稱，只需要提供識別資訊即可取得適當的物件。

為什麼需要工廠模式？

問題場景

 1# 使用者需要知道所有具體類別
 2if file_type == "json":
 3    parser = JsonParser()
 4elif file_type == "yaml":
 5    parser = YamlParser()
 6elif file_type == "xml":
 7    parser = XmlParser()
 8else:
 9    raise ValueError(f"Unknown type: {file_type}")
10
11# 問題：
12# 1. 使用者需要導入所有具體類別
13# 2. 新增類型需要修改多處程式碼
14# 3. 建立邏輯重複

使用工廠解決

1# 使用者只需要知道工廠
2parser = ParserFactory.create(file_type)
3
4# 新增類型只需要註冊到工廠
5# 使用者程式碼不需要修改

基本實作

簡單工廠

 1from abc import ABC, abstractmethod
 2
 3class BaseParser(ABC):
 4    @abstractmethod
 5    def parse(self, content: str) -> dict:
 6        pass
 7
 8class JsonParser(BaseParser):
 9    def parse(self, content: str) -> dict:
10        return json.loads(content)
11
12class YamlParser(BaseParser):
13    def parse(self, content: str) -> dict:
14        return yaml.safe_load(content)
15
16
17class ParserFactory:
18    """解析器工廠"""
19
20    # 註冊表
21    _parsers: dict[str, type] = {
22        "json": JsonParser,
23        "yaml": YamlParser,
24        "yml": YamlParser,
25    }
26
27    @classmethod
28    def create(cls, parser_type: str) -> BaseParser:
29        """
30        建立解析器
31
32        Args:
33            parser_type: 解析器類型
34
35        Returns:
36            BaseParser: 解析器實例
37
38        Raises:
39            ValueError: 未知的解析器類型
40        """
41        parser_class = cls._parsers.get(parser_type.lower())
42        if parser_class is None:
43            raise ValueError(f"Unknown parser type: {parser_type}")
44        return parser_class()
45
46    @classmethod
47    def register(cls, parser_type: str, parser_class: type) -> None:
48        """註冊新的解析器"""
49        cls._parsers[parser_type.lower()] = parser_class
50
51    @classmethod
52    def get_supported_types(cls) -> list[str]:
53        """取得支援的解析器類型"""
54        return list(cls._parsers.keys())

使用工廠

 1# 建立解析器
 2json_parser = ParserFactory.create("json")
 3yaml_parser = ParserFactory.create("yaml")
 4
 5# 查詢支援的類型
 6types = ParserFactory.get_supported_types()
 7# ['json', 'yaml', 'yml']
 8
 9# 註冊新類型
10class XmlParser(BaseParser):
11    def parse(self, content: str) -> dict:
12        ...
13
14ParserFactory.register("xml", XmlParser)

進階：帶參數的工廠

 1class ParserFactory:
 2    _parsers: dict[str, type] = {}
 3
 4    @classmethod
 5    def create(
 6        cls,
 7        parser_type: str,
 8        **kwargs
 9    ) -> BaseParser:
10        """
11        建立解析器（支援傳入參數）
12
13        Args:
14            parser_type: 解析器類型
15            **kwargs: 傳給解析器的參數
16
17        Example:
18            parser = ParserFactory.create(
19                "json",
20                encoding="utf-8",
21                strict=True
22            )
23        """
24        parser_class = cls._parsers.get(parser_type.lower())
25        if parser_class is None:
26            raise ValueError(f"Unknown parser type: {parser_type}")
27        return parser_class(**kwargs)

使用裝飾器註冊

更優雅的註冊方式：

 1class ParserFactory:
 2    _parsers: dict[str, type] = {}
 3
 4    @classmethod
 5    def register(cls, *names: str):
 6        """
 7        註冊解析器的裝飾器
 8
 9        Example:
10            @ParserFactory.register("json")
11            class JsonParser(BaseParser):
12                ...
13        """
14        def decorator(parser_class: type) -> type:
15            for name in names:
16                cls._parsers[name.lower()] = parser_class
17            return parser_class
18        return decorator
19
20    @classmethod
21    def create(cls, parser_type: str) -> BaseParser:
22        parser_class = cls._parsers.get(parser_type.lower())
23        if parser_class is None:
24            raise ValueError(f"Unknown parser type: {parser_type}")
25        return parser_class()
26
27
28# 使用裝飾器註冊
29@ParserFactory.register("json")
30class JsonParser(BaseParser):
31    def parse(self, content: str) -> dict:
32        return json.loads(content)
33
34
35@ParserFactory.register("yaml", "yml")
36class YamlParser(BaseParser):
37    def parse(self, content: str) -> dict:
38        return yaml.safe_load(content)

根據檔案自動選擇

 1class ParserFactory:
 2    _parsers: dict[str, type] = {}
 3    _extension_map: dict[str, str] = {
 4        ".json": "json",
 5        ".yaml": "yaml",
 6        ".yml": "yaml",
 7        ".xml": "xml",
 8    }
 9
10    @classmethod
11    def create_from_file(cls, file_path: str) -> BaseParser:
12        """
13        根據檔案副檔名自動選擇解析器
14
15        Args:
16            file_path: 檔案路徑
17
18        Example:
19            parser = ParserFactory.create_from_file("config.yaml")
20        """
21        from pathlib import Path
22        ext = Path(file_path).suffix.lower()
23
24        parser_type = cls._extension_map.get(ext)
25        if parser_type is None:
26            raise ValueError(f"Unsupported file extension: {ext}")
27
28        return cls.create(parser_type)

完整範例

 1from abc import ABC, abstractmethod
 2from pathlib import Path
 3
 4
 5class BaseParser(ABC):
 6    """解析器基類"""
 7
 8    @abstractmethod
 9    def parse(self, content: str) -> dict:
10        """解析內容"""
11        pass
12
13    def parse_file(self, path: str) -> dict:
14        """解析檔案"""
15        content = Path(path).read_text(encoding="utf-8")
16        return self.parse(content)
17
18
19class ParserFactory:
20    """解析器工廠"""
21
22    _parsers: dict[str, type] = {}
23    _extensions: dict[str, str] = {}
24
25    @classmethod
26    def register(cls, name: str, extensions: list[str] = None):
27        """
28        註冊解析器的裝飾器
29
30        Args:
31            name: 解析器名稱
32            extensions: 對應的副檔名列表
33        """
34        def decorator(parser_class: type) -> type:
35            cls._parsers[name.lower()] = parser_class
36
37            if extensions:
38                for ext in extensions:
39                    cls._extensions[ext.lower()] = name.lower()
40
41            return parser_class
42        return decorator
43
44    @classmethod
45    def create(cls, parser_type: str) -> BaseParser:
46        """建立解析器"""
47        parser_class = cls._parsers.get(parser_type.lower())
48        if parser_class is None:
49            available = ", ".join(cls._parsers.keys())
50            raise ValueError(
51                f"Unknown parser type: {parser_type}. "
52                f"Available: {available}"
53            )
54        return parser_class()
55
56    @classmethod
57    def create_from_file(cls, file_path: str) -> BaseParser:
58        """根據檔案副檔名自動建立解析器"""
59        ext = Path(file_path).suffix.lower()
60        parser_type = cls._extensions.get(ext)
61
62        if parser_type is None:
63            available = ", ".join(cls._extensions.keys())
64            raise ValueError(
65                f"No parser for extension: {ext}. "
66                f"Supported: {available}"
67            )
68
69        return cls.create(parser_type)
70
71
72# 註冊解析器
73@ParserFactory.register("json", extensions=[".json"])
74class JsonParser(BaseParser):
75    def parse(self, content: str) -> dict:
76        import json
77        return json.loads(content)
78
79
80@ParserFactory.register("yaml", extensions=[".yaml", ".yml"])
81class YamlParser(BaseParser):
82    def parse(self, content: str) -> dict:
83        import yaml
84        return yaml.safe_load(content) or {}
85
86
87# 使用
88def load_config(path: str) -> dict:
89    """載入配置檔案（自動選擇解析器）"""
90    parser = ParserFactory.create_from_file(path)
91    return parser.parse_file(path)
92
93# 使用範例
94config = load_config("settings.yaml")
95config = load_config("data.json")

工廠與依賴注入

工廠模式也可以用於依賴注入：

 1class ServiceFactory:
 2    """服務工廠"""
 3
 4    _services: dict[str, object] = {}
 5
 6    @classmethod
 7    def register_singleton(cls, name: str, instance: object):
 8        """註冊單例服務"""
 9        cls._services[name] = instance
10
11    @classmethod
12    def get(cls, name: str) -> object:
13        """取得服務"""
14        if name not in cls._services:
15            raise ValueError(f"Service not registered: {name}")
16        return cls._services[name]
17
18
19# 應用程式啟動時註冊服務
20ServiceFactory.register_singleton("database", Database())
21ServiceFactory.register_singleton("cache", RedisCache())
22
23# 在其他地方使用
24db = ServiceFactory.get("database")

最佳實踐

1. 提供清楚的錯誤訊息

 1@classmethod
 2def create(cls, parser_type: str) -> BaseParser:
 3    parser_class = cls._parsers.get(parser_type.lower())
 4    if parser_class is None:
 5        available = ", ".join(sorted(cls._parsers.keys()))
 6        raise ValueError(
 7            f"Unknown parser type: '{parser_type}'. "
 8            f"Available types: {available}"
 9        )
10    return parser_class()

2. 支援查詢可用類型

1@classmethod
2def get_available_types(cls) -> list[str]:
3    """返回所有可用的解析器類型"""
4    return sorted(cls._parsers.keys())

3. 考慮快取實例

 1class ParserFactory:
 2    _parsers: dict[str, type] = {}
 3    _instances: dict[str, BaseParser] = {}
 4
 5    @classmethod
 6    def create(cls, parser_type: str, cached: bool = True):
 7        """建立或取得快取的解析器"""
 8        if cached and parser_type in cls._instances:
 9            return cls._instances[parser_type]
10
11        instance = cls._parsers[parser_type]()
12
13        if cached:
14            cls._instances[parser_type] = instance
15
16        return instance

思考題

工廠模式和直接使用 if-elif 有什麼區別？
使用裝飾器註冊有什麼優點？
什麼時候應該快取工廠建立的實例？

實作練習

實作一個驗證器工廠，支援不同類型的驗證器
為現有的工廠添加快取功能
實作一個支援依賴注入的服務工廠

上一章：抽象基類 ABC 下一章：單例與快取模式

6.3 如何新增語言解析器

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

本章示範如何透過繼承抽象基類來新增語言解析器。這是一個完整的實作範例，展示了前面學到的 ABC、工廠模式和型別提示等概念。

前置知識

建議先閱讀：

場景說明

假設 Hook 系統需要支援新的配置格式（例如 TOML），我們需要：

建立繼承自 BaseParser 的 TomlParser 類別
實作所有抽象方法
註冊到工廠
撰寫測試

步驟 1：了解基類介面

首先檢視抽象基類的定義：

 1# parsers/base.py
 2from abc import ABC, abstractmethod
 3from typing import Optional
 4
 5class BaseParser(ABC):
 6    """解析器抽象基類"""
 7
 8    def __init__(self, encoding: str = "utf-8"):
 9        self.encoding = encoding
10
11    @abstractmethod
12    def parse(self, content: str) -> dict:
13        """
14        解析內容
15
16        Args:
17            content: 要解析的字串
18
19        Returns:
20            dict: 解析後的字典
21
22        Raises:
23            ParseError: 解析失敗時拋出
24        """
25        pass
26
27    @abstractmethod
28    def validate(self, content: str) -> bool:
29        """
30        驗證內容格式是否正確
31
32        Args:
33            content: 要驗證的字串
34
35        Returns:
36            bool: 格式正確返回 True
37        """
38        pass
39
40    @property
41    @abstractmethod
42    def file_extensions(self) -> list[str]:
43        """支援的檔案副檔名列表"""
44        pass
45
46    # 共用方法（不是抽象的）
47    def parse_file(self, path: str) -> dict:
48        """解析檔案"""
49        from pathlib import Path
50        content = Path(path).read_text(encoding=self.encoding)
51        return self.parse(content)

步驟 2：實作新解析器

 1# parsers/toml_parser.py
 2"""
 3TOML 解析器
 4
 5支援 TOML 格式的配置檔案解析。
 6"""
 7
 8from typing import Optional
 9from .base import BaseParser
10
11# 嘗試導入 toml 模組
12try:
13    import tomllib  # Python 3.11+ 內建
14except ImportError:
15    try:
16        import toml as tomllib  # 第三方套件
17    except ImportError:
18        tomllib = None
19
20class TomlParser(BaseParser):
21    """
22    TOML 格式解析器
23
24    支援 .toml 檔案的解析。
25
26    Example:
27        parser = TomlParser()
28        config = parser.parse_file("config.toml")
29    """
30
31    def __init__(self, encoding: str = "utf-8"):
32        """
33        初始化 TOML 解析器
34
35        Args:
36            encoding: 檔案編碼
37
38        Raises:
39            ImportError: 如果 toml 模組不可用
40        """
41        if tomllib is None:
42            raise ImportError(
43                "TOML parser requires 'tomllib' (Python 3.11+) "
44                "or 'toml' package. Install with: pip install toml"
45            )
46        super().__init__(encoding)
47
48    def parse(self, content: str) -> dict:
49        """
50        解析 TOML 內容
51
52        Args:
53            content: TOML 格式的字串
54
55        Returns:
56            dict: 解析後的字典
57
58        Raises:
59            ValueError: 如果 TOML 格式錯誤
60        """
61        try:
62            # Python 3.11+ 的 tomllib 需要 bytes
63            if hasattr(tomllib, 'loads'):
64                return tomllib.loads(content)
65            else:
66                # tomllib (3.11+) 只接受 bytes
67                return tomllib.load(content.encode(self.encoding))
68        except Exception as e:
69            raise ValueError(f"Failed to parse TOML: {e}") from e
70
71    def validate(self, content: str) -> bool:
72        """
73        驗證 TOML 格式
74
75        Args:
76            content: 要驗證的字串
77
78        Returns:
79            bool: 格式正確返回 True
80        """
81        try:
82            self.parse(content)
83            return True
84        except ValueError:
85            return False
86
87    @property
88    def file_extensions(self) -> list[str]:
89        """支援的副檔名"""
90        return [".toml"]

步驟 3：註冊到工廠

 1# parsers/__init__.py
 2"""
 3解析器模組
 4
 5提供多種格式的檔案解析功能。
 6"""
 7
 8from .base import BaseParser
 9from .factory import ParserFactory
10from .json_parser import JsonParser
11from .yaml_parser import YamlParser
12
13# 註冊內建解析器
14ParserFactory.register("json", [".json"])(JsonParser)
15ParserFactory.register("yaml", [".yaml", ".yml"])(YamlParser)
16
17# 嘗試註冊 TOML 解析器（可選依賴）
18try:
19    from .toml_parser import TomlParser
20    ParserFactory.register("toml", [".toml"])(TomlParser)
21except ImportError:
22    pass  # TOML 支援不可用
23
24__all__ = [
25    "BaseParser",
26    "ParserFactory",
27    "JsonParser",
28    "YamlParser",
29]

或者使用裝飾器直接在類別定義時註冊：

1# parsers/toml_parser.py
2from .factory import ParserFactory
3from .base import BaseParser
4
5@ParserFactory.register("toml", [".toml"])
6class TomlParser(BaseParser):
7    """TOML 解析器"""
8    # ... 實作 ...

步驟 4：撰寫測試

 1# tests/test_toml_parser.py
 2"""
 3TOML 解析器測試
 4"""
 5
 6import unittest
 7from unittest.mock import patch
 8
 9# 跳過測試如果 toml 不可用
10try:
11    from parsers.toml_parser import TomlParser
12    HAS_TOML = True
13except ImportError:
14    HAS_TOML = False
15
16@unittest.skipUnless(HAS_TOML, "TOML support not available")
17class TestTomlParser(unittest.TestCase):
18    """測試 TomlParser 類別"""
19
20    def setUp(self):
21        """測試前準備"""
22        self.parser = TomlParser()
23
24    def test_parse_simple_toml(self):
25        """測試解析簡單的 TOML"""
26        content = """
27        [server]
28        host = "localhost"
29        port = 8080
30        """
31        result = self.parser.parse(content)
32
33        self.assertEqual(result["server"]["host"], "localhost")
34        self.assertEqual(result["server"]["port"], 8080)
35
36    def test_parse_nested_toml(self):
37        """測試解析巢狀的 TOML"""
38        content = """
39        [database]
40        host = "localhost"
41
42        [database.connection]
43        timeout = 30
44        retries = 3
45        """
46        result = self.parser.parse(content)
47
48        self.assertEqual(result["database"]["host"], "localhost")
49        self.assertEqual(result["database"]["connection"]["timeout"], 30)
50
51    def test_validate_valid_toml(self):
52        """測試驗證有效的 TOML"""
53        content = '[section]\nkey = "value"'
54        self.assertTrue(self.parser.validate(content))
55
56    def test_validate_invalid_toml(self):
57        """測試驗證無效的 TOML"""
58        content = "this is not valid TOML ["
59        self.assertFalse(self.parser.validate(content))
60
61    def test_parse_invalid_raises_error(self):
62        """測試解析無效 TOML 時拋出錯誤"""
63        content = "invalid [ toml"
64        with self.assertRaises(ValueError):
65            self.parser.parse(content)
66
67    def test_file_extensions(self):
68        """測試檔案副檔名"""
69        self.assertIn(".toml", self.parser.file_extensions)
70
71@unittest.skipUnless(HAS_TOML, "TOML support not available")
72class TestTomlParserFactory(unittest.TestCase):
73    """測試 TOML 解析器與工廠的整合"""
74
75    def test_factory_creates_toml_parser(self):
76        """測試工廠可以建立 TOML 解析器"""
77        from parsers import ParserFactory
78
79        parser = ParserFactory.create("toml")
80        self.assertIsInstance(parser, TomlParser)
81
82    def test_factory_creates_from_file(self):
83        """測試工廠根據副檔名建立解析器"""
84        from parsers import ParserFactory
85
86        parser = ParserFactory.create_from_file("config.toml")
87        self.assertIsInstance(parser, TomlParser)
88
89if __name__ == "__main__":
90    unittest.main()

步驟 5：更新文件

在 README 或相關文件中記錄新功能：

 1## 支援的配置格式
 2
 3- JSON (.json) - 內建支援
 4- YAML (.yaml, .yml) - 需要 PyYAML
 5- TOML (.toml) - 需要 Python 3.11+ 或 toml 套件
 6
 7### 安裝 TOML 支援
 8
 9```bash
10# Python 3.11+ 內建支援
11# 或安裝第三方套件
12pip install toml
13```

使用範例

1from parsers import ParserFactory
2
3# 自動選擇解析器
4parser = ParserFactory.create_from_file("config.toml")
5config = parser.parse_file("config.toml")

 1
 2## 完整檢查清單
 3
 4新增解析器時的檢查項目：
 5
 6- [ ] 繼承 `BaseParser`
 7- [ ] 實作所有 `@abstractmethod`
 8  - [ ] `parse(content: str) -> dict`
 9  - [ ] `validate(content: str) -> bool`
10  - [ ] `file_extensions` 屬性
11- [ ] 處理可選依賴
12- [ ] 註冊到 `ParserFactory`
13- [ ] 撰寫單元測試
14  - [ ] 正常解析
15  - [ ] 錯誤處理
16  - [ ] 驗證功能
17  - [ ] 工廠整合
18- [ ] 更新文件
19- [ ] 更新 `__all__` 匯出
20
21## 常見問題
22
23### Q: 如果依賴套件不可用怎麼辦？
24
25在 `__init__` 中檢查並提供清楚的錯誤訊息：
26
27```python
28def __init__(self):
29    if required_module is None:
30        raise ImportError(
31            "TomlParser requires 'toml' package. "
32            "Install with: pip install toml"
33        )

Q: 如何處理不同版本的 API？

1try:
2    import tomllib  # Python 3.11+
3    def parse_toml(content: str) -> dict:
4        return tomllib.loads(content)
5except ImportError:
6    import toml
7    def parse_toml(content: str) -> dict:
8        return toml.loads(content)

Q: 解析錯誤應該拋出什麼異常？

建議轉換為標準異常並保留原始資訊：

1try:
2    return toml.loads(content)
3except toml.TomlDecodeError as e:
4    raise ValueError(f"Invalid TOML: {e}") from e

思考題

為什麼要將原始異常作為 from e 傳遞？
如何設計讓解析器支援串流處理（大檔案）？
如果要支援解析器鏈（先解密再解析），應該如何設計？

開放封閉原則與認知負擔

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

OCP 的傳統解釋

開放封閉原則（Open-Closed Principle, OCP）是 SOLID 原則之一，傳統定義是：

軟體實體（類別、模組、函式）應該對擴展開放，對修改封閉。

這意味著：

對擴展開放：可以增加新功能
對修改封閉：不需要修改現有程式碼

傳統焦點：避免修改帶來的風險

傳統觀點認為，OCP 的目的是：

避免修改穩定的程式碼引入錯誤
減少回歸測試的範圍
保護現有功能不受影響

這些都是正確的，但還有一個更深層的目的。

OCP 的認知負擔視角（用戶觀點）

真正目的：讓閱讀者不需要理解整個系統才能使用

從認知負擔的角度來看，OCP 的核心價值是：

擴展系統時，開發者只需要理解介面，不需要理解實作。

這大幅降低了認知負擔。

範例：違反 OCP 的設計

 1class ReportGenerator:
 2    def generate(self, report_type: str, data: dict) -> str:
 3        if report_type == "pdf":
 4            # 100 行 PDF 生成邏輯
 5            return self._generate_pdf(data)
 6        elif report_type == "excel":
 7            # 80 行 Excel 生成邏輯
 8            return self._generate_excel(data)
 9        elif report_type == "html":
10            # 60 行 HTML 生成邏輯
11            return self._generate_html(data)
12        else:
13            raise ValueError(f"Unknown report type: {report_type}")

問題：

新增格式需要修改這個類別
理解新增功能需要閱讀整個類別
每種格式的邏輯混在一起

認知負擔：要新增 CSV 格式，開發者需要理解整個 ReportGenerator 類別的結構，找到正確的位置插入程式碼，並確保不影響其他格式。

範例：遵循 OCP 的設計

 1from abc import ABC, abstractmethod
 2
 3class ReportFormatter(ABC):
 4    """報告格式化器的抽象介面"""
 5
 6    @abstractmethod
 7    def format(self, data: dict) -> str:
 8        """將資料格式化為報告"""
 9        pass
10
11class PdfFormatter(ReportFormatter):
12    def format(self, data: dict) -> str:
13        # PDF 生成邏輯
14        pass
15
16class ExcelFormatter(ReportFormatter):
17    def format(self, data: dict) -> str:
18        # Excel 生成邏輯
19        pass
20
21class HtmlFormatter(ReportFormatter):
22    def format(self, data: dict) -> str:
23        # HTML 生成邏輯
24        pass
25
26class ReportGenerator:
27    def __init__(self, formatter: ReportFormatter):
28        self._formatter = formatter
29
30    def generate(self, data: dict) -> str:
31        return self._formatter.format(data)

新增 CSV 格式：

1class CsvFormatter(ReportFormatter):
2    def format(self, data: dict) -> str:
3        # CSV 生成邏輯
4        pass
5
6# 使用
7generator = ReportGenerator(CsvFormatter())
8report = generator.generate(data)

認知負擔：要新增 CSV 格式，開發者只需要：

理解 ReportFormatter 介面（一個方法）
實作 format 方法

不需要閱讀 PdfFormatter、ExcelFormatter 或 ReportGenerator 的實作。

擴展時只需要理解介面，不需要理解實作

這就是 OCP 降低認知負擔的方式：

情境	違反 OCP	遵循 OCP
新增格式	需要理解整個類別	只需理解介面
修改一個格式	可能影響其他格式	完全隔離
閱讀程式碼	需要跟蹤 if-else 分支	直接看對應的類別

這和命名是同一件事：降低認知負擔

回想命名的藝術：好的命名讓讀者不需要追溯定義就能理解。

OCP 做的是同樣的事，只是在更高的層級：好的設計讓讀者不需要理解整個系統就能擴展。

單一職責原則的本質

單一職責原則（Single Responsibility Principle, SRP）是另一個 SOLID 原則：

一個類別應該只有一個改變的理由。

一次只理解一件事

從認知負擔的角度，SRP 的核心是：

讓讀者一次只需要理解一件事。

 1# 違反 SRP：一個類別做太多事
 2class UserManager:
 3    def create_user(self, data):
 4        # 驗證邏輯
 5        # 資料庫操作
 6        # 發送歡迎郵件
 7        # 記錄日誌
 8        pass
 9
10    def delete_user(self, user_id):
11        # 權限檢查
12        # 資料庫操作
13        # 清理關聯資料
14        # 發送通知
15        # 記錄日誌
16        pass

問題：讀者想理解「如何發送歡迎郵件」，卻需要閱讀整個 UserManager 類別。

 1# 遵循 SRP：每個類別只做一件事
 2class UserValidator:
 3    def validate(self, data: dict) -> ValidationResult:
 4        pass
 5
 6class UserRepository:
 7    def create(self, user: User) -> User:
 8        pass
 9
10    def delete(self, user_id: str) -> bool:
11        pass
12
13class EmailService:
14    def send_welcome_email(self, user: User) -> None:
15        pass
16
17class UserService:
18    def __init__(
19        self,
20        validator: UserValidator,
21        repository: UserRepository,
22        email_service: EmailService
23    ):
24        self._validator = validator
25        self._repository = repository
26        self._email_service = email_service
27
28    def create_user(self, data: dict) -> User:
29        validation = self._validator.validate(data)
30        if not validation.is_valid:
31            raise ValidationError(validation.errors)
32
33        user = self._repository.create(User.from_dict(data))
34        self._email_service.send_welcome_email(user)
35        return user

現在，讀者想理解「如何發送歡迎郵件」，只需要看 EmailService。

類別/函式的職責清晰 = 閱讀時認知負擔低

職責數量	認知負擔	維護難度
1	低	容易
2-3	中	需要注意
4+	高	危險區域

和命名的關聯：如果難以命名，可能職責不單一

這是一個非常實用的檢測方法：

 1# 難以命名 = 職責不單一
 2class UserStuffManager:  # "stuff" 說明不知道它具體做什麼
 3    pass
 4
 5class DataProcessorAndValidator:  # "and" 說明做了兩件事
 6    pass
 7
 8class HelperUtils:  # "helper/utils" 說明是雜項收集
 9    pass
10
11# 容易命名 = 職責單一
12class UserAuthenticator:  # 清楚：處理用戶認證
13    pass
14
15class ConfigurationLoader:  # 清楚：載入配置
16    pass
17
18class EmailFormatter:  # 清楚：格式化郵件
19    pass

規則：如果你無法用一個簡短的名詞描述類別的職責，它可能做了太多事。

實際案例

Hook 系統中的設計決策

讓我們看 Hook 系統中如何應用這些原則：

配置載入器（遵循 SRP）

 1# .claude/lib/config_loader.py
 2class ConfigLoader:
 3    """
 4    單一職責：載入和快取配置檔案
 5
 6    不負責：
 7    - 驗證配置內容
 8    - 使用配置執行操作
 9    - 修改配置
10    """
11
12    def __init__(self, config_path: Path):
13        self._config_path = config_path
14        self._cache: Optional[dict] = None
15
16    def load(self) -> dict:
17        """載入配置，使用快取避免重複讀取"""
18        if self._cache is None:
19            self._cache = self._read_config()
20        return self._cache
21
22    def _read_config(self) -> dict:
23        with open(self._config_path) as f:
24            return yaml.safe_load(f)

解析器工廠（遵循 OCP）

 1# .claude/lib/parsers/base.py
 2class LanguageParser(ABC):
 3    """語言解析器的抽象介面"""
 4
 5    @abstractmethod
 6    def parse(self, content: str) -> ParseResult:
 7        pass
 8
 9    @abstractmethod
10    def get_supported_extensions(self) -> list[str]:
11        pass
12
13# .claude/lib/parsers/python_parser.py
14class PythonParser(LanguageParser):
15    def parse(self, content: str) -> ParseResult:
16        # Python 解析邏輯
17        pass
18
19    def get_supported_extensions(self) -> list[str]:
20        return [".py"]
21
22# .claude/lib/parsers/factory.py
23class ParserFactory:
24    """
25    對擴展開放：新增語言只需實作 LanguageParser
26    對修改封閉：不需要修改此工廠類別
27    """
28
29    _parsers: dict[str, type[LanguageParser]] = {}
30
31    @classmethod
32    def register(cls, parser_class: type[LanguageParser]) -> None:
33        for ext in parser_class.get_supported_extensions():
34            cls._parsers[ext] = parser_class
35
36    @classmethod
37    def get_parser(cls, file_extension: str) -> LanguageParser:
38        parser_class = cls._parsers.get(file_extension)
39        if parser_class is None:
40            raise UnsupportedLanguageError(file_extension)
41        return parser_class()

新增 Dart 語言支援：

 1# .claude/lib/parsers/dart_parser.py
 2class DartParser(LanguageParser):
 3    def parse(self, content: str) -> ParseResult:
 4        # Dart 解析邏輯
 5        pass
 6
 7    def get_supported_extensions(self) -> list[str]:
 8        return [".dart"]
 9
10# 註冊（可在初始化時自動完成）
11ParserFactory.register(DartParser)

開發者只需要：

理解 LanguageParser 介面
實作兩個方法
註冊解析器

不需要閱讀其他解析器的實作。

如何用「降低認知負擔」來判斷設計好壞

面對設計決策時，問自己這些問題：

擴展時：開發者需要理解多少現有程式碼？
- 好：只需要理解介面
- 壞：需要理解整個實作
修改時：改動會影響多少其他部分？
- 好：改動是局部的
- 壞：改動會連鎖反應
閱讀時：讀者一次需要記住多少概念？
- 好：一次一個概念
- 壞：需要同時記住多個概念

設計原則檢查清單

開放封閉原則

新增功能是否不需要修改現有程式碼？
擴展時是否只需要理解介面？
是否有抽象層隔離變化點？

單一職責原則

類別是否只有一個改變的理由？
類別名稱是否能清楚描述其職責？
類別是否小到可以快速理解？

認知負擔檢查

讀者是否能在 5 分鐘內理解這個類別？
是否需要閱讀其他類別才能理解這個類別？
修改這個類別是否需要擔心影響其他部分？

小結

從認知負擔的視角來看，OCP 和 SRP 的核心目的是：

OCP：讓開發者不需要理解整個系統就能擴展
SRP：讓開發者一次只需要理解一件事

這和命名是同一個哲學：降低閱讀者的認知負擔。

當你面對設計決策時，不要問「這是否符合 OCP」，而是問：

下一個開發者要擴展這個功能時，需要理解多少現有程式碼？

答案越少，設計越好。

參考資料

Martin, R. C. (2000). “Design Principles and Design Patterns”
Martin, R. C. (2017). “Clean Architecture”
Meyer, B. (1988). “Object-Oriented Software Construction”

4.4 單例與快取模式

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

在某些情況下，我們需要控制物件的建立次數或快取計算結果以提升效能。本章介紹 Hook 系統中使用的快取模式。

模組級快取

Python 模組是天然的單例——模組只會被載入一次。利用這個特性，可以實作簡單的快取。

實際範例：配置快取

來自 .claude/lib/config_loader.py：

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

使用方式

 1# 第一次呼叫：從檔案載入
 2config1 = load_agents_config()
 3
 4# 第二次呼叫：直接返回快取
 5config2 = load_agents_config()
 6
 7# config1 is config2  # True
 8
 9# 需要重新載入時
10clear_config_cache()
11config3 = load_agents_config()  # 重新從檔案載入

為什麼使用這個模式？

效能考量

 1# 沒有快取：每次都讀取檔案
 2def load_config_slow() -> dict:
 3    with open("config.yaml") as f:
 4        return yaml.safe_load(f)  # I/O 操作
 5
 6# 有快取：只讀取一次
 7def load_config_fast() -> dict:
 8    global _cache
 9    if _cache is None:
10        with open("config.yaml") as f:
11            _cache = yaml.safe_load(f)
12    return _cache

一致性

1# 確保所有地方使用相同的配置
2config_a = load_agents_config()
3config_b = load_agents_config()
4
5# 修改 config_a 會影響 config_b（因為是同一個物件）
6# 這可能是優點也可能是缺點，取決於使用場景

函式裝飾器快取

@functools.lru_cache

Python 標準庫提供的快取裝飾器：

 1from functools import lru_cache
 2
 3@lru_cache(maxsize=128)
 4def expensive_computation(n: int) -> int:
 5    """計算結果會被快取"""
 6    print(f"Computing for {n}...")
 7    return sum(range(n))
 8
 9# 第一次呼叫：執行計算
10result1 = expensive_computation(1000)  # 印出 "Computing for 1000..."
11
12# 第二次呼叫：直接返回快取
13result2 = expensive_computation(1000)  # 不印出任何東西
14
15# 清除快取
16expensive_computation.cache_clear()

@functools.cache (Python 3.9+)

無大小限制的快取：

 1from functools import cache
 2
 3@cache
 4def fibonacci(n: int) -> int:
 5    if n < 2:
 6        return n
 7    return fibonacci(n - 1) + fibonacci(n - 2)
 8
 9# 快取讓遞迴變得高效
10fibonacci(100)  # 瞬間完成

手動實作快取

字典快取

 1_cache: dict = {}
 2
 3def get_user(user_id: int) -> dict:
 4    """取得使用者資料，使用快取"""
 5    if user_id not in _cache:
 6        _cache[user_id] = fetch_from_database(user_id)
 7    return _cache[user_id]
 8
 9def invalidate_user(user_id: int) -> None:
10    """使特定使用者的快取失效"""
11    _cache.pop(user_id, None)
12
13def clear_all_cache() -> None:
14    """清除所有快取"""
15    _cache.clear()

帶過期時間的快取

 1from time import time
 2from typing import Optional, Any
 3
 4_cache: dict = {}
 5_cache_time: dict = {}
 6CACHE_TTL = 300  # 5 分鐘
 7
 8def get_with_ttl(key: str) -> Optional[Any]:
 9    """取得快取，檢查是否過期"""
10    if key in _cache:
11        if time() - _cache_time[key] < CACHE_TTL:
12            return _cache[key]
13        else:
14            # 快取過期
15            del _cache[key]
16            del _cache_time[key]
17    return None
18
19def set_with_ttl(key: str, value: Any) -> None:
20    """設定快取"""
21    _cache[key] = value
22    _cache_time[key] = time()

單例模式

當確實需要單例時的實作方式：

使用模組（最簡單）

 1# singleton.py
 2class _Singleton:
 3    def __init__(self):
 4        self.value = 0
 5
 6instance = _Singleton()
 7
 8# 使用
 9from singleton import instance
10instance.value = 42

使用類別裝飾器

 1def singleton(cls):
 2    instances = {}
 3
 4    def get_instance(*args, **kwargs):
 5        if cls not in instances:
 6            instances[cls] = cls(*args, **kwargs)
 7        return instances[cls]
 8
 9    return get_instance
10
11@singleton
12class Database:
13    def __init__(self):
14        print("Connecting to database...")
15
16# 使用
17db1 = Database()  # 印出 "Connecting..."
18db2 = Database()  # 不印出（返回同一個實例）
19db1 is db2  # True

使用 new

 1class Singleton:
 2    _instance = None
 3
 4    def __new__(cls):
 5        if cls._instance is None:
 6            cls._instance = super().__new__(cls)
 7        return cls._instance
 8
 9# 使用
10s1 = Singleton()
11s2 = Singleton()
12s1 is s2  # True

Hook 系統的實際應用

配置載入器的設計

 1# config_loader.py
 2
 3from typing import Optional
 4
 5# 私有快取
 6_agents_config_cache: Optional[dict] = None
 7
 8def load_agents_config() -> dict:
 9    """
10    載入代理人配置
11
12    特點：
13    1. 使用模組級快取
14    2. 支援預設配置
15    3. 提供清除快取的方法
16    """
17    global _agents_config_cache
18
19    if _agents_config_cache is None:
20        try:
21            _agents_config_cache = load_config("agents")
22        except FileNotFoundError:
23            # 返回預設配置
24            _agents_config_cache = _get_default_agents_config()
25
26    return _agents_config_cache
27
28def _get_default_agents_config() -> dict:
29    """預設配置"""
30    return {
31        "known_agents": [
32            "basil-hook-architect",
33            "thyme-documentation-integrator",
34            # ...
35        ],
36        "agent_dispatch_rules": {
37            "Hook 開發": "basil-hook-architect",
38            # ...
39        }
40    }

測試快取程式碼

 1import unittest
 2
 3class TestConfigLoader(unittest.TestCase):
 4
 5    def setUp(self):
 6        # 每個測試前清除快取
 7        clear_config_cache()
 8
 9    def tearDown(self):
10        # 每個測試後清除快取
11        clear_config_cache()
12
13    def test_config_is_cached(self):
14        """測試配置被快取"""
15        config1 = load_agents_config()
16        config2 = load_agents_config()
17
18        # 應該是同一個物件
19        self.assertIs(config1, config2)
20
21    def test_clear_cache_works(self):
22        """測試清除快取"""
23        config1 = load_agents_config()
24        clear_config_cache()
25        config2 = load_agents_config()
26
27        # 應該是不同的物件
28        self.assertIsNot(config1, config2)

最佳實踐

1. 提供清除快取的方法

1# 好：可以清除快取
2def clear_config_cache():
3    global _cache
4    _cache = None
5
6# 不好：無法重新載入

2. 考慮執行緒安全

 1import threading
 2
 3_lock = threading.Lock()
 4_cache = None
 5
 6def get_cached_value():
 7    global _cache
 8    if _cache is None:
 9        with _lock:
10            # 雙重檢查
11            if _cache is None:
12                _cache = expensive_computation()
13    return _cache

3. 文件化快取行為

1def load_config() -> dict:
2    """
3    載入配置
4
5    Note:
6        結果會被快取，後續呼叫返回同一個物件。
7        使用 clear_config_cache() 可重新載入。
8    """

思考題

模組級快取和 @lru_cache 有什麼區別？
為什麼 clear_config_cache() 很重要？
在多執行緒環境下，模組級快取可能有什麼問題？

實作練習

使用 @lru_cache 實作一個帶快取的 API 呼叫函式
實作一個帶 TTL（存活時間）的快取
為現有的快取添加執行緒安全保護

模組四：物件導向設計

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

Python 支援多種程式設計範式，物件導向是其中最重要的一種。本模組介紹 Hook 系統中使用的 OOP 技巧和設計模式。

章節列表

章節	主題	關鍵收穫
4.1	類別設計原則	設計清晰的類別介面
4.2	抽象基類 ABC	定義介面契約
4.3	工廠模式	動態建立物件
4.4	單例與快取模式	控制物件生命週期

實際範例來源

模式	範例來源
類別設計	`MarkdownLinkChecker`
抽象基類	`parsers/base.py`
工廠模式	`ParserFactory`
快取模式	`config_loader.py`

設計原則預覽

 1# 單一職責：每個類別只做一件事
 2class MarkdownLinkChecker:
 3 """只負責檢查 Markdown 連結"""
 4 pass
 5
 6# 開放封閉：對擴展開放，對修改封閉
 7class BaseParser(ABC):
 8 """定義介面，子類別實作細節"""
 9 @abstractmethod
10 def parse(self) -> dict:
11 pass

學習路徑

建議按順序學習：

1類別設計 → 抽象基類 → 工廠模式 → 單例/快取

學習時間

預計 60-90 分鐘

Oop on Tarragon

4.1 類別設計原則

何時使用類別？

使用類別的情況

封裝狀態和行為

需要多個實例

有複雜的初始化邏輯

使用函式的情況

無狀態的操作

簡單的工具函式

實際範例：Hook 驗證器

設計分析

類別設計原則

1. 單一職責原則（SRP）

2. 封裝

3. 明確的初始化

實際範例：Markdown 連結檢查器

類別與模組函式的搭配

文檔字串

類別文檔

方法文檔

最佳實踐

1. 優先使用組合而非繼承

2. 保持類別小巧

3. 使用有意義的命名

思考題

實作練習

延伸閱讀（進階系列）

4.2 抽象基類 ABC

為什麼需要抽象基類？

問題場景

使用 ABC 解決

基本語法

定義抽象基類

實作子類別

抽象屬性

範本方法模式

實作檢查

無法直接實例化

必須實作所有抽象方法

檢查子類別關係

與 Protocol 的比較

ABC（名義子型別）

Protocol（結構化子型別）

何時使用哪個？

最佳實踐

1. 保持介面簡潔

2. 提供有用的預設實作

3. 清晰的文檔

思考題

實作練習

延伸閱讀（進階系列）

4.3 工廠模式

為什麼需要工廠模式？

問題場景

使用工廠解決

基本實作

簡單工廠

使用工廠

進階：帶參數的工廠

使用裝飾器註冊

根據檔案自動選擇

完整範例

工廠與依賴注入

最佳實踐

1. 提供清楚的錯誤訊息

2. 支援查詢可用類型

3. 考慮快取實例

思考題

實作練習

6.3 如何新增語言解析器

前置知識

場景說明

步驟 1：了解基類介面

步驟 2：實作新解析器

步驟 3：註冊到工廠

步驟 4：撰寫測試

步驟 5：更新文件

使用範例

Q: 如何處理不同版本的 API？