Python 类型注解（Type Hints）完全指南：从基础标注到 Pydantic 数据验证 | Python 进阶核心知识

1
def process(data):
2
    result = []
3
    for item in data:
4
        result.append(item * 2)
5
    return result

1
def process(data: list[int]) -> list[int]:
2
    result: list[int] = []
3
    for item in data:
4
        result.append(item * 2)
5
    return result

1
# 基础变量注解
2
name: str = "Alice"
3
age: int = 30
4
height: float = 1.75
5
is_active: bool = True
6

7
# 容器类型注解（Python 3.9+ 可直接使用小写类型）
8
names: list[str] = ["Alice", "Bob"]
9
scores: dict[str, int] = {"Alice": 90, "Bob": 85}
10
point: tuple[int, int] = (10, 20)
11
unique_ids: set[int] = {1, 2, 3}
12

13
# 无需赋值，仅声明类型（用于模块级或类级常量）
14
MAX_CONNECTIONS: int
15
DEFAULT_TIMEOUT: float = 30.0

1
# 参数注解和返回值注解
2
def greet(name: str, times: int = 1) -> str:
3
    return f"Hello, {name}! " * times
4

5
# 多返回值注解（返回元组）
6
def get_user_info(user_id: int) -> tuple[str, int, bool]:
7
    return ("Alice", 30, True)
8

9
# 无返回值
10
def log_message(msg: str) -> None:
11
    print(f"[LOG] {msg}")
12

13
# 异步函数注解
14
async def fetch_data(url: str) -> dict[str, str]:
15
    # ...
16
    return {"status": "ok"}

1
from typing import Optional
2

3
# Optional[str] 表示 name 可以是字符串或 None
4
def find_user(user_id: int) -> Optional[str]:
5
    users = {1: "Alice", 2: "Bob"}
6
    return users.get(user_id)  # .get() 找不到时返回 None
7

8
result = find_user(1)   # "Alice"
9
result = find_user(99)  # None
10

11
# Python 3.10+ 新语法：X | None（推荐）
12
def find_user_new(user_id: int) -> str | None:
13
    users = {1: "Alice", 2: "Bob"}
14
    return users.get(user_id)

1
from typing import Union
2

3
# 值可以是 int 或 str
4
def process_id(value: Union[int, str]) -> str:
5
    if isinstance(value, int):
6
        return f"ID-{value:04d}"
7
    return value.upper()
8

9
# Python 3.10+ 新语法：X | Y（推荐）
10
def process_id_new(value: int | str) -> str:
11
    if isinstance(value, int):
12
        return f"ID-{value:04d}"
13
    return value.upper()
14

15
# 多类型联合
16
def parse_value(value: int | float | str | None) -> float | None:
17
    if value is None:
18
        return None
19
    return float(value)

1
# ❌ 错误：Optional[list] 表示列表本身可能为 None
2
#          并不表示列表内的元素可能为 None
3
def bad_example(data: Optional[list[int]]) -> int:
4
    if data is None:
5
        return 0
6
    return sum(data)
7

8
# ✅ 正确：如果列表内元素也可能为 None
9
from typing import Optional
10

11
def good_example(data: list[Optional[int]] | None) -> int:
12
    if data is None:
13
        return 0
14
    return sum(x for x in data if x is not None)
15

16
# ✅ 更清晰：使用 | None 语法
17
def clear_example(data: list[int | None] | None) -> int:
18
    if data is None:
19
        return 0
20
    return sum(x for x in data if x is not None)

1
# 没有泛型：返回值类型丢失
2
def first(items: list) -> ???:
3
    return items[0]
4

5
# 用 Any：等于没有类型注解
6
from typing import Any
7
def first(items: list[Any]) -> Any:
8
    return items[0]

1
from typing import TypeVar
2

3
T = TypeVar('T')
4

5
def first(items: list[T]) -> T:
6
    return items[0]
7

8
# 现在 mypy 知道：
9
result1 = first([1, 2, 3])       # result1 的类型是 int
10
result2 = first(["a", "b", "c"]) # result2 的类型是 str

1
from typing import TypeVar
2

