Inheritance on Tarragon

4.2 抽象基類 ABC

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

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

為什麼需要抽象基類？

問題場景

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

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

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

使用 ABC 解決

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

基本語法

定義抽象基類

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

實作子類別

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

抽象屬性

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

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

範本方法模式

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

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

實作檢查

無法直接實例化

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

必須實作所有抽象方法

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

檢查子類別關係

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

與 Protocol 的比較

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

ABC（名義子型別）

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

Protocol（結構化子型別）

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

何時使用哪個？

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

最佳實踐

1. 保持介面簡潔

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

2. 提供有用的預設實作

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

3. 清晰的文檔

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

思考題

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

實作練習

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

6.3 如何新增語言解析器

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

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

前置知識

建議先閱讀：

場景說明

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

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

步驟 1：了解基類介面

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

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

步驟 2：實作新解析器

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

步驟 3：註冊到工廠

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

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

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

步驟 4：撰寫測試

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

步驟 5：更新文件

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

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

使用範例

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

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

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

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

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

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

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

思考題

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

late final 欄位不能用欄位覆蓋 — Dart 欄位的隱藏 getter/setter 機制

Tue, 30 Jun 2026 00:00:00 +0000

事件

AppService 宣告了 late final PackageInfo packageInfo;，在 init() 中透過 PackageInfo.fromPlatform() 非同步初始化。測試用的 TestAppService extends AppService 想跳過平台呼叫，直接給一個固定值：

1// ❌ analyzer 報錯：overridden_fields
2@override
3late final PackageInfo packageInfo = PackageInfo(...);

Dart analyzer 報 overridden_fields：欄位覆蓋了從 AppService 繼承的欄位。

根因：late final 欄位 = getter + setter

Dart 的每個 instance 欄位在底層都會生成對應的 getter（和非 final 的會生成 setter）。late final 更特殊——它生成的 getter 包含「是否已初始化」的檢查邏輯，setter 包含「只能寫入一次」的 guard。

當子類用另一個欄位覆蓋時，記憶體中會有兩個獨立的儲存槽：

存取來源	讀到的 slot
子類自己的程式碼	子類的 slot（已初始化）
父類的程式碼（繼承的方法）	父類的 slot（未初始化）

父類的 init() 或其他方法如果存取 packageInfo，會讀到父類那份未初始化的 slot，拋出 LateInitializationError。這就是為什麼 Dart 不允許用欄位覆蓋欄位。

修法：改用 getter 覆寫

1@override
2PackageInfo get packageInfo => PackageInfo(
3 appName: 'UniPos Test',
4 packageName: 'com.mxkj.unipos.test',
5 version: '1.0.0',
6 buildNumber: '1',
7 buildSignature: 'test',
8 installerStore: null,
9);

Getter 覆寫只有一個讀取入口——不管父類還是子類的程式碼呼叫 packageInfo，都走子類的 getter。不會有兩份 slot 的問題。

通則

Dart 中覆寫父類的欄位，一律用 getter（必要時加 setter），不要用欄位。這不只適用於 late final——所有欄位覆蓋都有同樣的雙 slot 風險，只是 late final 的症狀最明顯（直接拋 LateInitializationError），普通欄位的症狀更隱蔽（值不同步）。

Widget 子類重新宣告 key — 遮蔽父類屬性與 duplicate key 風險

Tue, 30 Jun 2026 00:00:00 +0000

事件

測試用的 TestRiveAnimation extends StatelessWidget 裡宣告了 final Key? key;，constructor 中透過 super(key: key) 傳給父類。Dart analyzer 警告 key overrides an inherited member。

加了 @override 可以消除警告，但問題沒有解決——class 裡現在有兩個 key slot（子類自己的和 Widget 繼承的），而 build 方法裡又寫了 Container(key: key)，把同一個 key 同時掛在 parent widget 和 child widget 上。

根因

Widget 的 key 是 final 屬性，由 constructor 的 super(key:) 設定。子類重新宣告同名欄位會產生 shadowing：

子類的程式碼（包括 build）讀到的是子類自己的那份 key
父類 Widget 的框架程式碼讀到的是父類的那份 key

兩份值相同（因為 constructor 都有寫入），但語意上是兩個獨立的 slot。更危險的是，如果在 build 裡把 key 往下傳給 child，同一棵 widget 子樹會出現兩個相同的 Key 值，Flutter 在 diff 時可能拋出 duplicate key 錯誤。

修法

不要重新宣告 key，改用 super.key：

1const TestRiveAnimation.asset(
2 this.asset, {
3 super.key, // 直接傳給 Widget，不產生新 slot
4 this.useArtboardSize = false,
5});

build 裡也不要把 widget 自身的 key 再傳給 child——key 是給 framework 用來識別這個 widget 的，不該手動轉發。

判斷原則

在 Flutter 中，key、hashCode、runtimeType 這類從 Widget / Object 繼承的屬性，子類永遠不該用欄位覆蓋。如果需要自訂行為，覆寫 getter。

Inheritance on Tarragon

4.2 抽象基類 ABC

為什麼需要抽象基類？

問題場景

使用 ABC 解決

基本語法

定義抽象基類

實作子類別

抽象屬性

範本方法模式

實作檢查

無法直接實例化

必須實作所有抽象方法

檢查子類別關係

與 Protocol 的比較

ABC（名義子型別）

Protocol（結構化子型別）

何時使用哪個？

最佳實踐

1. 保持介面簡潔

2. 提供有用的預設實作

3. 清晰的文檔

思考題

實作練習

延伸閱讀（進階系列）

6.3 如何新增語言解析器

前置知識

場景說明

步驟 1：了解基類介面

步驟 2：實作新解析器

步驟 3：註冊到工廠

步驟 4：撰寫測試

步驟 5：更新文件

使用範例

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

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

思考題

延伸閱讀（進階系列）

late final 欄位不能用欄位覆蓋 — Dart 欄位的隱藏 getter/setter 機制

事件

根因：late final 欄位 = getter + setter

修法：改用 getter 覆寫

通則

Widget 子類重新宣告 key — 遮蔽父類屬性與 duplicate key 風險

事件

根因

修法

判斷原則