08. FastAPI 请求参数类型验证_Path方式

Path 管 URL 中的标识符

Path 用来说明和约束路径参数。例如订单 ID 应为正整数、文章代号只允许小写字母。路径参数必填，因为缺少该片段时，URL 就匹配不到这一条路由。

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/orders/{order_id}")
def order_detail(
    order_id: Annotated[int, Path(gt=0, description="订单主键")],
    include_items: bool = False,
):
    return {"order_id": order_id, "include_items": include_items}

@app.get("/articles/{slug}")
def article_detail(
    slug: Annotated[str, Path(min_length=3, max_length=60,
                              pattern=r"^[a-z0-9-]+$")],
    language: Annotated[str, Query(min_length=2, max_length=5)] = "zh",
):
    return {"slug": slug, "language": language}

保存为 main.py，运行 uv run uvicorn main:app --reload。/orders/18?include_items=true 成功；/orders/0 违反范围；/orders/abc 无法转成整数；/articles/hello-fastapi 成功；/articles/Hello! 不符合代号格式。

404 与 422 分别意味着什么

/orders/abc 匹配了路径模板，但参数不合要求，因此是 422。/something/abc 没有相应路由，因此是 404。/orders/999 即使类型合法，也可能查不到数据库资源，需要函数主动返回 404。

路径约束不会自动验证数据库里有没有这个 ID，更不会检查是否属于当前用户。资源归属应结合认证信息在业务层检查。

三类声明的分工

工具	主要位置	常见用途
Path	URL 路径	ID、代号、层级资源
Query	查询串	分页、搜索、排序
Field	模型字段	正文中字段的规则

不要给路径参数设置可省略的默认值。需要“列表”和“单项”两个入口时，分别注册 /orders 和 /orders/{order_id} 更清楚。

常见误区与练习

• 正整数规则不代表只匹配数字路由；默认模板先匹配，再做参数验证。
• 将动态路由放在 /orders/latest 之前，可能把 latest 当作 ID 后返回 422。
• 对一个字段设置多条规则时，应避免上下界互相矛盾。
• 标题和描述只影响文档，不替代验证规则。

练习：增加 /warehouses/{warehouse_id}/items/{item_id}，限制两个 ID 均大于零；手工整理“路径不匹配”“类型错误”“范围错误”三种请求及响应。