3
# T 必须是 Number 的子类
4
from numbers import Number
5

6
N = TypeVar('N', bound=Number)
7

8
def sum_values(values: list[N]) -> N:
9
    total: N = values[0]
10
    for v in values[1:]:
11
        total = total + v
12
    return total
13

14
result = sum_values([1, 2, 3])        # 返回 int
15
result = sum_values([1.5, 2.5, 3.5])  # 返回 float
16

17
# ❌ 错误：str 不是 Number 的子类
18
# result = sum_values(["a", "b"])

1
from typing import TypeVar
2

3
# T 只能是 str 或 bytes
4
S = TypeVar('S', str, bytes)
5

6
def longest(a: S, b: S) -> S:
7
    return a if len(a) >= len(b) else b
8

9
result1 = longest("hello", "world")      # 返回 str
10
result2 = longest(b"hello", b"world")    # 返回 bytes
11

12
# ❌ 错误：int 不在允许的范围内
13
# result3 = longest(123, 456)

1
from typing import TypeVar, Generic
2

3
T = TypeVar('T')
4

5
class Stack(Generic[T]):
6
    """泛型栈：元素类型在实例化时确定"""
7

8
    def __init__(self) -> None:
9
        self._items: list[T] = []
10

11
    def push(self, item: T) -> None:
12
        self._items.append(item)
13

14
    def pop(self) -> T:
15
        if not self._items:
16
            raise IndexError("pop from empty stack")
17
        return self._items.pop()
18

19
    def peek(self) -> T:
20
        if not self._items:
21
            raise IndexError("peek from empty stack")
22
        return self._items[-1]
23

24
    def __len__(self) -> int:
25
        return len(self._items)
26

27
# 使用：类型在实例化时确定
28
int_stack: Stack[int] = Stack()
29
int_stack.push(1)
30
int_stack.push(2)
31
value: int = int_stack.pop()  # mypy 知道返回 int
32

33
str_stack: Stack[str] = Stack()
34
str_stack.push("hello")
35
text: str = str_stack.pop()   # mypy 知道返回 str

1
from typing import TypeVar, K, V
2

3
K = TypeVar('K')
4
V = TypeVar('V')
5

6
def invert_dict(d: dict[K, V]) -> dict[V, K]:
7
    """反转字典的键和值"""
8
    return {v: k for k, v in d.items()}
9

10
def merge_dicts(d1: dict[K, V], d2: dict[K, V]) -> dict[K, V]:
11
    """合并两个字典，后者的值优先"""
12
    result: dict[K, V] = {}
13
    result.update(d1)
14
    result.update(d2)
15
    return result
16

17
# 使用
18
original = {"Alice": 90, "Bob": 85}
19
inverted = invert_dict(original)  # {90: "Alice", 85: "Bob"}

1
from typing import Callable
2

3
# Callable[[参数类型...], 返回类型]
4
def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
5
    return func(a, b)
6

7
# 使用
8
result = apply(lambda x, y: x + y, 3, 5)      # 8
9
result = apply(lambda x, y: x * y, 3, 5)      # 15
10

11
# 无参数的回调
12
def run_callback(callback: Callable[[], None]) -> None:
13
    callback()
14

15
# 可变参数的回调（不推荐，但有时需要）
16
from typing import Any
17
def flexible_call(func: Callable[..., Any], *args: Any) -> Any:
18
    return func(*args)

1
from typing import Callable
2

3
# 高阶函数：接收函数，返回函数
4
def multiply_by(factor: int) -> Callable[[int], int]:
5
    """返回一个将输入乘以 factor 的函数"""
6
    def multiplier(x: int) -> int:
7
        return x * factor
8
    return multiplier
9

10
double = multiply_by(2)
11
triple = multiply_by(3)
12

13
print(double(5))  # 10
14
print(triple(5))  # 15
15

16
# 策略模式：用 Callable 类型实现
17
type SortStrategy = Callable[[list[int]], list[int]]
18

19
def sort_ascending(data: list[int]) -> list[int]:
20
    return sorted(data)
21

22
def sort_descending(data: list[int]) -> list[int]:
23
    return sorted(data, reverse=True)
24

