先看一段代码找 bug——函数在什么情况下会出错？

def apply_discount(price, rate):
    return price * (1 - rate)

apply_discount(100, 0.2)        # 80.0，正常
apply_discount("100", 0.2)      # TypeError: 字符串乘不了浮点
apply_discount(100, "两折")     # TypeError 又一个
apply_discount(-50, 1.5)        # -25，不报错但业务上是错的！

三个调用，两个运行时崩溃，一个静默的业务错误。这段代码没有语法错误、没有逻辑漏洞——问题只在「约定不明」：price 应该是正数、rate 应该是 0~1 的小数，但代码没说，调用方也就「自由发挥」了。

类型注解（Type Hints）解决的就是这个问题：把「约定」写进代码，让工具替你检查。Python 3.5 引入、3.9+ 大幅强化、如今已是现代 Python 工程的标配——这篇讲清注解怎么写、检查工具怎么配、以及渐进式迁移的路径。

一、基础：给函数和变量写「约定」

def apply_discount(price: float, rate: float) -> float:
    """price: 正数价格；rate: 0~1 之间的折扣率"""
    return price * (1 - rate)

price: float 是参数注解，-> float 是返回值注解。注意一个关键认知：Python 运行时不会强制这些注解——apply_discount("100", 0.2) 照样能传进去（运行时不报错）。注解的价值不在运行时，在静态检查：mypy/pyright 这类工具读注解，在你运行代码之前就报错：

$ mypy your_code.py
error: Argument 1 to "apply_discount" has incompatible type "str"; expected "float"
error: Argument 2 to "apply_discount" has incompatible type "str"; expected "float"
Found 2 errors in 1 file (checked 1 source file)

运行时崩溃 → 编写时报警，这就是类型注解的全部价值起点。IDE（VS Code + Pylance）还会实时划红线、自动补全（知道参数类型就能补全它的属性和方法）——很多工程师装了类型注解后回不去的原因，是开发体验的质变。

二、进阶：容器、Optional 和联合类型

真实代码里的类型远比 float 复杂，三个高频写法：

def process_names(names: list[str]) -> dict[str, int]:
    return {name: len(name) for name in names}

def find_user(user_id: int) -> dict | None:      # 3.10+ 用 | 语法
    ...

user = find_user(123)
print(user["name"])     # mypy 红线：user 可能是 None，不能直接下标
if user is not None:    # 判空后，工具自动「类型收窄」
    print(user["name"]) # ✅ 通过

def parse(value: str | int | bytes) -> int: ...

Optional 是类型系统里价值最高的注解——它把「这个值可能为 None」从口头约定变成机器检查。Python 里一半的运行时崩溃是 NoneType has no attribute...，这一类问题在配了类型检查的项目里几乎绝迹。

三、实战：dataclass——类型注解的最佳拍档

结构化数据（配置、记录、API 返回值）的类型化，标准答案是 dataclass（3.7+）：

from dataclasses import dataclass

@dataclass
class Order:
    order_id: str
    amount: float
    status: str = "pending"          # 带默认值
    items: list[str] = None          # ⚠️ 可变默认值的坑，见下

order = Order(order_id="A001", amount=99.9, status="paid")
print(order)   # Order(order_id='A001', amount=99.9, status='paid')

dataclass 自动生成 __init__/__repr__/__eq__，配合类型注解，把「字典当数据容器」的裸奔写法升级成有结构的对象。更进一步要校验数据合法性（amount 必须为正），用 Pydantic（FastAPI 的底层，数据校验的事实标准）：

from pydantic import BaseModel, Field

class Order(BaseModel):
    order_id: str
    amount: float = Field(gt=0)          # 运行时校验：必须大于 0
    status: str = "pending"

Order(order_id="A001", amount=-5)        # ValidationError: 必须大于 0 ✅

分工：dataclass 用于内部结构（静态检查），Pydantic 用于边界数据（API 入参/出参的运行时校验）——两者都是类型注解生态的一部分。

四、渐进迁移：老项目别推翻重来

存量项目加类型注解的正确姿势是渐进式，按收益排序：

第 1 步：新代码 100% 带注解（成本最低，收益立现）
第 2 步：公共函数/模块（被多人调用的）加注解——接口约定收益最大
第 3 步：pyright 检查器上「宽松模式」跑起来，逐步收紧
第 4 步：CI 里加 mypy/pyright 卡点，新代码不过类型检查不能合入
第 5 步：老代码按「改动频率」逐步补注解（常改的先补）

配置上推荐 pyright（VS Code 内置 Pylance 的引擎，速度快），CI 用 mypy 或 pyright 均可。别追求 100% 类型覆盖率——收益最高的 20% 是公共接口和数据结构，剩下的按改动频率自然渗透即可。

五、避坑三条

注解不影响运行时：写错注解程序照跑——所以 CI 里必须挂静态检查，
  否则注解只是「看起来专业」的装饰
可变默认值的注解写法：list[str] = [] 仍共享（老坑），
  正确写法 list[str] | None = None，函数内再初始化
Any 是逃生门不是默认门：类型拿不准就写 Any 会让检查失去意义，
  拿不准时先用 Unknown（pyright 会推导），按报错逐步明确

类型注解代表的，是 Python 从「脚本语言」走向「工程语言」的那条路：动态类型的灵活 + 静态检查的严谨，可以兼得。它的收益结构很适合技术人的长期主义——早期投入每小时，换来的是：IDE 补全加速日常编码、mypy 拦截一半的运行时崩溃、重构时全链路类型检查兜底、新人读代码的理解成本减半。如果你的团队还在「能跑就行」的阶段，从下一个新函数开始写注解——三个月后，你会把「没类型的 Python 代码」视作不敢接手的陌生领域。

 更多相关技术内容咨询欢迎前往并持续关注好学星城论坛了解详情。

想高效系统的学习Python编程语言，推荐大家关注一个微信公众号：Python编程学习圈。每天分享行业资讯、技术干货供大家阅读，关注即可免费领取整套Python入门到进阶的学习资料以及教程，感兴趣的小伙伴赶紧行动起来吧。