一、前言

1. 在 Python 開發(fā)中，類型注解是提升代碼可讀性、降低維護(hù)成本的低成本手段——它不影響程序運(yùn)行，卻能讓 IDE 實現(xiàn)智能補(bǔ)全、讓同事快速理解代碼邏輯，更是 dataclass、Pydantic 等常用框架的核心依賴。
2. Python 作為動態(tài)類型語言，變量、函數(shù)參數(shù)的類型全靠“猜測”，這會帶來三個核心問題：
   • 閱讀成本高：需反復(fù)追溯變量用途，才能理解代碼邏輯；
   • 調(diào)試成本高：傳參類型錯誤僅在運(yùn)行時暴露，排查耗時；
   • 開發(fā)效率低：IDE 無法提供精準(zhǔn)補(bǔ)全，寫代碼全靠記憶。

而類型注解的核心價值，就是給代碼“打標(biāo)簽”——僅做類型提示，不強(qiáng)制校驗，卻能解決上述問題。

二、類型注解核心用法

按使用場景可以劃分為變量的類型注解、函數(shù)類型注解、類的類型注解

2.1 變量類型注解

這是最基礎(chǔ)的用法，覆蓋全局變量、函數(shù)內(nèi)局部變量，語法統(tǒng)一且簡單，重點(diǎn)區(qū)分“有無默認(rèn)值”的差異。

1. 無默認(rèn)值的注解（如 age: int）僅存元數(shù)據(jù)，不會創(chuàng)建變量，未賦值直接使用會報錯；
2. 有默認(rèn)值的注解，同時完成“類型標(biāo)記”和“變量賦值”，變量可正常使用；
3. 注解不強(qiáng)制類型匹配（如 age: int = “20” 可運(yùn)行），僅起提示作用。

# 無默認(rèn)值（僅標(biāo)記類型，不創(chuàng)建變量）
變量名: 類型
# 有默認(rèn)值（標(biāo)記類型+賦值，注解與變量共存）
變量名: 類型 = 默認(rèn)值

age:int = 19
# 合法：只聲明類型，不賦值
name: str
# 此時變量還不存在，直接用會報錯
# print(name)  # NameError
# 賦值后，變量才真正存在
name = "張三"
print(name)  # 正常運(yùn)行

2.2 函數(shù)類型注解

重點(diǎn)標(biāo)注「參數(shù)類型」和「返回值類型」，讓函數(shù)用途、輸入輸出一目了然，減少溝通成本

1. 無返回值最好寫 -> None，省略會導(dǎo)致 IDE 提示異常；
2. *args 注解標(biāo)注“元素類型”（如 *args: int 表示所有可變位置參數(shù)都是整數(shù)）；
3. **kwargs 注解標(biāo)注“值的類型”（如 **kwargs: str 表示所有關(guān)鍵字參數(shù)的值為字符串）；

# 僅參數(shù)注解
def 函數(shù)名(參數(shù)1: 類型, 參數(shù)2: 類型 = 默認(rèn)值):
    pass
# 參數(shù)+返回值注解（-> 標(biāo)識返回類型）
def 函數(shù)名(參數(shù)1: 類型, 參數(shù)2: 類型) -> 返回值類型:
    pass

def add(a: int, b: int) -> int:
    return a + b
# 無返回值（必須寫 -> None，不可省略）
def log(msg: str) -> None:
    print(f"日志：{msg}")
# 可變參數(shù)注解（指定內(nèi)部元素類型）
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)

2.3 類的類型注解（dataclass 依賴）

專門用于標(biāo)記「實例屬性」類型，分三種形態(tài)，核心區(qū)分“注解”與“類屬性”的關(guān)系，是 dataclass 框架的核心依賴。

1. 純注解（如 name: str）不生成類屬性，僅存入 __annotations__，用于標(biāo)記未來實例的屬性類型；
2. 注解+默認(rèn)值（如 email: str | None = None），一行完成“類型標(biāo)記+類屬性賦值”；
3. dataclass 正是通過讀取 __annotations__，自動生成 __init__、__repr__ 等方法，無需手動編寫；
4. 實例化后，注解標(biāo)記的屬性會成為實例屬性，優(yōu)先覆蓋同名類屬性。

