前言

Python 是一種動態(tài)類型語言，這意味著變量的類型是在運行時才確定的。雖然這種靈活性帶來了便利，但在大型項目中，它也可能導(dǎo)致代碼難以理解和維護(hù)。為了改善這一點，Python 3.5 引入了 typing 模塊，為 Python 增加了靜態(tài)類型檢查的能力。

typing 模塊中的一個強(qiáng)大功能是 typing.Annotated。它允許你在類型注解上附加額外的元數(shù)據(jù)（metadata），從而使代碼更具自解釋性，并提升工具（如類型檢查器、IDE）的支持能力。

typing.Annotated 的基本概念

typing.Annotated 是一個類型構(gòu)造器（type constructor），它接受兩個參數(shù)：

• 第一個參數(shù)是實際的數(shù)據(jù)類型，比如 int、str 或自定義類；
• 后續(xù)參數(shù)是任意數(shù)量的元數(shù)據(jù)對象（metadata），這些對象可以是任何 Python 對象（字符串、字典、函數(shù)、類等），用于提供關(guān)于該類型的附加信息。

? 核心要點：Annotated[T, metadata] 的本質(zhì)是：“這個值是類型 T，同時還帶有某些額外說明”。

這些元數(shù)據(jù)本身不會影響程序運行時的行為（即不參與類型檢查邏輯），但可以被靜態(tài)分析工具（如 mypy、pyright）、IDE 或框架（如 FastAPI）讀取并用于增強(qiáng)功能。

?? 示例結(jié)構(gòu)：

from typing import Annotated

MyType = Annotated[int, "這是一個用戶ID"]

在這個例子中，MyType 仍然是 int 類型，但附加了 “這是一個用戶ID” 的描述信息。

使用方法

基礎(chǔ)用法

from typing import Annotated

UserId = Annotated[int, "User ID"]

def get_user_name(user_id: UserId) -> str:
    user_dict = {1: "Alice", 2: "Bob"}
    return user_dict.get(user_id, "Unknown")

?? 詳解：

• 我們定義了一個別名 UserId，它是 int 類型，但附帶了 “User ID” 的元數(shù)據(jù)。
• 在函數(shù) get_user_name 中，參數(shù) user_id 被標(biāo)注為 UserId 類型。
• 運行時，user_id 依然是整數(shù)；但在類型檢查或文檔生成時，工具可以知道這個 int 實際上代表“用戶ID”。

?? 好處：避免混淆。例如，如果函數(shù)有兩個 int 參數(shù)，一個是用戶ID，一個是訂單ID，通過 Annotated 可以清晰地區(qū)分它們。

與類型提示結(jié)合使用

Annotated 不僅適用于基礎(chǔ)類型，還可以嵌套在復(fù)雜類型中使用。

from typing import List, Annotated

ProductId = Annotated[int, "Product ID"]

def process_products(product_ids: List[ProductId]) -> None:
    for product_id in product_ids:
        print(f"Processing product with ID: {product_id}")

?? 詳解：

• List[ProductId] 表示這是一個整數(shù)列表，每個整數(shù)都應(yīng)被視為“產(chǎn)品ID”。
• 工具可以通過反射或靜態(tài)分析提取出 “Product ID” 這一語義信息，用于生成文檔、驗證輸入來源等。

?? 注意：Annotated 必須放在最內(nèi)層類型上。例如不能寫成 Annotated[List[int], …] 來標(biāo)注列表元素，而應(yīng)該對元素類型進(jìn)行標(biāo)注。

添加多個元數(shù)據(jù)

你可以為一個類型附加多個元數(shù)據(jù)項：

from typing import Annotated

DatabaseId = Annotated[int, "Database ID", "Unique identifier for a database"]

?? 詳解：

• DatabaseId 類型現(xiàn)在有兩個元數(shù)據(jù)字符串。
• 元數(shù)據(jù)可以是任意對象，不僅僅是字符串。例如：

from typing import Annotated

PositiveInt = Annotated[int, "必須大于0", {"min_value": 1}]

這些元數(shù)據(jù)可被自定義類型檢查器或序列化庫（如 Pydantic v2）用來實現(xiàn)驗證邏輯。

常見實踐

使用 typing.Annotated 進(jìn)行文檔化

Annotated 是一種輕量級的文檔方式，比注釋更結(jié)構(gòu)化。

from typing import Annotated

FileSize = Annotated[int, "Size of a file in bytes"]

def check_file_size(file_path: str, max_size: FileSize) -> bool:
    import os
    file_stat = os.stat(file_path)
    return file_stat.st_size <= max_size

?? 詳解：

