学习结果
用 Protocol 定义行为接口，用 TypedDict 与 Pydantic 约束不可信边界，用泛型保持容器类型连续，并在 CI 中强制静态检查。
前置条件
- Python 3.12 或更新版本
- 熟悉函数与基础类型注解
- 一个可以添加类型检查模块的项目
在 AI Coding 时代，类型注解不是可有可无的装饰。它们是机器可解析的边界契约，能够有效约束大模型的代码生成范围，并在代码运行前拦截逻辑回退。
使用 Protocol 实现结构化子类型
避免为测试桩或服务适配器构建繁重的类继承层级。使用 typing.Protocol 定义轻量级的行为接口：
from typing import Protocol
class DataRepository(Protocol):
def get_by_id(self, item_id: str) -> dict | None: ...
def save(self, item_id: str, data: dict) -> None: ...
无论是测试用的 Mock 对象还是真实的数据库适配器，只要签名匹配即可满足 DataRepository 契约，使单元测试运行极快，并解耦业务逻辑与存储实现。
使用 TypedDict 与 Pydantic 建立严格边界契约
处理来自外部不可信的 JSON 数据时，内部使用 typing.TypedDict 描述确定性结构，在系统网络边界处使用 Pydantic 进行反序列化和严格校验。
from typing import TypedDict
class UserProfile(TypedDict):
user_id: int
username: str
is_active: bool
使用泛型保留容器与管道的类型信息
使用 typing.TypeVar 或现代 Python 3.12+ 泛型语法（如 class Container[T]: ...），确保在缓存层、任务队列与 API 包装器中保持类型连续性，避免退化为无约束的 Any。
在开发与 CI 流程中进行静态验证
类型注解只有在被强制检查时才具备确定性价值。在 CI 流水线中运行 Mypy 或 Pyright，确保公共接口类型完备。
来源
类型系统的权威规范见官方 Python typing 文档。
验证记录
文档审校
依据 Python typing、Pydantic 与 Mypy 官方文档对类型模式进行编辑审校。验证日期 2026-09-02。
关于作者
Organizational byline for FlyPython guides, verification records, and corrections. 编辑标准与联系方式 →