class 類名:
    # 1. 純注解（僅標(biāo)記實例屬性類型，無類屬性）
    屬性名1: 類型
    # 2. 注解+默認(rèn)值（標(biāo)記類型+創(chuàng)建類屬性，供實例繼承默認(rèn)值）
    屬性名2: 類型 = 默認(rèn)值
    # 3. 普通類屬性（無注解，不進(jìn)入__annotations__）
    屬性名3 = 默認(rèn)值

class User:
    # 純注解：僅標(biāo)記實例屬性類型，無類屬性
    name: str
    age: int
    # 注解+默認(rèn)值：有類型標(biāo)記，同時創(chuàng)建類屬性（默認(rèn)值）
    email: str | None = None  # 實例可覆蓋該默認(rèn)值
    gender: str = "未知"
    # 普通類屬性：無注解，不進(jìn)入__annotations__，所有實例共享
    address = "北京"
# 驗證注解存儲（僅包含帶注解的屬性）
print(User.__annotations__)
# 輸出：{'name': str, 'age': int, 'email': str | None, 'gender': str}

三、類型注解元數(shù)據(jù)的存儲機(jī)制

Python 會自動將所有類型注解收集到特殊的 __annotations__ 字典中，本質(zhì)是一個普通字典，鍵為注解標(biāo)記的對象名稱（變量名、函數(shù)參數(shù)名、類屬性名等），值為對應(yīng)的類型（如 str、int、list[int] 等），供框架、工具讀取使用。

3.1 不同場景下的元數(shù)據(jù)存儲

注解元數(shù)據(jù)的存儲位置，隨注解場景（變量、函數(shù)、類）不同而有所差異

模塊級變量注解存儲

全局（模塊級）變量的注解，會存儲在當(dāng)前模塊對象的 annotations 字典中

# 模塊級變量注解
name: str = "張三"
age: int = 20
score: float | None = 95.5
# 查看模塊級注解元數(shù)據(jù)
print(__annotations__)
# 輸出：{'name': str, 'age': int, 'score': float | None}

函數(shù)注解存儲

函數(shù)的注解（參數(shù)注解、返回值注解），會存儲在函數(shù)對象的 annotations 字典中，同時返回值注解會單獨(dú)對應(yīng)鍵 “return”，參數(shù)注解對應(yīng)各自的參數(shù)名

def add(a: int, b: int) -> int:
    return a + b
# 查看函數(shù)注解元數(shù)據(jù)
print(add.__annotations__)
# 輸出：{'a': int, 'b': int, 'return': int}
# 可變參數(shù)注解的存儲
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)
print(sum_numbers.__annotations__)
# 輸出：{'args': int, 'kwargs': str, 'return': list[int]}

類注解存儲

類內(nèi)的屬性注解（純注解、注解+默認(rèn)值），會存儲在類對象的 annotations 字典中（普通類屬性無注解，不存入）；實例對象本身沒有 annotations，其注解信息繼承自所屬類。

class User:
    name: str  # 純注解
    age: int   # 純注解
    email: str | None = None  # 注解+默認(rèn)值
    gender: str = "未知"       # 注解+默認(rèn)值
    address = "北京"          # 無注解，不存入
# 查看類的注解元數(shù)據(jù)
print(User.__annotations__)
# 輸出：{'name': str, 'age': int, 'email': str | None, 'gender': str}
# 實例無__annotations__，繼承類的注解信息
u = User()
print(hasattr(u, "__annotations__"))  # 輸出：False

3.2 關(guān)鍵注意點(diǎn)

• __annotations__ 是動態(tài)可變的：可手動修改該字典，修改后會影響框架、工具對注解的讀?。ú煌扑]手動修改，易造成混亂）；
• 無默認(rèn)值的變量注解，僅存入 __annotations__，不創(chuàng)建變量（如 age: int 僅在 __annotations__ 中有記錄，未賦值則變量不存在）；
• 框架依賴：dataclass、Pydantic 等框架，核心就是通過讀取 __annotations__ 字典，實現(xiàn)屬性校驗、自動生成方法等功能。

四、常用類型簡寫

到此這篇關(guān)于Python 類型注解核心指南的文章就介紹到這了,更多相關(guān)Python 類型注解內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論