类型注解

一、前言：为什么 Python 也需要“类型约束感”？

Python 天生就是一门“写起来随心所欲”的语言。不用声明类型，脚本几十行就能跑起来。可一旦项目超过 1000 行，或者需要多人协作开发后端 API，这种“自由”很快就会变成负担。

举一个真实的小例子：同事优化了登录接口返回的 user_meta 字段，把里面的 level 从 int 悄悄改成了带进度条的 dict。结果导出 Excel 的脚本直接崩了一串 TypeError: unsupported operand type(s) for +: 'dict' and 'int'，排查了半个小时 Git 记录才找到漏改的那一行。

更大的痛点其实藏在日常开发里：

  • 变量猜谜大会：接手别人的函数，参数叫 data，返回值叫 result——它到底是 list？dict？还是随时可能为 None 的炸弹？
  • IDE 退化：PyCharm / VS Code 连最基本的自动补全都弹不出来，只能靠人肉记忆类名、方法名。
  • 全靠测试兜底：很多隐性 Bug（比如字典里 key 的类型传错）只能在特定输入下才会暴露。

类型注解（Type Hints） 就是解决这些痛点的“轻量解药”。它完全不改变 Python 的动态特性（解释器在运行时仍然不做强制检查），只是通过“元数据”告诉开发工具和协作伙伴：这里该传什么，那里会返回什么。

二、基础篇：给变量和函数“贴标签”

核心语法非常简单：

  • 变量名后面加 : 再加类型；
  • 函数返回值前面加 -> 再加类型。

1. 单值变量与基础函数

# 单值变量（Python 3.6+ 支持直接标注）
user_name: str = "DaomanLab"
user_level: int = 5
is_member: bool = True

# 带输入输出注解的函数
def generate_greeting(name: str, level: int) -> str:
    """生成会员专属欢迎语"""
    if level >= 5:
        return f"🎉 钻石会员 {name} 下午好！"
    return f"👋 普通会员 {name} 下午好！"

# ⚠️ 下面这行代码静态检查会报错，但解释器仍然可以执行
# generate_greeting(123, "Gold")

💡 一句话总结：类型注解就像贴在代码上的“便利签”，开发工具（比如 mypy、PyCharm）会读这些标签来帮我们检查错误，但 Python 解释器本身不看它们，所以不影响运行。

三、进阶篇：容器、多状态值的标注

处理 list、dict 这类容器，或者“可能是 A 也可能是 B”的值时，我们需要借助 typing 模块提供的工具。
注意：从 Python 3.9 开始，很多常用工具已经可以直接用小写形式了，无需从 typing 导入。

1. 常用容器类型

# ✅ Python 3.9+ 推荐的内置写法（完全不需要导入）
price_list: list[float] = [199.9, 299.9, 399.9]
course_dict: dict[str, bool | float] = {"Python": True, "price": 99.9}
site_coords: tuple[int, int, str] = (30, 120, "Hangzhou")

# 📝 兼容旧版本（Python < 3.9）的写法
from typing import List, Dict, Tuple
old_price_list: List[float] = [1.1, 2.2]
old_course_dict: Dict[str, bool | float] = {"Java": False}

2. 多状态与可空值

  • 联合类型（Union）：当某个值是“A 或者 B”时使用；
  • 可选类型（Optional）：当某个值是“A 或者 None”时使用（本质就是 Union[A, None] 的缩写）。
from typing import Union, Optional

# 📝 兼容性写法（3.5 - 3.10 通用）
def fetch_course(course_id: Union[int, str]) -> Optional[dict]:
    """支持数字 ID 或字符串 ID 查课程，查不到返回 None"""
    mock_db = {1: "Python进阶", "course-02": "FastAPI入门"}
    if course_id in mock_db:
        return {"title": mock_db[course_id], "status": "published"}
    return None

# ✅ Python 3.10+ 极简写法：用 | 替代 Union，直接写 None 替代 Optional
def fetch_course_v2(course_id: int | str) -> dict | None:
    mock_db = {1: "Python进阶", "course-02": "FastAPI入门"}
    return {"title": mock_db[course_id], "status": "published"} if course_id in mock_db else None

🎯 为什么推荐新式写法？
int | str 比 Union[int, str] 更短、更直观，而且完全不需要 import，减少心智负担。