25
def process_data(data: list[int], strategy: SortStrategy) -> list[int]:
26
    return strategy(data)
27

28
result1 = process_data([3, 1, 2], sort_ascending)   # [1, 2, 3]
29
result2 = process_data([3, 1, 2], sort_descending)  # [3, 2, 1]

1
# Python 3.12+ 新语法
2
type Vector = list[float]
3
type Matrix = list[Vector]
4

5
# 旧语法
6
from typing import TypeAlias
7
Vector: TypeAlias = list[float]
8
Matrix: TypeAlias = list[Vector]
9

10
# 泛型类型别名（3.12+）
11
type ListOrSet[T] = list[T] | set[T]
12

13
def unique_items(data: ListOrSet[int]) -> list[int]:
14
    if isinstance(data, list):
15
        return list(set(data))
16
    return list(data)

1
from typing import TypedDict
2

3
# 定义带类型的字典结构
4
class UserInfo(TypedDict):
5
    name: str
6
    age: int
7
    email: str
8
    is_active: bool
9

10
# 使用：就像普通字典，但 IDE 会提示键名和类型
11
def create_user(name: str, age: int) -> UserInfo:
12
    return {
13
        "name": name,
14
        "age": age,
15
        "email": f"{name.lower()}@example.com",
16
        "is_active": True,
17
    }
18

19
user: UserInfo = create_user("Alice", 30)
20
print(user["name"])       # "Alice"
21
print(user["age"])        # 30
22

23
# mypy 会检查键是否完整、类型是否匹配
24
# user = {"name": "Bob"}  # ❌ mypy 报错：缺少 age, email, is_active

1
from typing import TypedDict, Required, NotRequired
2

3
# Python 3.11+：可选键
4
class ApiConfig(TypedDict):
5
    host: str
6
    port: int
7
    # 可选键：可以不存在
8
    timeout: NotRequired[float]
9
    # 必填键（用于覆盖 total=False 的默认行为）
10
    api_key: Required[str]
11

12
# 使用
13
config: ApiConfig = {
14
    "host": "localhost",
15
    "port": 8080,
16
    "api_key": "secret",
17
    # timeout 可以不提供
18
}
19

20
# 函数式定义（不推荐，可读性差）
21
from typing import TypedDict
22
Movie = TypedDict("Movie", {"title": str, "year": int, "rating": float})
23

24
movie: Movie = {"title": "Inception", "year": 2010, "rating": 8.8}

1
from typing import NamedTuple
2

3
class Point(NamedTuple):
4
    x: float
5
    y: float
6
    label: str = "origin"  # 带默认值
7

8
# 使用：既可按位置访问，也可按名称访问
9
p = Point(3.0, 4.0, "A")
10
print(p.x)        # 3.0
11
print(p[0])       # 3.0
12
print(p.label)    # "A"
13

14
# 不可变
15
# p.x = 5.0  # ❌ AttributeError
16

17
# 解包
18
x, y, label = p
19

20
# 作为函数返回值（比 tuple 更清晰）
21
def parse_coordinates(text: str) -> Point:
22
    parts = text.split(",")
23
    return Point(float(parts[0]), float(parts[1]), parts[2])

1
from typing import NamedTuple, TypedDict
2
from dataclasses import dataclass
3

4
# NamedTuple：不可变，轻量，可解包
5
class PointNT(NamedTuple):
6
    x: float
7
    y: float
8

9
# dataclass：可变（默认），功能更丰富
10
@dataclass
11
class PointDC:
12
    x: float
13
    y: float
14
    def distance_to_origin(self) -> float:
15
        return (self.x ** 2 + self.y ** 2) ** 0.5
16

17
# TypedDict：用于字典数据，不是类
18
class PointTD(TypedDict):
19
    x: float
20
    y: float

1
from typing import Protocol
2

3
# 定义协议（接口）
4
class SupportsClose(Protocol):
5
    def close(self) -> None:
6
        ...
7

8
class SupportsRead(Protocol):
9
    def read(self, size: int = -1) -> str:
10
        ...
11

