今天介绍 FastAPI 框架中一个小技巧，如何通过使用 Annotated 来实现更简洁、功能又强大的接口函数。下面让我们直接上干货。

在使用 FastAPI 开发项目时，我们经常会写这样的接口，路由函数中的参数是需要规定格式和校验的：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def get_items(q: str = Query(..., min_length=3, max_length=50)):
    return {"q": q}

这里的 Query 用来声明和校验参数。但随着项目规模的扩大，我们会发现：

• 参数声明和业务逻辑混杂在一起；
• 同样的参数校验在多个接口里重复出现；
• 类型标注越来越复杂，代码可读性下降。

这时，Annotated 就能帮我们解耦「类型声明」和「参数校验逻辑」。

一、什么是Annotated

Annotated 来自 Python 的 typing 模块（PEP 593），它的本质作用是：

在类型标注的基础上，添加额外的元信息（metadata），而不改变原本的类型。

在 FastAPI 中，Annotated 最常见的场景就是 结合依赖注入 或 参数校验。
例如，下面两段代码效果完全一样：

# 传统写法
async def get_items(q: str = Query(..., min_length=3, max_length=50)):
    ...

# Annotated 写法
from typing import Annotated

async def get_items(q: Annotated[str, Query(..., min_length=3, max_length=50)]):
    ...

区别在于：

• 第一种写法里，类型和参数校验混合在一起；
• 第二种写法里，类型定义与校验逻辑分开，更清晰、更易复用。

你可能反对，这不是没啥区别吗？但是，Annotated 的定义是可以单独拿出来的。看看下面的常见用法！

二、Annotated 的常见用法

1. 请求参数校验

from typing import Annotated
from fastapi import Query

# 定义一个带校验的字符串类型
QueryString = Annotated[str, Query(min_length=3, max_length=50)]

@app.get("/search/")
async def search(q: QueryString):
    return {"q": q}

解释：
这里我们把 q 的类型单独抽出来，定义成 QueryString。
这样做有两个好处：

1. 复用性：如果多个接口都有搜索参数，就不用每次都写 Query(min_length=3, max_length=50)；
2. 可读性：接口函数里只保留业务逻辑，参数约束被“命名化”，更直观。

2. 路径参数

from fastapi import Path

ItemId = Annotated[int, Path(ge=1)]

@app.get("/items/{item_id}")
async def get_item(item_id: ItemId):
    return {"item_id": item_id}

解释：
ItemId 被声明为一个「必须大于等于 1 的整数」。
路径参数通常很重要，像订单 ID、用户 ID，明确校验规则可以避免非法访问。
这种写法比在函数里写 item_id: int = Path(ge=1) 更简洁，而且能统一管理。

3. Header / Cookie 参数

from fastapi import Header

AuthHeader = Annotated[str | None, Header(alias="Authorization")]

@app.get("/me")
async def read_me(auth: AuthHeader):
    return {"Authorization": auth}

解释：
AuthHeader 指定了从请求头里提取 Authorization 字段。
使用 Annotated 的好处是：以后所有需要鉴权的接口，都能直接使用 auth: AuthHeader，而不是重复写 Header(alias="Authorization")。

4. 依赖注入（Depends）

from fastapi import Depends

async def common_dep(token: str = Depends(...)):
    return token

TokenDep = Annotated[str, Depends(common_dep)]

@app.get("/secure/")
async def secure(token: TokenDep):
    return {"token": token}

解释：
Depends 是 FastAPI 的依赖注入核心。
这里我们用 TokenDep 来标记“需要经过 common_dep 的依赖注入”。
以后只要有接口需要依赖这个校验逻辑，直接写 token: TokenDep 就行，函数定义简洁且一致。

5. 自定义参数类型：手机号 / UUID

在工程实践中，我们经常遇到一些“特殊格式”的参数，比如手机号、UUID。
如果每次都写正则和校验逻辑，不仅麻烦，而且容易出错。

借助 Annotated，可以封装成统一的类型：

from typing import Annotated
from fastapi import Query

# 手机号类型
PhoneNumber = Annotated[
    str,
    Query(
        ...,
        description="用户手机号",
        min_length=11,
        max_length=11,
        regex=r"^1[3-9]\d{9}#34;,
    )
]

# UUID 类型
Uuid = Annotated[
    str,
    Query(
        ...,
        description="UUID格式的唯一标识符",
        regex=r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}#34;,
    )
]

@app.get("/verify-phone/")
async def verify_phone(phone: PhoneNumber):
    return {"phone": phone}

@app.get("/resource/")
async def get_resource(uuid: Uuid):
    return {"uuid": uuid}

解释：
这是 Annotated 在工程中非常实用的用法：

