Python 課程 – 型別提示與靜態分析（Type Hints & Static Analysis）

主題：type hint 語法

---

簡介

在 Python 這個動態語言中，變數的型別在執行時才會被決定，這讓開發者在編寫程式時享有極高的彈性。然而，隨著專案規模的擴大、團隊人數的增加，程式碼的可讀性、可維護性與錯誤偵測變得愈來愈重要。
自 Python 3.5 起引入的 type hint（型別提示）提供了一種以註解方式描述變數、函式參數與回傳值型別的機制，配合 mypy、pyright、pylint 等靜態分析工具，能在編譯前就捕捉到許多潛在的型別錯誤，提升開發效率與程式品質。

本篇文章將從語法基礎、實作範例、常見陷阱與最佳實踐，帶你一步步掌握 Python 型別提示的核心概念，並說明在真實專案中如何運用它來減少 bug、加速重構與提升團隊協作。

---

核心概念

1. 基本語法：-> 與 :

在函式定義時，我們可以使用冒號 : 來標註參數型別，使用箭頭 -> 來標註回傳值型別。型別提示本身不會改變執行時的行為，只是 靜態資訊。

def greet(name: str) -> str:
    """傳回問候語"""
    return f"Hello, {name}!"

• name: str 告訴讀者與分析工具 name 應該是字串。
• -> str 表示函式最終會回傳字串。

Tip：即使不寫回傳型別，工具仍會根據程式碼推斷，但明確標註可以避免推斷錯誤。

---

2. 常見型別：List, Dict, Tuple, Set

Python 內建的容器需要使用 typing 模組中的泛型（generic）型別來描述其元素型別。

from typing import List, Dict, Tuple, Set

def process_data(values: List[int]) -> Tuple[int, int]:
    """回傳最小值與最大值"""
    return min(values), max(values)

def merge_maps(a: Dict[str, int], b: Dict[str, int]) -> Dict[str, int]:
    """合併兩個字典，若鍵相同則相加"""
    result = a.copy()
    for k, v in b.items():
        result[k] = result.get(k, 0) + v
    return result

• List[int] 表示「只會出現 int 的列表」。
• Tuple[int, int] 表示長度固定且每個元素都是 int。

---

3. 可為 None 的型別：Optional

若參數或回傳值允許 None，使用 Optional[T]（等價於 Union[T, None]）能清楚表達意圖。

from typing import Optional

def find_user(user_id: int) -> Optional[dict]:
    """找不到使用者時回傳 None"""
    users = {1: {"name": "Alice"}, 2: {"name": "Bob"}}
    return users.get(user_id)          # 可能是 dict 或 None

---

4. 自訂型別別名與 NewType

在大型系統中，常會出現「相同結構但語意不同」的情況。NewType 能為已有型別建立語意上獨立的別名，讓靜態分析更嚴格。

from typing import NewType

UserId = NewType('UserId', int)   # 建立新的型別別名

def get_profile(uid: UserId) -> dict:
    # 假設此函式只接受 UserId，而非一般 int
    ...

# 正確使用
uid = UserId(42)
profile = get_profile(uid)

# 錯誤使用（mypy 會報錯）
# profile = get_profile(42)   # 直接傳 int 會被視為型別不符

---

5. 泛型（Generics）與 Protocol

當函式需要接受「任意型別但具備特定行為」時，可使用 TypeVar 與 Protocol 來描述。

from typing import TypeVar, Protocol

T = TypeVar('T')

class SupportsAdd(Protocol):
    def __add__(self, other: T) -> T: ...

def combine(a: T, b: T) -> T:
    """只要兩個參數支援 + 運算，就能相加"""
    return a + b          # 靜態分析會檢查 a、b 是否符合 SupportsAdd

---

程式碼範例彙總

以下提供 4 個實務上常會用到的範例，展示不同型別提示的寫法與好處。

# 範例 1：簡易資料驗證
def validate_age(age: int) -> bool:
    """年齡必須是 0~120 之間的正整數"""
    return 0 <= age <= 120

# 範例 2：使用 Union 處理多型別輸入
from typing import Union

def stringify(value: Union[int, float, str]) -> str:
    """把數字或字串轉成字串"""
    return str(value)