12
# 任何有 close() 方法的对象都满足 SupportsClose
13
# 不需要显式继承
14
def cleanup(resource: SupportsClose) -> None:
15
    resource.close()
16

17
# 文件对象有 close 方法，满足协议
18
f = open("test.txt", "w")
19
cleanup(f)  # ✅ mypy 认可
20

21
# 自定义类只要有 close 方法就行
22
class CustomResource:
23
    def close(self) -> None:
24
        print("Custom cleanup")
25

26
cleanup(CustomResource())  # ✅ 也满足

1
from typing import Protocol, Iterator
2

3
class Iterable(Protocol):
4
    def __iter__(self) -> Iterator:
5
        ...
6

7
class Serializable(Protocol):
8
    def to_dict(self) -> dict:
9
        ...
10

11
def process_iterable(items: Iterable) -> list:
12
    return [item for item in items]
13

14
def serialize(obj: Serializable) -> str:
15
    import json
16
    return json.dumps(obj.to_dict())
17

18
# 自定义类自动满足协议
19
class UserCollection:
20
    def __init__(self, users: list[str]) -> None:
21
        self.users = users
22

23
    def __iter__(self) -> Iterator:
24
        return iter(self.users)
25

26
# UserCollection 满足 Iterable 协议（有 __iter__ 方法）
27
process_iterable(UserCollection(["Alice", "Bob"]))  # ✅

1
from typing import Protocol, runtime_checkable
2

3
@runtime_checkable
4
class Drawable(Protocol):
5
    def draw(self) -> str:
6
        ...
7

8
class Circle:
9
    def draw(self) -> str:
10
        return "Drawing circle"
11

12
class Square:
13
    def draw(self) -> str:
14
        return "Drawing square"
15

16
class Text:
17
    pass  # 没有 draw 方法
18

19
# 运行时检查
20
print(isinstance(Circle(), Drawable))   # True
21
print(isinstance(Square(), Drawable))   # True
22
print(isinstance(Text(), Drawable))     # False
23

24
# 根据协议过滤对象
25
def render_all(items: list) -> None:
26
    for item in items:
27
        if isinstance(item, Drawable):
28
            print(item.draw())
29

30
render_all([Circle(), Square(), Text(), "string"])
31
# Drawing circle
32
# Drawing square

1
[mypy]
2
python_version = 3.12
3
warn_return_any = True
4
warn_unused_configs = True
5
disallow_untyped_defs = True
6
disallow_incomplete_defs = True
7
check_untyped_defs = True
8
no_implicit_optional = True
9
warn_redundant_casts = True
10
warn_unused_ignores = True
11

12
# 对特定模块放宽规则
13
[mypy-tests.*]
14
disallow_untyped_defs = False
15

16
[mypy-third_party_lib.*]
17
ignore_missing_imports = True

1
# ❌ 错误 1：返回值类型不匹配
2
def get_value() -> int:
3
    return "hello"  # error: Incompatible return value type (got "str", expected "int")
4

5
# ✅ 修复
6
def get_value() -> str:
7
    return "hello"
8

9
# ❌ 错误 2：参数类型不匹配
10
def add(a: int, b: int) -> int:
11
    return a + b
12

13
add("1", "2")  # error: Argument 1 to "add" has incompatible type "str"; expected "int"
14

15
# ✅ 修复
16
add(1, 2)
17

18
# ❌ 错误 3：Optional 类型未处理 None
19
from typing import Optional
20

21
def get_name() -> Optional[str]:
22
    return None
23

24
name = get_name()
25
print(name.upper())  # error: Item "None" of "Optional[str]" has no attribute "upper"
26

27
# ✅ 修复：先检查 None
28
if name is not None:
29
    print(name.upper())
30

31
# ❌ 错误 4：列表类型不统一
32
def process(data: list[int]) -> int:
33
    return sum(data)
34

35
process([1, "2", 3])  # error: List item 1 has incompatible type "str"; expected "int"
36

37
# ✅ 修复
38
process([1, 2, 3])

1
# 类型忽略：临时跳过某行的类型检查
2
result = some_untyped_func()  # type: ignore
3

4
# 更精确的忽略（mypy 特定）
5
result = some_untyped_func()  # type: ignore[return-value]
6