• 手机号：加了正则匹配，确保用户输入符合国内手机号格式；
• UUID：严格校验字符串格式，避免传入任意乱写的 ID。

这种做法的价值在于：

• 你只需要在一个地方维护正则表达式；
• 接口函数里只用 phone: PhoneNumber，别人一看就懂这是「带验证的手机号」。

三、真实工程案例：用户管理系统

假设我们正在实现一个简单的 用户管理系统，其中有用户注册接口。
需求：

• 用户名必须在 3~20 个字符之间；
• 邮箱必须符合格式；
• 密码至少 6 位；

传统写法：

from fastapi import FastAPI, Query, Form

app = FastAPI()

@app.post("/register/")
async def register(
    username: str = Form(..., min_length=3, max_length=20),
    email: str = Form(..., regex=r"^[\w\.-]+@[\w\.-]+\.\w+#34;),
    password: str = Form(..., min_length=6),
):
    return {"username": username, "email": email}

路由函数的参数非常长，而且如果其他地方要用，又得再写一遍。所以我们改用 Annotated：

from typing import Annotated
from fastapi import Form

Username = Annotated[str, Form(..., min_length=3, max_length=20)]
Email = Annotated[str, Form(..., regex=r"^[\w\.-]+@[\w\.-]+\.\w+#34;)]
Password = Annotated[str, Form(..., min_length=6)]

@app.post("/register/")
async def register(username: Username, email: Email, password: Password):
    return {"username": username, "email": email}

你看到了，修改之后的代码：

• 可读性更好：一眼就能看出 Username、Email、Password 的定义；
• 可复用：其他接口也能直接用这些类型；
• 清晰解耦：业务逻辑函数更简洁。

四、Annotated vs Pydantic 模型类对比

有敏锐的人可能发现了：那我为什么不用直接定义一个 Pydantic 模型类？

确实可以，我们来对比一下。

Pydantic 模型写法

from pydantic import BaseModel, Field

class User(BaseModel):
    username: str = Field(..., min_length=3, max_length=20)
    email: str = Field(..., regex=r"^[\w\.-]+@[\w\.-]+\.\w+#34;)
    password: str = Field(..., min_length=6)

@app.post("/register/")
async def register(user: User):
    return user

对比总结

实战选择建议

• 简单接口（登录、分页、搜索参数） → 用 Annotated 更轻量；
• 复杂接口（注册用户、订单提交、配置对象） → 用 Pydantic 模型类，更结构化；
• 混合场景 → FastAPI 也支持两者混用，比如：

@app.post("/orders/{order_id}")
async def create_order(
    order_id: Annotated[int, Path(ge=1)],
    user: User,   # 请求体
    token: Annotated[str, Header(alias="Authorization")]
):
    ...

这种两种方式混合使用，能让接口函数既干净又强大。

一句话总结：

• Annotated 更像是「精细化标注」工具，适合做小刀切割；
• Pydantic 模型类 更像是「大而全的契约」，适合做复杂的结构化数据约束。

五、在团队工程中的最佳实践

1、参数类型集中管理

建议在项目中新建一个 schemas/params.py，把常用的 Annotated 参数都放里面：

# app/schemas/params.py
from typing import Annotated
from fastapi import Query, Path, Form, Header

Username = Annotated[str, Form(..., min_length=3, max_length=20)]
Email = Annotated[str, Form(..., regex=r"^[\w\.-]+@[\w\.-]+\.\w+#34;)]
Password = Annotated[str, Form(..., min_length=6)]
PhoneNumber = Annotated[str, Query(..., min_length=11, max_length=11, regex=r"^1[3-9]\d{9}#34;)]
Uuid = Annotated[str, Query(..., regex=r"^[0-9a-fA-F-]{36}#34;)]

2、保持函数简洁

避免在接口函数里写一长串校验规则，统一用 Annotated 提升可维护性。

3、合理选择模型方式

• 参数少、接口简单：Annotated；
• 参数多、结构复杂：Pydantic 模型；
• 两者结合：最灵活。

六、总结

• Annotated 是 FastAPI 中推荐的参数声明方式，可以让代码更清晰、复用性更高；
• 它尤其适合「轻量参数」：手机号、UUID、分页、Token 等；
• Pydantic 模型类则更适合「结构化请求体」；
• 工程实践中，两者往往结合使用，效果最佳。

一句话总结：
Annotated 是小刀，Pydantic 是大斧，刀斧并用让你的接口简洁又强大。

长篇技术文章的编写不易，喜欢就请点点赞和关注吧。后续我会更新更多FastAPI框架相关的内容。

#python# #后端开发# #fastapi# #Web系统开发# #接口#