[智能体-329]：Annotated 通俗详解
一句话：Annotated就是给「数据类型」贴标签、加备注、绑规则，本身不改类型，只是额外附带上说明 / 约束，常和 Pydantic、FastAPI 搭配使用。
一、先搞懂：为什么需要它？
平时写类型注解，只能单纯标注类型：
python
运行
age: int只能看出age是整数，但不知道取值范围、含义、填写规则。
如果想额外加信息（比如：年龄 0~120、字段说明、校验规则），普通注解（age: int）做不到，这时候就用Annotated。
二、基础用法
1. 导入
Python3.9+ 自带，直接导入：
python
运行
from typing import Annotated3.8 及以下先装依赖：pip install typing-extensions，再从typing_extensions导入。
2. 固定语法
python
运行
Annotated[基础类型, 附加内容1, 附加内容2, ...]- 第一个参数：原本的类型（
int/str/ 列表等），必填 - 后面所有参数：随便加文字、规则、对象，都是附加信息，数量不限
3. 最简单示例（加文字备注）
python
运行
from typing import Annotated # 给 int 加说明：年龄，范围0-120 Age = Annotated[int, "用户年龄，取值 0 ~ 120"] # 使用，本质还是 int 类型 def get_age() -> Age: return 20 print(type(get_age())) # <class 'int'>，类型没变✅ 关键点：底层类型完全不变，附加内容只是 “附属信息”。
三、常见使用场景（由浅到深）
场景 1：纯文字注释（看代码 / 生成文档用）
给字段写中文说明，别人一看就懂，不用翻注释：
python
运行
from typing import Annotated # 字符串 + 备注：登录账号，4-20位 Username = Annotated[str, "登录账号，长度4~20位"] name: Username = "zhangsan"场景 2：多条附加信息叠加
可以一次性加多个备注、标记：
python
运行
from typing import Annotated Phone = Annotated[ str, "中国大陆手机号", "必须11位数字", "不可为空" ] tel: Phone = "13800000000"场景 3：搭配 PydanticField（最常用：绑定校验规则和类型自动转化）
这是工作中主力用法：把类型 + 校验规则打包在一起，还能重复使用。
普通写法（规则写在字段后，无法复用）：
python
运行
from pydantic import BaseModel, Field class User(BaseModel): age: int = Field(ge=0, le=120)用Annotated改写（规则打包，全局复用）：
python
运行
from typing import Annotated from pydantic import BaseModel, Field # 打包：int类型 + 年龄校验规则 AgeRule = Annotated[int, Field(ge=0, le=120, description="用户年龄")] # 模型里直接用，代码更干净 class User(BaseModel): age: AgeRule # 另一个模型，直接复用这套规则，不用重复写 Field class Student(BaseModel): age: AgeRule对比总结：
- 不用
Annotated：规则散在每个字段里，重复代码多 - 用
Annotated：类型 + 规则 封装成一个整体，一次定义，到处调用
场景 4：搭配 FastAPI（接口文档 + 参数校验）
接口开发标配，附加内容会自动展示在接口文档里：
python
运行
from fastapi import FastAPI from typing import Annotated app = FastAPI() @app.get("/hello") def say_hello( num: Annotated[int, "传入一个正整数", 1, 999] ): return {"number": num}打开接口文档，能直接看到后面的文字说明。
四、运行时读取附加信息
如果代码里需要拿到你写的备注 / 规则，用__metadata__属性：
python
运行
from typing import Annotated Info = Annotated[int, "测试数字", 0, 100] # 获取所有附加内容，返回元组 print(Info.__metadata__) # ('测试数字', 0, 100) # 获取原始基础类型 print(Info.__origin__) # <class 'int'>五、核心特点总结（好记版）
- 不改变原类型
Annotated[int, ...]到头来还是int，运算、类型判断不受影响。 - 附加内容自由后面可以写字符串、校验规则、对象，想加多少加多少。
- 核心价值：复用 + 解耦把「类型 + 规则 + 说明」打包，一处定义，多处使用，减少重复代码。
- 主打搭档和Pydantic、FastAPI是黄金组合，专门用来做数据约束、接口文档。
六、最简实战组合（日常开发直接抄）
python
运行
from typing import Annotated from pydantic import BaseModel, Field # 1. 统一封装通用字段规则 UserName = Annotated[str, Field(min_length=2, max_length=20, description="用户名")] UserAge = Annotated[int, Field(ge=0, le=120, description="年龄")] # 2. 模型直接引用 class User(BaseModel): name: UserName age: UserAge