7
# cast：手动告诉 mypy 类型（不改变运行时行为）
8
from typing import cast, Any
9

10
raw_data: Any = get_external_data()
11
data = cast(dict[str, int], raw_data)
12
# mypy 现在认为 data 是 dict[str, int]
13

14
# TYPE_CHECKING：仅在类型检查时导入
15
from typing import TYPE_CHECKING
16

17
if TYPE_CHECKING:
18
    from mymodule import HeavyClass  # 运行时不导入，仅用于类型注解
19

20
def process(obj: "HeavyClass") -> None:
21
    ...

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5
    name: str
6
    email: str
7
    age: int
8
    is_active: bool = True
9

10
# 正常创建：自动类型转换
11
user = User(id="123", name="Alice", email="alice@example.com", age="30")
12
print(user.id)    # 123（字符串 "123" 自动转为 int）
13
print(user.age)   # 30
14
print(user.is_active)  # True（默认值）
15

16
# 序列化
17
print(user.model_dump())
18
# {'id': 123, 'name': 'Alice', 'email': 'alice@example.com', 'age': 30, 'is_active': True}
19

20
print(user.model_dump_json())
21
# '{"id":123,"name":"Alice","email":"alice@example.com","age":30,"is_active":true}'
22

23
# 验证失败：抛出 ValidationError
24
from pydantic import ValidationError
25

26
try:
27
    bad_user = User(id="not_a_number", name="Bob", email="bob@example.com", age=25)
28
except ValidationError as e:
29
    print(e.errors())
30
    # [{'type': 'int_parsing', 'loc': ('id',), 'msg': 'Input should be a valid integer...', ...}]

1
from pydantic import BaseModel, Field, EmailStr, field_validator
2

3
class Product(BaseModel):
4
    name: str = Field(..., min_length=1, max_length=100, description="产品名称")
5
    price: float = Field(..., gt=0, description="价格必须大于0")
6
    quantity: int = Field(default=0, ge=0, description="库存不能为负")
7
    tags: list[str] = Field(default_factory=list, max_length=10)
8

9
    # 字段验证器
10
    @field_validator("name")
11
    @classmethod
12
    def name_must_not_be_empty(cls, v: str) -> str:
13
        if not v.strip():
14
            raise ValueError("产品名称不能为空")
15
        return v.strip()
16

17
    @field_validator("price")
18
    @classmethod
19
    def price_must_be_reasonable(cls, v: float) -> float:
20
        if v > 1000000:
21
            raise ValueError("价格异常过高，请检查")
22
        return v
23

24
# 使用
25
product = Product(name="  Laptop  ", price=999.99, quantity=50, tags=["electronics", "computer"])
26
print(product.name)      # "Laptop"（自动 strip）
27
print(product.price)     # 999.99
28

29
# 验证失败示例
30
try:
31
    Product(name="", price=-10, quantity=-5)
32
except ValidationError as e:
33
    for error in e.errors():
34
        print(f"{error['loc']}: {error['msg']}")

1
from pydantic import BaseModel
2
from datetime import datetime
3
from typing import Optional
4

5
class Address(BaseModel):
6
    street: str
7
    city: str
8
    zip_code: str
9
    country: str = "China"
10

11
class OrderItem(BaseModel):
12
    product_id: int
13
    name: str
14
    price: float
15
    quantity: int
16

17
class Order(BaseModel):
18
    order_id: str
19
    customer_name: str
20
    items: list[OrderItem]
21
    shipping_address: Address
22
    created_at: datetime
23
    note: Optional[str] = None
24

25
    @property
26
    def total(self) -> float:
27
        return sum(item.price * item.quantity for item in self.items)
28

29
# 从 JSON 创建（模拟 API 响应）
30
json_data = {
31
    "order_id": "ORD-2026-001",
32
    "customer_name": "Alice",
33
    "items": [
34
        {"product_id": 1, "name": "Laptop", "price": 999.99, "quantity": 1},
35
        {"product_id": 2, "name": "Mouse", "price": 29.99, "quantity": 2},
36
    ],
37
    "shipping_address": {
38
        "street": "123 Main St",
39
        "city": "Shanghai",
40
        "zip_code": "200000",
41
    },
42
    "created_at": "2026-06-19T10:30:00",
43
}
44

