一、前言

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

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

二、類型注解核心用法

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

2.1 變量類型注解

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

1. 無默認(rèn)值的注解（如 age: int）僅存元數(shù)據(jù)，不會(huì)創(chuàng)建變量，未賦值直接使用會(huì)報(bào)錯(cuò)；
2. 有默認(rèn)值的注解，同時(shí)完成“類型標(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
# 此時(shí)變量還不存在，直接用會(huì)報(bào)錯(cuò)
# print(name)  # NameError
# 賦值后，變量才真正存在
name = "張三"
print(name)  # 正常運(yùn)行

2.2 函數(shù)類型注解

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

1. 無返回值最好寫 -> None，省略會(huì)導(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)識(shí)返回類型）
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)記「實(shí)例屬性」類型，分三種形態(tài)，核心區(qū)分“注解”與“類屬性”的關(guān)系，是 dataclass 框架的核心依賴。

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

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

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

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

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

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

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

模塊級(jí)變量注解存儲(chǔ)

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

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

函數(shù)注解存儲(chǔ)

函數(shù)的注解（參數(shù)注解、返回值注解），會(huì)存儲(chǔ)在函數(shù)對(duì)象的 annotations 字典中，同時(shí)返回值注解會(huì)單獨(dú)對(duì)應(yīng)鍵 “return”，參數(shù)注解對(duì)應(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ù)注解的存儲(chǔ)
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)
print(sum_numbers.__annotations__)
# 輸出：{'args': int, 'kwargs': str, 'return': list[int]}

類注解存儲(chǔ)

類內(nèi)的屬性注解（純注解、注解+默認(rèn)值），會(huì)存儲(chǔ)在類對(duì)象的 annotations 字典中（普通類屬性無注解，不存入）；實(shí)例對(duì)象本身沒有 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}
# 實(shí)例無__annotations__，繼承類的注解信息
u = User()
print(hasattr(u, "__annotations__"))  # 輸出：False

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

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

四、常用類型簡(jiǎn)寫

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

最新評(píng)論