模組四：物件導向設計 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 下一章：單例與快取模式

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（存活時間）的快取
為現有的快取添加執行緒安全保護

模組四：物件導向設計 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. 考慮快取實例

思考題

實作練習

4.4 單例與快取模式

模組級快取

實際範例：配置快取

使用方式

為什麼使用這個模式？

效能考量

一致性

函式裝飾器快取

@functools.lru_cache

@functools.cache (Python 3.9+)