在 FastAPI、Pydantic 或 LangGraph 的代码里,迟早会撞见这样的声明:total: Annotated[int, add_total]。类型的位置不再是一个光秃秃的 int,而是被 Annotated 包了起来,后面还跟了个函数——它是什么语法、add_total 什么时候被调用、为什么类型检查器不报错,一连串疑问都指向同一个答案:Python 用一个注解槽同时服务两批读者,静态工具看第一个参数,运行时框架看其余全部。
这种"双面"设计出自 PEP 593,是类型注解体系里承上启下的一块。本文按"注解槽的困境 → 检查器视角 → Pydantic 校验器 → FastAPI 依赖注入 → LangGraph 合并契约 → 对照 Java 注解 → 要点与坑"展开。
1、注解只能放一个值
把 total: int = 0 拆开看,这行声明在语法上是三栏结构:
total : int = 0
名字栏 类型栏 值栏
类型栏是一个单人格子,语法规定恰好放一个表达式。想塞两件东西会被解析器直接拦下,示例如下:
total: int = 0 # 合法:类型栏恰好放一个表达式
# total: int, add_total = 0 # SyntaxError:注解不支持逗号并列
解读:解析器读完冒号后的一个表达式,接下来只接受等号或换行,逗号一出现就判非法——这不是风格建议,是语法检查阶段的硬规则。可生态的真实需求偏偏是"一格装两件":既声明类型,又携带约束、校验器、参数描述。Java 没有这个烦恼,因为它的注解住在声明上方、有自己的语法位置,类型栏不用兼职;Python 的类型注解没有"上方"可挂,一切只能从这一格过。
PEP 593(Python 3.9 引入,更早版本用 typing_extensions)的解法是把两件打包成一件。Annotated[int, add_total] 在语法上就是一次下标运算,整体是单个合法表达式,与 list[int] 无异,所以放得进那一格:
from typing import Annotated
def add_total(value: int) -> int:
return value + 100
Total = Annotated[int, add_total] # 起别名复用,是社区惯例
解读:Annotated[int, add_total] 的第一个参数 int 是真正的类型,之后的参数都是元数据,数量不限。给常用的组合起一个别名(如 Total)复用到多处,是 Pydantic 官方推荐的组织方式。函数参数也是同样的单人格子,所以 FastAPI 的 limit: Annotated[int, Query(...)] = 10 与此同源。设计细节见 PEP 593。
2、检查器只看首参数
Annotated 不改变类型。对 mypy、pyright 这类静态检查器而言,Annotated[int, 任何东西] 就是 int,元数据完全透明。运行时的行为可以用 get_type_hints 看得一清二楚,示例如下:
from typing import Annotated, get_type_hints
class Order:
total: Annotated[int, "订单总额"] = 0
print(get_type_hints(Order))
print(get_type_hints(Order, include_extras=True))
运行输出:
{'total': <class 'int'>}
{'total': typing.Annotated[int, '订单总额']}
解读:默认调用 get_type_hints 会把 Annotated 剥掉只留 int——这正是静态工具视角的运行时写照;传 include_extras=True 才保留完整元数据。这揭示了分工的实质:检查器读第一个参数做类型判断,框架读完整元数据做行为定制,同一行声明两批读者各取所需,详见 typing 文档。
3、Pydantic 挂校验器
Pydantic v2 是把元数据用得最重的框架:约束、校验器、转换函数全部塞进 Annotated。你最初的那个例子完整跑通,示例如下:
from typing import Annotated
from pydantic import BaseModel, Field
def add_total(value: int) -> int:
return value + 100
class Order(BaseModel):
total: Annotated[int, Field(ge=0), add_total]
o = Order(total=50)
print(o.total) # 150:先过 ge=0 校验,再被 add_total 转换
解读:元数据按从左到右的顺序生效——Field(ge=0) 先做值域约束,裸函数 add_total 随后执行。裸可调用对象是 AfterValidator 的简写:在基础类型校验之后运行,收到的是已确认为 int 的值;要在校验前处理原始输入(比如把字符串先转成数字),用 BeforeValidator,四种校验器的完整语义见 Pydantic 校验器文档。
4、FastAPI 与依赖注入
FastAPI 把 Annotated 定为官方推荐的参数声明方式,一个查询参数从声明到校验一行完成:
from typing import Annotated
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/orders")
def list_orders(
limit: Annotated[int, Query(ge=1, le=100, description="每页数量")] = 10,
):
return {"limit": limit}
def get_current_user(token: str) -> str:
return "user-42"
@app.get("/me")
def me(user: Annotated[str, Depends(get_current_user)]):
return {"user": user}
解读:Query(ge=1, le=100, description=...) 既生成接口文档又做参数校验,写法见查询参数校验文档。更关键的是 Depends:Annotated[str, Depends(get_current_user)] 声明"这个参数由依赖函数提供",FastAPI 处理请求时自动调用 get_current_user 注入结果——认证、数据库会话、分页对象都走这条路,Agent 框架里的工具注入同出一门,机制详见依赖注入教程。
5、LangGraph 的合并契约
第三个重量级消费者是 LangGraph:智能体框架用 Annotated 声明状态字段的合并方式。示例如下:
from typing import Annotated, TypedDict
def add_total(old: int, new: int) -> int:
return old + new # reducer:按累加合并
class State(TypedDict):
total: Annotated[int, add_total] # 节点更新时自动调用
steps: int # 无元数据:默认覆盖
解读:节点返回 {"total": 5} 时,LangGraph 取旧状态的 total 与这个 5 调用 add_total,结果写回状态;没配元数据的 steps 直接覆盖,官方文档对这个默认行为写得很直白。这个两参函数叫 reducer(归并函数),名字来自函数式编程的 reduce——累计值与新值进出同一函数,多步输出被归并成一个状态。
注意它的签名与 Pydantic 不同,这正是这套机制的另一面:容器对元数据零要求,调用契约由消费它的框架规定。三个框架的对照如下:
| 框架 | 元数据角色 | 约定签名 | 生效时机 |
|---|---|---|---|
| Pydantic | 校验与转换函数 | (值) |
构造模型时 |
| LangGraph | 状态合并函数 | (旧值, 新值) |
节点返回、合并状态时 |
| FastAPI | 参数与依赖描述 | 不限定 | 处理请求时 |
从表里可以直接读出写代码的顺序:先查"读这个元数据的框架契约是什么",再决定函数签名。累加语义还有现成的惯用写法 Annotated[int, operator.add]——标准库 operator.add 本身就是两参相加;消息历史字段则用 LangGraph 内置的 add_messages。同一个容器,装什么策略由场景决定。
6、对照 Java 注解
这套玩法 Java 开发者其实早就会——Bean Validation(JSR 380)就是同构的设计,等价的 Java 写法如下:
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
public class Order {
@Min(0)
@Max(1000)
private int total;
}
解读:@Min(0) @Max(1000) 与 Field(ge=0, le=1000) 表达的是同一件事,两套体系的分工也如出一辙,对照如下:
| 维度 | Java 注解 | Python Annotated |
|---|---|---|
| 书写位置 | 字段或参数上方 | 类型注解槽内部 |
| 静态检查 | 编译器不校验约束 | 检查器只认首个类型参数 |
| 执行者 | 校验框架(如 Hibernate Validator) | 读取注解的库(如 Pydantic) |
| 触发方式 | 显式调用校验器或 @Valid |
构造模型或处理请求时 |
从表里可以看出,两边都是"声明式元数据加外部引擎执行"的路线:注解与元数据本身是惰性的,真正的行为由读它们的框架赋予。差别只在挂载位置——Java 把注解悬在声明上方,Python 把元数据塞进类型这一格里。
7、要点与坑
第一,元数据对类型检查器不可见是特性也是坑:Field(ge=0) 约束的是值域,而值域本就不在类型系统的管辖范围内,mypy 不会替你校验它,传错元数据(比如拼错参数名)只能靠框架自己的报错兜底。第二,版本门槛要记牢:Annotated 是 Python 3.9 进入标准库的,更早的解释器需要装 typing_extensions 才能导入。第三,Annotated 本身没有任何魔法——只是个装元数据的容器,库必须主动用 get_type_hints(..., include_extras=True) 读取才有效果;自己写框架想利用它,读出来后按约定解释即可。
元数据里放什么没有硬性限制,字符串、函数、Field 对象都合法;但生态的默契是放"框架认识的标记",放一个只有你自己认识的字符串进去,等于谁也不生效,不如写成注释。
8、总结
回顾要点:Annotated[T, 元数据...] 用一个注解槽同时承载类型与元数据,检查器只看 T,元数据留给运行时框架读取;Pydantic 用它挂约束与校验器,裸函数即"校验后转换",BeforeValidator 管"校验前预处理";FastAPI 用它声明参数行为与依赖注入,是接口层的通用挂载点;LangGraph 用它挂状态合并的 reducer,契约是"旧值加新值",无元数据则覆盖;它与 Java 的 Bean Validation 同构,都是"惰性元数据加执行引擎"的分工。对于正在 FastAPI 与 Pydantic 生态里写代码的开发者,建议把常用的"类型加约束加校验器"组合提炼成 Annotated 别名统一复用——声明集中在一处,接口文档、运行时校验、类型检查三头受益。

