如何利用Annotated在Python 3.9中高效进行类型提示管理？

本文共计1248个文字，预计阅读时间需要5分钟。

当您需要在类型提示中附带校验规则、文档说明或序列化行为（例如FastAPI的Query、Pydantic v2的Field）时，单纯写str或int就不够用了。Annotated是Python 3.9引入的官方机制，允许你在保持运行时访问原始类型的同时，添加额外的元数据。例如：

常见错误是误以为 Union[str, Field(...)] 或自定义泛型能替代它：前者根本不是合法类型，后者在静态检查和运行时反射中都不可靠。

• Annotated 的第一个参数必须是有效类型（如 str、List[int]），后续所有参数都是元数据，类型检查器只关心第一个
• 元数据对象不参与类型推导，但可通过 get_args() 和 get_origin() 在运行时提取
• 第三方库（如 Pydantic、FastAPI）正是靠识别 Annotated[T, ...] 结构来注入行为，不是靠字符串解析或装饰器

怎么安全提取 Annotated 中的类型与元数据

别直接索引 __args__——这是内部实现细节，且在嵌套 Annotated（如 Annotated[Annotated[int, 'a'], 'b']）时会出错。Python 3.9+ 应统一用 typing.get_origin() 和 typing.get_args()。