# 範例 3：遞迴型別（Tree）示範
from __future__ import annotations
from typing import List

class TreeNode:
    def __init__(self, value: int, children: List[TreeNode] | None = None):
        self.value = value
        self.children = children or []

def sum_tree(node: TreeNode) -> int:
    """計算整棵樹的數值總和"""
    total = node.value
    for child in node.children:
        total += sum_tree(child)
    return total

# 範例 4：結合 asyncio 與型別提示
import asyncio
from typing import Awaitable

async def fetch_data(url: str) -> dict:
    await asyncio.sleep(0.1)   # 模擬 I/O
    return {"url": url, "data": "sample"}

async def main() -> None:
    result: Awaitable[dict] = fetch_data("https://example.com")
    data = await result
    print(data)

# 若在 IDE 中開啟，會看到 `result` 的型別被正確推斷為 Awaitable[dict]

---

常見陷阱與最佳實踐

陷阱	可能的問題	解決方式
忘記匯入 typing	使用 List、Dict 等會出現 NameError	在檔案開頭 from typing import …
過度使用 Any	失去靜態檢查的意義，等同於不寫型別	只在真的無法確定型別時才使用 Any，或改用 Protocol
遺漏 Optional	變數允許 None 卻未標註，mypy 會警告	明確寫 Optional[T]，或使用 `
容器內部型別不一致	List[int] 內放入 str，執行時不會錯，但靜態分析會報錯	保持容器內部型別一致，若需混合型別使用 List[Union[int, str]]
在 __init__ 中未使用 self 型別	self 被推斷為 Any，導致屬性檢查失效	可以使用 Self（Python 3.11+）或 typing.TypeVar 來標註返回自身類別的型別

最佳實踐

1. 從入口函式開始標註：先為公共 API（例如 Flask 路由、CLI 指令）加入型別提示，逐步向內部擴展。
2. 結合 IDE 與 Linter：使用 VS Code、PyCharm 等支援型別提示的 IDE，搭配 mypy --strict 進行全專案檢查。
3. 維持一致的風格：在同一專案內盡量使用 typing 的統一寫法（例如 Python 3.10 以後優先使用 list[int] 而非 List[int]），避免混雜。
4. 定期更新型別註記：重構或加入新功能時，同步更新型別提示，防止「過時的註解」成為誤導。

---

實際應用場景

1. 大型資料處理管線
   在 ETL 工作中，資料結構往往經過多層轉換。使用 TypedDict、NamedTuple 或 dataclass 搭配型別提示，可在每一步明確保證欄位名稱與型別，減少因欄位遺失或型別不符導致的錯誤。

2. 微服務 API 合約
   透過 pydantic 的模型與型別提示，能自動產生 OpenAPI 規格，同時在服務端與客戶端都執行靜態檢查，確保前後端協議一致。

3. 機器學習模型前後處理
   訓練模型的輸入往往是 np.ndarray，而預測結果可能是 list[float]。型別提示讓資料科學家在撰寫前處理函式時，即可在 IDE 中即時看到型別不匹配的警告，避免因維度錯誤導致的 RuntimeError。

4. 異步程式與併發
   使用 asyncio 時，Awaitable[T]、Coroutine[Any, Any, T] 能讓開發者清楚知道每個協程最終回傳的型別，避免在 await 後誤用成其他型別。

---

總結

• 型別提示不是為了改變 Python 的執行行為，而是提供 靜態資訊，協助開發者、IDE 與分析工具在編譯前就捕捉錯誤。
• 透過 typing 模組，我們可以描述 基本型別、容器、可為 None 的型別、泛型與協定，讓程式碼更具可讀性與可維護性。
• 最佳實踐包括從公共 API 開始標註、結合 Linter、保持風格一致以及在重構時同步更新型別。
• 在 資料處理、微服務、機器學習與異步程式等實務場景中，型別提示已成為提升品質、降低除錯成本的關鍵工具。

藉由養成在每個函式、類別與模組上加上型別提示的習慣，你的 Python 專案將會變得更安全、更易於協作，也更容易在未來的升級與重構中保持穩定。祝你在寫程式的旅程中，玩得開心、寫得乾淨！