模組三：進階設計模式 on Tarragon

3.5.1 泛型進階

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

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

先備知識

入門系列 2.2 Optional、Union、泛型

TypeVar 進階

bound 參數

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

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

bound vs 限制型別

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

差異：

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

covariant 與 contravariant

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

問題情境

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

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

covariant（協變）

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

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

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

contravariant（逆變）

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

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

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

實際應用

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

Generic 類別

建立自己的泛型容器

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

多型別參數

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

繼承泛型類別

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

Protocol 與結構化子型別

什麼是 Protocol？

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

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

Protocol vs ABC

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

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

何時選擇 Protocol？

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

帶有屬性的 Protocol

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

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

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

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

常見錯誤

1. 忘記 TypeVar 的名稱參數

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

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

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

3. 誤用 covariant/contravariant

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

小結

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

思考題

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

下一章：3.5.2 異常設計架構

3.5.2 異常設計架構

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

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

先備知識

入門系列 5.1 異常處理策略

異常層級設計

為什麼需要層級設計？

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

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

模組級異常基類

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

細粒度異常分類

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

使用範例

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

異常鏈的進階用法

`cause` vs `context`

Python 有兩種異常鏈機制：

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

輸出差異：

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

何時使用 from

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

suppress context

有時你想切斷異常鏈：

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

輸出：

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

使用時機：

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

ExceptionGroup（Python 3.11+）

問題情境

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

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

ExceptionGroup 解決方案

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

except* 語法

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

實際範例：並行任務處理

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

巢狀 ExceptionGroup

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

異常 vs 返回值

何時使用異常

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

何時使用 Result 模式

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

混合使用

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

補充：contextlib.suppress

簡潔地忽略特定異常：

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

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

設計檢查表

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

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

小結

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

思考題

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

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

3.5.3 進階上下文管理

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

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

先備知識

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

上下文管理器協議

`enter` 與 `exit`

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

`exit` 的異常處理

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

返回值的重要性

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

contextlib 工具

@contextmanager 裝飾器

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

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

ExitStack

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

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

ExitStack 的回調功能

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

nullcontext

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

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

嵌套與組合上下文

資源的有序獲取與釋放

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

組合上下文管理器

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

async context manager

基本語法

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

@asynccontextmanager

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

與 asyncio 模組的連結

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

實際範例：交易管理器

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

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

常見錯誤

1. 忘記 yield

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

2. 在 finally 中 yield

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

3. 異常處理不當

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

小結

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

思考題

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

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

3.5.4 插件系統設計

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

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

先備知識

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

插件架構模式

模式一：基於繼承

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

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

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

模式二：基於註冊

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

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

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

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

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

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

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

使用 Metaclass 的進階版本

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

動態載入模組

importlib 基礎

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

從檔案路徑載入

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

importlib.metadata 的 entry_points（現代做法）

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

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

優點：

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

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

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

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

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

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

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

設計考量

安全性

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

版本相容性

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

小結

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

思考題

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

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

3.5.5 設計模式整合案例

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

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

先備知識

本模組 3.5.1-3.5.4 所有章節

案例一：迷你 ORM 框架

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

設計概覽

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

異常層級設計

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

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

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

泛型 Repository

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

上下文管理：交易

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

整合使用範例

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

案例二：任務排程器

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

設計概覽

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

異常設計

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

泛型任務定義

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

插件系統：任務處理器

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

上下文管理：任務上下文

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

排程器：整合所有模式

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

完整使用範例

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

模式協作關係圖

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

設計原則總結

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

思考題

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

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

3.5.6 軟體設計的取捨藝術

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

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

先備知識

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

為什麼取捨不可避免？

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

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

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

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

Python 的哲學立場

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

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

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

六個核心取捨維度

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

維度一：重複 vs 錯誤抽象

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

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

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

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

反思觀點 – AHA（Avoid Hasty Abstractions）

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

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

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

“Duplication is far cheaper than the wrong abstraction.”

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

錯誤抽象的演化過程

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

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

Python 實際案例

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

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

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

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

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

決策指引

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

維度二：效能 vs 可讀性

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

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

但完整的引用其實是：

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

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

Python 的定位

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

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

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

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

決策框架：何時該優化？

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

資料結構選擇的隱性取捨

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

維度三：Build vs Buy

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

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

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

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

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

Python 生態系統的案例

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

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

決策矩陣

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

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

Fail Fast 原則

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

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

Python 中的 Fail Fast

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

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

何時用哪種？

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

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

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

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

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

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

決策指引

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

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

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

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

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

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

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

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

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

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

三步決策法

步驟一：辨識取捨的存在

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

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

步驟二：量化代價

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

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

步驟三：偏好可逆的決策

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

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

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

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

可逆性評估表

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

經典案例研究

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

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

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

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

來源：Medium - Technical Debt vs. Innovation

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

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

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

業界的解決方案：

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

來源：Honeycomb - The Cost Crisis in Observability Tooling

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

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

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

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

Python 特有的取捨考量

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

The Zen of Python 說：

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

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

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

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

如何選擇？ 優先考慮：

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

型別提示的漸進策略

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

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

EAFP vs LBYL

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

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

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

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

取捨決策清單

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

決策前

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

評估中

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

決策後

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

本章重點整理

核心觀念

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

實用原則

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

模組三：進階設計模式 on Tarragon

3.5.1 泛型進階

先備知識

TypeVar 進階

bound 參數

bound vs 限制型別

covariant 與 contravariant

問題情境

covariant（協變）

contravariant（逆變）

實際應用

Generic 類別

建立自己的泛型容器

多型別參數

繼承泛型類別

Protocol 與結構化子型別

什麼是 Protocol？

Protocol vs ABC

何時選擇 Protocol？

帶有屬性的 Protocol

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

常見錯誤

1. 忘記 TypeVar 的名稱參數

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

3. 誤用 covariant/contravariant

小結

思考題

3.5.2 異常設計架構

先備知識

異常層級設計

為什麼需要層級設計？

模組級異常基類

細粒度異常分類

使用範例

異常鏈的進階用法

__cause__ vs __context__

何時使用 from

suppress context

ExceptionGroup（Python 3.11+）

問題情境

ExceptionGroup 解決方案

except* 語法

實際範例：並行任務處理

巢狀 ExceptionGroup

異常 vs 返回值

何時使用異常

何時使用 Result 模式

混合使用

補充：contextlib.suppress

設計檢查表

小結

思考題

3.5.3 進階上下文管理

先備知識

上下文管理器協議

__enter__ 與 __exit__

__exit__ 的異常處理

返回值的重要性

contextlib 工具

@contextmanager 裝飾器

ExitStack

ExitStack 的回調功能

nullcontext

嵌套與組合上下文

資源的有序獲取與釋放

組合上下文管理器

async context manager

基本語法

@asynccontextmanager

與 asyncio 模組的連結

實際範例：交易管理器

常見錯誤

1. 忘記 yield

2. 在 finally 中 yield

3. 異常處理不當

小結

思考題

3.5.4 插件系統設計

先備知識

插件架構模式

`cause` vs `context`

`enter` 與 `exit`

`exit` 的異常處理

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