Python作為動態類型語言，變量類型無需提前聲明，這雖然靈活，但也帶來了隱患：代碼可讀性差、類型錯誤要到運行時才暴露、團隊協作時溝通成本高。而類型提示（Type Hints）通過在代碼中標註類型信息，既能保留動態類型的靈活性，又能解決這些痛點。本文從基礎語法到實戰應用，詳解Python類型提示的核心用法，幫你寫出更易讀、更穩定的代碼。
一、為什麼需要類型提示？先看兩個場景
在瞭解語法前，先明白類型提示能解決什麼問題，這是學習的核心動力。
場景1：代碼可讀性差，接手成本高
沒有類型提示時，調用函數需要猜參數類型：
# 無類型提示：data是什麼類型？返回值是什麼類型？
def calculate_total(data):
total = 0
for item in data:
total += item["price"]
return total
# 調用時需要翻函數內部代碼才知道data是"包含price鍵的字典列表"
result = calculate_total([{"name": "蘋果", "price": 5}, {"name": "香蕉", "price": 3}])有了類型提示後，函數定義自帶文檔：
# 有類型提示：一眼知道data是字典列表，返回值是整數
def calculate_total(data: list[dict[str, int]]) -> int:
total = 0
for item in data:
total += item["price"]
return total
# 調用時無需查看函數內部，IDE還會自動提示參數結構
result = calculate_total([{"name": "蘋果", "price": 5}, {"name": "香蕉", "price": 3}])場景2：類型錯誤隱藏深，運行時才暴露
動態類型下，類型錯誤要等到代碼執行到對應位置才會發現：
# 無類型提示：傳入字符串會報錯，但編寫時不提示
def add(a, b):
return a + b
# 開發時無報錯，運行時才拋出TypeError
add(1, "2") # 報錯：unsupported operand type(s) for +: 'int' and 'str'有類型提示後，配合工具能在編寫時就發現錯誤：
def add(a: int, b: int) -> int:
return a + b
# 編寫時IDE會提示：參數2應為int，而非str（提前規避錯誤）
add(1, "2")二、基礎用法：變量、函數與類的類型提示
Python 3.5+引入類型提示，核心語法簡單直觀，無需複雜學習就能上手。
1. 變量的類型提示
變量類型提示用變量名: 類型的格式，支持基本類型、容器類型等：
# 基本類型：整數、字符串、布爾值、浮點數
age: int = 25
name: str = "Alice"
is_active: bool = True
score: float = 98.5
# 容器類型：列表、元組、字典（Python 3.9+支持直接用list/dict等）
# 列表：list[元素類型]
fruits: list[str] = ["apple", "banana", "cherry"]
# 元組：tuple[元素1類型, 元素2類型,...]（元組元素類型固定，長度固定）
user: tuple[str, int] = ("Bob", 30) # 第一個元素是字符串，第二個是整數
# 字典：dict[鍵類型, 值類型]
user_info: dict[str, str] = {"name": "Charlie", "city": "Beijing"}
# 可選類型：用Union表示變量可以是多種類型之一（Python 3.10+可用|簡化）
from typing import Union # Python 3.9及以下需導入
# 方式1：Union（兼容舊版本）
phone: Union[str, int] = "13800138000"
phone = 13800138000 # 也允許
# 方式2：|（Python 3.10+推薦）
phone: str | int = 13800138000
# 空類型：用None表示變量可以是None
from typing import Optional # Python 3.9及以下需導入
# 表示address可以是字符串，也可以是None
address: Optional[str] = None # 等價於 str | None（Python 3.10+）
address = "上海市浦東新區" # 賦值字符串也允許注意：類型提示僅為“提示”，不會改變Python的動態類型特性——即使標註age: int，給age賦值字符串age = "25"也不會報錯（運行時仍允許），但IDE和類型檢查工具會提示警告。
2. 函數的類型提示
函數類型提示包括“參數類型”和“返回值類型”，返回值類型用-> 類型標註：
# 1. 簡單函數：參數和返回值都是基本類型
def add(a: int, b: int) -> int:
return a + b
# 2. 帶默認參數的函數：默認值不影響類型提示
def greet(name: str, greeting: str = "Hello") -> str:
return f"{greeting}, {name}!"
# 3. 不定長參數：*args和**kwargs的類型提示
def print_args(*args: str, **kwargs: int) -> None:
"""
*args：所有位置參數都是字符串
**kwargs：所有關鍵字參數都是整數
返回值：None（無返回值）
"""
for arg in args:
print(arg)
for key, value in kwargs.items():
print(f"{key}: {value}")
# 調用時IDE會提示參數類型
print_args("a", "b", x=1, y=2) # 正確
# print_args(1, 2, x="a") # IDE提示錯誤：args應為str，kwargs應為int
# 4. 函數作為參數：用Callable標註函數類型
from typing import Callable
def apply_func(func: Callable[[int, int], int], a: int, b: int) -> int:
"""
func：參數是兩個int，返回值是int的函數
"""
return func(a, b)
# 定義一個符合Callable類型的函數
def multiply(a: int, b: int) -> int:
return a * b
# 調用apply_func，IDE會驗證func是否符合類型
result = apply_func(multiply, 3, 4) # 正確，返回123. 類的類型提示
類的類型提示包括“實例屬性”和“方法”，實例屬性可在__init__中標註，或直接在類體中標註：
class User:
# 類體中直接標註實例屬性類型（推薦，更直觀）
username: str
age: int
email: Optional[str] # 可選屬性，可能為None
def __init__(self, username: str, age: int, email: str | None = None):
# 初始化屬性，類型與類體標註一致
self.username = username
self.age = age
self.email = email
# 方法的類型提示與普通函數一致
def get_user_info(self) -> dict[str, str | int | None]:
return {
"username": self.username,
"age": self.age,
"email": self.email
}
# 創建實例時，IDE會提示參數類型和順序
user = User(username="alice", age=28, email="alice@example.com")
# 訪問屬性時，IDE知道屬性類型，會自動補全
print(user.username.upper()) # IDE提示upper()方法（因為username是str）三、進階用法：泛型、類型別名與複雜場景
對於複雜數據結構（如自定義容器、通用函數），需要用到泛型（Generics）和類型別名（Type Aliases），讓類型提示更精準。
1. 泛型：處理通用類型的容器
當函數或類需要支持多種元素類型的容器時，用泛型標註“類型參數”，避免重複定義：
from typing import Generic, TypeVar
# 定義類型變量T（表示任意類型）
T = TypeVar("T")
# 1. 泛型函數：支持多種類型的列表反轉
def reverse_list(items: list[T]) -> list[T]:
"""反轉列表，返回與輸入相同元素類型的列表"""
return items[::-1]
# 調用時自動推斷類型
int_list: list[int] = [1, 2, 3]
reversed_int: list[int] = reverse_list(int_list) # 正確，返回int列表
str_list: list[str] = ["a", "b", "c"]
reversed_str: list[str] = reverse_list(str_list) # 正確，返回str列表
# 2. 泛型類：自定義通用容器
class Stack(Generic[T]):
"""通用棧結構，支持任意類型的元素"""
def __init__(self):
self.items: list[T] = []
def push(self, item: T) -> None:
"""壓棧：添加的元素類型與棧的泛型類型一致"""
self.items.append(item)
def pop(self) -> T | None:
"""出棧：返回與泛型類型一致的元素，或None（棧空時）"""
if self.is_empty():
return None
return self.items.pop()
def is_empty(self) -> bool:
return len(self.items) == 0
# 創建int類型的棧
int_stack = Stack[int]()
int_stack.push(1)
int_stack.push(2)
print(int_stack.pop()) # 2（類型為int）
# 創建str類型的棧
str_stack = Stack[str]()
str_stack.push("hello")
# str_stack.push(123) # IDE提示錯誤：應傳入str，而非int泛型的核心是“類型參數化”，讓函數或類擺脱固定類型的束縛，同時保持類型安全。
2. 類型別名：簡化複雜類型
對於重複出現的複雜類型（如list[dict[str, str | int]]），用TypeAlias定義別名，讓代碼更簡潔：
from typing import TypeAlias
# 定義類型別名：表示"用户數據"的複雜類型
UserData: TypeAlias = dict[str, str | int] # 鍵是str，值是str或int
UserList: TypeAlias = list[UserData] # 用户數據列表
# 用別名簡化函數類型提示
def process_users(users: UserList) -> list[str]:
"""處理用户列表，返回用户名列表"""
return [user["name"] for user in users if "name" in user]
# 調用函數，類型提示更清晰
users: UserList = [
{"name": "Alice", "age": 28, "city": "Beijing"},
{"name": "Bob", "age": 30, "city": "Shanghai"}
]
usernames = process_users(users) # 正確，IDE能識別users的類型類型別名不僅簡化代碼，還能提高可維護性——如果後續UserData的結構變化，只需修改別名定義，無需逐個修改函數。
3. Optional與Union的區別
很多人混淆Optional和Union，其實兩者有明確分工：
Optional[T]：表示類型是T或None（等價於Union[T, None]），專門用於“可選值”場景；Union[T1, T2]：表示類型是T1或T2（可多個類型），用於“多種可能類型”場景。
from typing import Optional, Union
# Optional：可選的郵箱（有或無）
def send_email(to: str, subject: str, body: Optional[str] = None) -> None:
if body is None:
body = "無正文"
print(f"發送到：{to}，主題：{subject}，正文：{body}")
# Union：支持多種支付方式（整數金額或字符串優惠券）
def pay(amount: Union[int, str]) -> bool:
if isinstance(amount, int):
print(f"支付{amount}元")
return True
elif isinstance(amount, str):
print(f"使用優惠券：{amount}")
return True
return False四、工具支持：讓類型提示發揮最大價值
類型提示本身不影響代碼運行，但配合工具能實現“類型檢查”“IDE智能提示”等功能，真正提升開發效率。
1. 類型檢查工具：mypy
mypy是Python最流行的類型檢查工具，能靜態分析代碼，在運行前發現類型錯誤：
安裝mypy
pip install mypy示例：用mypy檢查類型錯誤
創建test_type.py文件：
def add(a: int, b: int) -> int:
return a + b
# 錯誤：傳入字符串，與類型提示不符
result = add(1, "2")用mypy檢查：
mypy test_type.py輸出結果（明確指出錯誤位置和原因）：
test_type.py:5: error: Argument 2 to "add" has incompatible type "str"; expected "int"
Found 1 error in 1 file (checked 1 source file)2. IDE智能提示：PyCharm/VS Code
主流IDE（如PyCharm、VS Code）都支持類型提示，能提供：
- 參數提示：輸入函數時，自動顯示參數類型和順序；
- 屬性補全：訪問對象屬性時，只顯示該類型支持的方法（如str類型顯示
upper()，int類型不顯示）； - 錯誤預警：編寫時實時提示類型不匹配的錯誤。
以VS Code為例，編寫帶類型提示的代碼時，IDE會自動補全屬性：
user: dict[str, str | int] = {"name": "Alice", "age": 28}
# 輸入user["name"].後，IDE自動提示str的方法（upper()、strip()等）
print(user["name"].upper())3. 文檔生成：自動生成API文檔
類型提示還能用於自動生成API文檔，工具（如sphinx）會讀取類型提示，生成包含參數和返回值類型的文檔，減少手動編寫文檔的工作量。
五、避坑指南：常見類型提示誤區
1. 誤區1：過度複雜的類型提示
類型提示的目的是“提升可讀性”，而非“炫技”。如果類型提示過於複雜（如嵌套多層泛型），反而會降低代碼可讀性：
# 不好的寫法：類型提示過於複雜，難以理解
from typing import Dict, List, Union
def process_data(data: List[Dict[str, Union[str, List[Dict[str, int]]]]]) -> None:
pass
# 好的寫法：用類型別名簡化
from typing import TypeAlias
DataItem: TypeAlias = dict[str, str | list[dict[str, int]]]
def process_data(data: list[DataItem]) -> None:
pass2. 誤區2：忽略動態類型的靈活性
類型提示是“提示”而非“強制”，不要為了嚴格的類型檢查，犧牲Python的動態特性。例如，當函數需要支持多種類型時，用Union或Any（表示任意類型）更合適：
from typing import Any
# 支持任意可迭代類型的函數（用Any保持靈活性）
def print_iterable(items: Any) -> None:
for item in items:
print(item)
# 調用時支持列表、元組、生成器等，不被嚴格類型束縛
print_iterable([1, 2, 3])
print_iterable((4, 5, 6))