• max_size 參數(shù)的類型是 FileSize，明確表明它是“以字節(jié)為單位的文件大小”。
• 相比于僅寫 int，這大大增強(qiáng)了函數(shù)接口的可讀性和自文檔性。
• IDE 可以在懸停提示中顯示該元數(shù)據(jù)，提升開發(fā)體驗。

在函數(shù)簽名中提供上下文

from typing import Annotated, Tuple

Coordinate = Annotated[Tuple[float, float], "Geographical coordinate (latitude, longitude)"]

def get_location(address: str) -> Coordinate:
    # 這里是占位實現(xiàn)
    return (0.0, 0.0)

?? 詳解：

• 返回值是一個浮點數(shù)元組，但通過 Annotated 明確指出這是“地理坐標(biāo)（緯度, 經(jīng)度）”。
• 避免了開發(fā)者誤將 (x, y) 像素坐標(biāo)當(dāng)作地理坐標(biāo)使用的問題。
• 可用于構(gòu)建 API 文檔自動生成系統(tǒng)。

最佳實踐

保持注解簡潔

? 推薦做法：

PortNumber = Annotated[int, "TCP/UDP port number (1-65535)"]

? 不推薦做法：

PortNumber = Annotated[int, 
    "This is a port number used in networking. It should be between 1 and 65535. " 
    "Ports below 1024 are privileged. Do not use them unless necessary. "
    "See RFC 793 for more details."
]

?? 建議：元數(shù)據(jù)應(yīng)簡短、精準(zhǔn)，重點說明用途或約束，而不是寫成冗長的文檔。

用于提高可讀性，而非增加復(fù)雜性

如果變量名已經(jīng)足夠清晰，就不需要過度使用 Annotated。

? 合理使用：

TimeoutSeconds = Annotated[float, "超時時間（秒）"]

def fetch_data(url: str, timeout: TimeoutSeconds) -> dict: ...

? 過度使用：

NameStr = Annotated[str, "姓名"]
AgeInt = Annotated[int, "年齡"]

def greet(name: NameStr, age: AgeInt) -> str: ...

?? 理由：name: str 和 age: int 本身就很清晰，加上 Annotated 反而增加了不必要的抽象層。

結(jié)論

typing.Annotated 是 Python 類型系統(tǒng)中的一項強(qiáng)大而靈活的功能。它允許開發(fā)者在不改變類型本身的前提下，為類型附加豐富的語義信息。

通過合理使用 Annotated，你可以：

• ? 提升代碼的可讀性和自文檔性；
• ? 為 IDE 和類型檢查工具提供更多上下文；
• ? 支持高級框架（如 FastAPI、Pydantic）實現(xiàn)字段驗證、序列化等功能；
• ? 構(gòu)建更智能的開發(fā)工具鏈。
  只要遵循“簡潔、實用、增強(qiáng)可讀性”的原則，typing.Annotated 就能成為你編寫高質(zhì)量 Python 代碼的得力助手。

參考資料

Python 官方文檔 - typing.Annotated
PEP 593 – Flexible function and variable annotations（Annotated 的設(shè)計提案）

typing.Annotated 的實際應(yīng)用場景（進(jìn)階）

除了上述基礎(chǔ)用途，Annotated 在現(xiàn)代 Python 框架中有更深層次的應(yīng)用：

? FastAPI 中的依賴注入與元數(shù)據(jù)傳遞

from typing import Annotated
from fastapi import Depends, Query

async def common_params(q: str, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}

def read_items(
    commons: Annotated[dict, Depends(common_params)]
):
    return commons

這里 Depends(…) 作為元數(shù)據(jù)被傳入，F(xiàn)astAPI 能識別并執(zhí)行依賴注入。

? Pydantic v2 中的字段約束

from typing import Annotated
from pydantic import Field

UserId = Annotated[int, Field(ge=1, description="用戶唯一ID")]

class User(BaseModel):
    user_id: UserId

Field(…) 作為元數(shù)據(jù)，被 Pydantic 解析用于數(shù)據(jù)驗證和 OpenAPI 文檔生成。

? 總結(jié)一句話：

typing.Annotated[T, metadata] 讓你的類型不僅能表達(dá)“是什么”，還能表達(dá)“意味著什么”。

它是連接類型系統(tǒng)與業(yè)務(wù)語義的橋梁，是現(xiàn)代 Python 類型編程的重要組成部分。

如果你正在開發(fā)大型項目、API 服務(wù)或團(tuán)隊協(xié)作項目，強(qiáng)烈建議學(xué)習(xí)并適度使用 typing.Annotated 來提升代碼質(zhì)量。

總結(jié)

到此這篇關(guān)于Python中typing.Annotated使用的文章就介紹到這了,更多相關(guān)Python typing.Annotated使用內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！