用途:在 Python 项目中使用类型系统,让静态分析工具在运行前发现类型错误。类型注解被视为可被工具自动校验的文档。
适用时机:为已有代码添加类型提示;创建可复用的泛型类;用协议定义结构化接口;为 mypy 或 pyright 配置严格检查;理解类型收窄与类型守卫;构建类型安全的 API 与库。
核心概念:类型注解,为函数参数、返回值与变量声明预期类型;泛型,编写在不同类型间保留类型信息的可复用代码;协议,无需继承即可定义结构化接口(带类型安全的鸭子类型);类型收窄,用守卫与条件在代码块内缩小类型范围。
使用方式:为所有公开签名添加注解,公开函数、方法与类都应带类型注解;优先使用现代联合语法,Python 3.10+ 用 str | None,3.9 可用 typing.Optional/Union;用守卫做类型收窄,例如先判断 user is None 再抛出异常,之后类型检查器即知 user 为 User;用 TypeVar 与 Generic 构建泛型类,可对类型变量加 bound 限制;用 mypy --strict 或 pyright 在 CI 中捕获类型错误,存量项目可用按模块覆盖的方式逐步开启严格模式。属快速入门示例:def get_user(user_id: str) -> User | None,函数体省略,随后判断 None 并处理。
最佳实践:注解所有公开 API;用 T | None 取代 Optional[T];在 CI 中运行 mypy --strict;用泛型保留类型信息;用协议定义接口;用守卫收窄类型;为类型变量加 bound;为复杂类型创建类型别名;尽量少用 Any,仅在真正动态数据或对接无类型第三方代码时使用;用类型充当可强制执行的文档。
限制与说明:更多进阶模式与完整示例位于 references/details.md,需查阅该文件获取细节。资料未提供具体版本兼容范围、工具安装命令、性能数据或收费信息。