45
order = Order.model_validate(json_data)
46
print(order.order_id)              # "ORD-2026-001"
47
print(order.shipping_address.city)  # "Shanghai"
48
print(order.created_at)             # 2026-06-19 10:30:00
49
print(order.total)                  # 1059.97

1
from pydantic import BaseModel, ConfigDict
2

3
class Config(BaseModel):
4
    # Pydantic v2 配置
5
    model_config = ConfigDict(
6
        # 允许从数据库 ORM 对象创建
7
        from_attributes=True,
8
        # 禁止额外字段
9
        extra="forbid",
10
        # 允许从字段名别名映射
11
        populate_by_name=True,
12
        # 大小写不敏感
13
        str_to_lower=False,
14
    )
15

16
    host: str
17
    port: int
18
    debug: bool = False
19

20
# 从 ORM 对象创建
21
class DBConfig:
22
    def __init__(self):
23
        self.host = "localhost"
24
        self.port = 5432
25
        self.debug = True
26

27
db_obj = DBConfig()
28
config = Config.model_validate(db_obj)
29
print(config.host)   # "localhost"
30
print(config.port)   # 5432
31

32
# 模型更新（返回新实例，不改原对象）
33
updated = config.model_copy(update={"port": 8080})
34
print(updated.port)  # 8080
35
print(config.port)   # 5432（原对象不变）

1
# ❌ 错误：可变默认值（经典 Python 陷阱，与类型注解无关但容易混淆）
2
def add_item(item: str, items: list[str] = []) -> list[str]:
3
    items.append(item)
4
    return items
5

6
# ✅ 正确：使用 None 作为默认值
7
from typing import Optional
8

9
def add_item(item: str, items: Optional[list[str]] = None) -> list[str]:
10
    if items is None:
11
        items = []
12
    items.append(item)
13
    return items

1
# ❌ Any 等于没有类型注解
2
from typing import Any
3

4
def process(data: Any) -> Any:
5
    return data
6

7
# ✅ 尽量使用具体类型或泛型
8
from typing import TypeVar
9

10
T = TypeVar('T')
11

12
def process(data: T) -> T:
13
    return data
14

15
# 如果确实不知道类型，用 object 比 Any 更好
16
def log_data(data: object) -> None:
17
    print(data)  # object 类型，mypy 不会报错但不允许调用任意方法

1
# 类型注解不会在运行时阻止错误类型
2
def add(a: int, b: int) -> int:
3
    return a + b
4

5
# 运行时不会报错（Python 是动态类型语言）
6
result = add("hello", "world")  # "helloworld"
7
# 只有 mypy 才会发现这个错误

1
# ❌ 错误：类定义中引用自身时，类还未定义完成
2
class Node:
3
    def __init__(self, value: int, next: Node) -> None:  # NameError: name 'Node' is not defined
4
        self.value = value
5
        self.next = next
6

7
# ✅ 修复 1：使用字符串引用（前向引用）
8
class Node:
9
    def __init__(self, value: int, next: "Node") -> None:
10
        self.value = value
11
        self.next = next
12

13
# ✅ 修复 2：Python 3.11+ 使用 from __future__
14
from __future__ import annotations
15

16
class Node:
17
    def __init__(self, value: int, next: Node) -> None:  # 现在可以了
18
        self.value = value
19
        self.next = next

1
# Python 3.8 及更早：需要从 typing 导入
2
from typing import List, Dict, Tuple, Set
3
items: List[int] = [1, 2, 3]
4
mapping: Dict[str, int] = {"a": 1}
5

6
# Python 3.9+：可以直接使用内置类型（推荐）
7
items: list[int] = [1, 2, 3]
8
mapping: dict[str, int] = {"a": 1}
9

10
# Python 3.9 之前的泛型类型别名
11
from typing import Union, Optional
12
value: Optional[int] = None  # 等价于 Union[int, None]
13

14
# Python 3.10+：可以直接用 | 语法（推荐）
15
value: int | None = None