![[智能体-329]：Annotated 通俗详解](images/news1.jpg)
一句话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(ge0, le120)用Annotated改写规则打包全局复用python运行from typing import Annotated from pydantic import BaseModel, Field # 打包int类型 年龄校验规则 AgeRule Annotated[int, Field(ge0, le120, 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_length2, max_length20, description用户名)] UserAge Annotated[int, Field(ge0, le120, description年龄)] # 2. 模型直接引用 class User(BaseModel): name: UserName age: UserAge
[智能体-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(ge0, le120)用Annotated改写规则打包全局复用python运行from typing import Annotated from pydantic import BaseModel, Field # 打包int类型 年龄校验规则 AgeRule Annotated[int, Field(ge0, le120, 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_length2, max_length20, description用户名)] UserAge Annotated[int, Field(ge0, le120, description年龄)] # 2. 模型直接引用 class User(BaseModel): name: UserName age: UserAge
