[智能体-327]：Annotated 语法详解

Annotated是类型注解增强工具，给已有类型附加元数据、描述、校验规则、文档等额外信息，不改变原类型本身。

一、基础导入

python

运行

# Python 3.9+ 标准库 from typing import Annotated

二、核心语法

python

运行

Annotated[类型, 元数据1, 元数据2, ...]

• 第一个参数：原生类型（int/str/list/ 自定义类等）
• 后面所有参数：任意元数据（字符串、对象、函数、枚举等）
• 运行时不强制校验，仅存储附加信息，由第三方库（FastAPI、Pydantic、mypy）解析使用

三、基础示例

1. 加文字描述（最常用）

python

运行

from typing import Annotated # 给 int 附加说明 Age = Annotated[int, "用户年龄，范围 0-120"] def get_age() -> Age: return 25 # 本质还是 int print(type(get_age())) # <class 'int'>

2.多个元数据叠加

python

运行

Username = Annotated[ str, "登录用户名", {"min_length": 4, "max_length": 20}, # 字典规则 "不可包含特殊字符" ]

四、实战场景（主流用法）

场景 1：FastAPI 接口参数（高频）

搭配参数校验、说明、示例：

python

运行

from fastapi import FastAPI from typing import Annotated app = FastAPI() @app.get("/user") def read_user( age: Annotated[int, "用户年龄", 0, 120] ): return {"age": age}

场景 2：Pydantic 数据模型校验

结合Field做约束：

python

运行

from pydantic import BaseModel, Field from typing import Annotated # 类型 + 校验规则 + 描述 Score = Annotated[float, Field(ge=0, le=100, description="考试分数")] class Student(BaseModel): name: str score: Score

场景 3：类型别名复用

统一规范全局类型：

python

运行

from typing import Annotated Phone = Annotated[str, "手机号，11位数字"] Email = Annotated[str, "标准邮箱格式"] class User: phone: Phone email: Email

五、取值元数据（运行时读取附加信息）

用__metadata__属性获取：

python

运行

from typing import Annotated Info = Annotated[int, "数值类型", 100] # 取出所有附加元数据 print(Info.__metadata__) # ('数值类型', 100) # 取出基础类型 print(Info.__origin__) # <class 'int'>

六、版本说明

1. Python 3.9：正式加入typing.Annotated
2. Python 3.8 及以下：需安装typing_extensions

   bash

   运行

   pip install typing-extensions

   导入改为：

   python

   运行

   from typing_extensions import Annotated

七、总结口诀

• 格式：Annotated[原类型, 附加信息...]
• 作用：给类型打标签、加规则、写文档
• 本质：原类型不变，元数据供框架解析
• 主力场景：FastAPI、Pydantic、静态类型文档