四、核心篇：类、回调函数与 Pydantic 模型

1. 标注回调函数（Callable）

Python 经常需要把函数当成参数传递（比如排序的 key、异步框架的回调），这时可以用 Callable 来标注。

from typing import Callable

# 标注规则：Callable[[参数1类型, 参数2类型, ...], 返回值类型]
def apply_math_op(a: int, b: int, op_func: Callable[[int, int], int]) -> int:
    return op_func(a, b)

# 传加法 lambda
print(apply_math_op(1, 2, lambda x, y: x + y))  # 输出 3
# 传乘法 lambda
print(apply_math_op(3, 4, lambda x, y: x * y))  # 输出 12

⚠️ 小心箭头：Callable[[int, int], int] 中第一个方括号是参数列表的类型，第二个是返回值类型，不要搞混。

2. Pydantic 模型（后端开发的“黄金搭档”）

如果你在写 FastAPI 接口，一定会遇到 Pydantic。它把类型注解直接变成了自动数据校验规则，甚至能一键生成 API 文档！

from pydantic import BaseModel

# 1. 定义一个“课程创建请求”的模型
class CourseCreate(BaseModel):
    title: str          # 必填字段
    price: float        # 必填字段
    is_published: bool = False  # 带默认值的选填字段

# 2. 模拟 FastAPI 接口逻辑
def create_course_api(req_data: CourseCreate):
    # Pydantic 会自动帮你做这些事：
    # ✅ 检查前端 JSON 是否缺了必填字段
    # ✅ 检查字段类型（比如 price 传了 "abc" 会直接报错）
    # ✅ 把 JSON 自动转成 Python 对象，支持点语法访问
    print(f"✅ 课程创建成功：{req_data.title}，定价：{req_data.price}")

# 3. 测试一下（正常输入）
valid_req = CourseCreate(title="Vue3入门", price=49.9)
create_course_api(valid_req)

CourseCreate(title="Vue3入门") 会立即触发校验错误，因为缺少必填的 price 字段——这类错误在开发阶段就能被发现，而不是等到线上才爆炸。

五、工程实践：别让类型注解变成负担

类型注解虽好，过度使用反而会拖慢开发节奏。分享三个实用建议：

1. 别给“一眼能看出来”的局部变量加注解

循环里的 i、函数内部简单转换的 sorted_list 这类变量，IDE 完全能自动推断，根本不需要手动标注。

# ❌ 过度注解（完全没必要）
nums: list[int] = [3, 1, 2]
sorted_nums: list[int] = sorted(nums)
for i: int in range(len(sorted_nums)):
    print(sorted_nums[i])

# ✅ 简洁写法（IDE 照样自动补全）
nums = [3, 1, 2]
sorted_nums = sorted(nums)
for i in range(len(sorted_nums)):
    print(sorted_nums[i])

原则：只给函数签名、类属性、公共 API 加注解，局部变量交给类型推断。

2. 用 Any 当成“逃生舱”

当你实在无法确定类型时（比如解析极度复杂的嵌套 JSON、对接黑盒第三方接口），可以用 Any 明确告诉静态检查工具：“这里先放我一马”。

from typing import Any

def parse_weird_json(raw: str) -> Any:
    """解析第三方的超复杂 JSON，暂时无法确定返回类型"""
    import json
    return json.loads(raw)

Any 不是偷懒的借口，而是承认“当前信息不足，后续再细化”的诚实信号。

3. 配合 mypy 做“静态代码体检”

类型注解写了却不检查，等于白写。终端安装并运行 mypy 扫描项目，能发现大量隐藏的类型错误。

# 安装
pip install mypy

# 扫描单个文件
mypy your_script.py

# 扫描整个项目（推荐加上 --strict，开启严格模式）
mypy your_project/ --strict

将 mypy 集成进 CI 流程，就能持续保障代码的类型安全。

结语

类型注解是 Python 从“快速脚本语言”走向“工业级协作语言”的关键一步。它不会让你的编写速度变慢（后期补全、重构反而快很多），也不会阉割 Python 的灵活性。掌握了它，你的代码就能从“能跑就行”升级为“清晰、健壮、一眼就能看懂”。