当前位置：首页 > news >正文

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

news 2026/6/9 3:27:50

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'>

六、版本说明

Python 3.9：正式加入typing.Annotated
Python 3.8 及以下：需安装typing_extensions
bash
运行
```
pip install typing-extensions
```
导入改为：
python
运行
```
from typing_extensions import Annotated
```