快捷導(dǎo)航

Python中typing.Annotated使用全面指南

更新時間：2025年12月01日 08:48:23 作者：SunnyRivers

在Python中typing.Annotated是一種用于向類型提示添加元數(shù)據(jù)的方式,這篇文章主要介紹了Python中typing.Annotated使用的相關(guān)資料,文中通過代碼介紹的非常詳細(xì),需要的朋友可以參考下

前言

Python 是一種動態(tài)類型語言，這意味著變量的類型是在運(yùn)行時才確定的。雖然這種靈活性帶來了便利，但在大型項(xiàng)目中，它也可能導(dǎo)致代碼難以理解和維護(hù)。為了改善這一點(diǎn)，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í)際的數(shù)據(jù)類型，比如 int、str 或自定義類；
后續(xù)參數(shù)是任意數(shù)量的元數(shù)據(jù)對象（metadata），這些對象可以是任何 Python 對象（字符串、字典、函數(shù)、類等），用于提供關(guān)于該類型的附加信息。

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

這些元數(shù)據(jù)本身不會影響程序運(yùn)行時的行為（即不參與類型檢查邏輯），但可以被靜態(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 類型。
運(yùn)行時，user_id 依然是整數(shù)；但在類型檢查或文檔生成時，工具可以知道這個 int 實(shí)際上代表“用戶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” 這一語義信息，用于生成文檔、驗(yàn)證輸入來源等。

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

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

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

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）用來實(shí)現(xiàn)驗(yàn)證邏輯。

常見實(shí)踐

使用 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ā)體驗(yàn)。

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

from typing import Annotated, Tuple

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

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

?? 詳解：

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

最佳實(shí)踐

保持注解簡潔

? 推薦做法：

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)，重點(diǎ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)中的一項(xiàng)強(qiáng)大而靈活的功能。它允許開發(fā)者在不改變類型本身的前提下，為類型附加豐富的語義信息。

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

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

參考資料

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

typing.Annotated 的實(shí)際應(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ù)驗(yàn)證和 OpenAPI 文檔生成。

? 總結(jié)一句話：