FastAPI 路径参数全解：一份类型标注如何同时驱动解析、校验与文档

本文基于 FastAPI 官方教程中的「Pfad-Parameter（路径参数）」章节，系统讲解如何在 FastAPI 中声明路径参数：从 Python 格式化字符串语法、类型标注触发的自动解析与数据校验，到 Enum 预定义取值、包含路径的参数写法。读完本文，你可以直接复制运行文中全部示例，并能从源码层面（fastapi/routing.py、fastapi/dependencies/utils.py）理解「一次声明，处处生效」背后的实现机制。

一、基础语法：与 Python 格式化字符串同源

路径参数（Pfad-Parameter）可以使用与 Python 格式化字符串（f-string / str.format）完全相同的语法来声明——在路径模板的 {...} 中写出参数名即可：

from fastapi import FastAPI

app = FastAPI()


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

（完整示例见 tutorial001_py310.py）

此时路径参数 item_id 的取值会作为同名参数 item_id 传入你的函数。启动应用后访问 http://127.0.0.1:8000/items/foo，响应为：

{"item_id":"foo"}

注意：不加类型标注时，item_id 收到的就是 URL 中原始的字符串 "foo"。

二、带类型标注的路径参数

使用标准 Python 类型标注即可声明路径参数的类型：

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

（完整示例见 tutorial002_py310.py）

这里 item_id 被声明为 int。这一行标注带来的第一个直接好处：编辑器支持——在你的函数体内，类型检查、代码补全、错误提示全部生效，item_id 会被当作 int 对待。

2.1 自动数据转换（Parsing）

访问 http://127.0.0.1:8000/items/3，响应为：

{"item_id":3}

关键点：你的函数实际收到（并返回）的值是 Python int 类型的 3，而不是字符串 "3"。仅仅依靠这一行类型声明，FastAPI 就完成了对请求的自动「解析」——把来自 HTTP 请求的字符串转换成对应的 Python 数据类型。

2.2 自动数据校验（Validation）

反过来，访问 http://127.0.0.1:8000/items/foo，你会得到一个结构化的 HTTP 错误响应：

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": [
        "path",
        "item_id"
      ],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

原因很直接：路径参数 item_id 的值 "foo" 无法解析为 int。同样的错误也会出现在你传入浮点数（如 http://127.0.0.1:8000/items/4.2）的场景——4.2 不是合法的整数。

值得留意错误响应中的 loc 字段：它明确指出了校验失败的位置是 path 中的 item_id。在开发、调试与你的 API 交互的代码时，这种「精确到字段」的错误定位非常有价值。同样，这一切都来自同一行 Python 类型声明。

三、一份声明驱动的自动文档

在浏览器打开 http://127.0.0.1:8000/docs，你会看到自动生成的交互式 API 文档（内嵌 Swagger UI），其中路径参数 item_id 被正确地标注为整数类型（见文首截图）。

再强调一次因果关系：仅仅是同一行类型声明，同时带来了编辑器支持、请求解析、数据校验，以及自动交互式文档——且只需声明一次。

3.1 基于 OpenAPI 标准的生态收益

由于生成的 Schema 遵循 OpenAPI 标准，存在大量兼容工具。因此 FastAPI 还自带一套基于 ReDoc 的替代文档界面，位于 http://127.0.0.1:8000/redoc：

同理，围绕 OpenAPI 还有大量兼容工具，包括面向多种语言的客户端代码生成工具。

3.2 Pydantic 是幕后功臣

整个数据校验过程在幕后由 Pydantic 完成，你因此直接受益于其能力。同样的类型声明机制可以配合 str、float、bool 以及更多复杂类型使用，这些都会在教程的后续章节中逐一展开。

四、顺序很重要：固定路径与参数路径的声明次序

当你创建路径操作（path operations）时，经常会遇到「固定路径」与「参数路径」并存的情况。例如 /users/me 用来获取当前用户的信息，同时又有 /users/{user_id} 用来获取某个指定用户的信息。

由于路径操作按声明顺序被匹配，你必须确保 /users/me 声明在 /users/{user_id} 之前：

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

（完整示例见 tutorial003_py310.py）

否则 /users/{user_id} 会先匹配到 /users/me，把 "me" 当作 user_id 参数的值处理。

此外，你也不能重新定义同一路径：

@app.get("/users")
async def read_users():
    return ["Rick", "Morty"]


@app.get("/users")
async def read_users2():
    return ["Bean", "Elfo"]

（完整示例见 tutorial003b_py310.py）

此时永远只有第一个定义会被调用，因为它声明在前、路径先匹配命中。

五、预定义取值：用 Enum 限定路径参数

当你希望某个路径参数的合法取值来自一个固定集合时，可以使用标准 Python Enum。

5.1 创建 Enum 类

导入 Enum，并创建一个同时继承 str 和 Enum 的子类：

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

继承 str 的意义在于：API 文档知道这些值必须是 string 类型，从而能正确渲染。（顺带一提：AlexNet、ResNet、LeNet 是深度学习模型架构的名字。）

5.2 声明使用该 Enum 的路径参数

然后用你的 ModelName 类作为类型标注来声明路径参数：

app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    ...

5.3 查看文档效果

由于合法取值已被预定义，交互式文档可以漂亮地把它们显示为一个下拉选择：

5.4 与 Python 枚举协作

路径参数的值会是一个枚举成员（Enum Member），有三种常用操作：

比较枚举成员——直接和 ModelName 中的成员比较：

    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

获取枚举值——通过 .value 拿到实际的底层值（本例中是 str）：

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

提示："lenet" 这个值也可以通过 ModelName.lenet.value 直接获取。

返回枚举成员——你可以把 Enum 成员从路径操作中返回，甚至可以嵌套在 JSON 响应体（如 dict）里。它们会在返回给客户端之前自动转换成对应的值（本例中是字符串）：

    return {"model_name": model_name, "message": "Have some residuals"}

（以上完整示例见 tutorial005_py310.py）

客户端收到的 JSON 响应为：

{
  "model_name": "alexnet",
  "message": "Deep Learning FTW!"
}

六、包含路径的参数：{file_path:path}

假设你有一个路径操作，路径为 /files/{file_path}，但 file_path 本身需要包含多级目录，例如 home/johndoe/myfile.txt，即完整 URL 形如 /files/home/johndoe/myfile.txt。

6.1 OpenAPI 的限制与 Starlette 的方案

OpenAPI 标准本身不提供「路径参数内可以包含路径」的声明方式——那会导致难以定义和测试的边界场景。不过 FastAPI 允许你借助 Starlette 的内部工具实现这一行为：文档依旧正常生成，只是不会额外标注「该参数应包含路径」。

借助 Starlette 的路径转换器（path convertor）语法，把路由声明为：

/files/{file_path:path}

这里参数名是 file_path，结尾的 :path 表示该参数匹配任意路径（包括 /）。完整示例：

from fastapi import FastAPI

app = FastAPI()


@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

（完整示例见 tutorial004_py310.py）

提示：如果参数值本身需要以 / 开头，如 /home/johndoe/myfile.txt，那么 URL 就是 /files//home/johndoe/myfile.txt——files 与 home 之间会出现双斜杠 //。

七、源码印证：一次声明背后的调用链

上述「一份声明，多处生效」的行为，可以从仓库源码中得到印证。

路由匹配与路径参数提取。 在 fastapi/routing.py 中，APIRoute 初始化时调用 Starlette 的 compile_path(path) 生成路径正则与参数转换器：

self.path_regex, self.path_format, self.param_convertors = compile_path(path)

（见 fastapi/routing.py#L815）

而在请求匹配阶段，路由的正则捕获到的原始字符串会立即经过 param_convertors 转换后再写入 scope["path_params"]（见 fastapi/routing.py#L1505-L1526）：

        match = self.path_regex.match(route_path)
        if not match:
            return Match.NONE, {}
        matched_params = match.groupdict()
        for key, value in matched_params.items():
            matched_params[key] = self.param_convertors[key].convert(value)
        path_params = dict(scope.get("path_params", {}))
        path_params.update(matched_params)

这说明两件事：其一，路由是按注册顺序逐个尝试 path_regex.match 的，这正解释了第四节「顺序很重要」的根本原因；其二，Starlette 的转换器（如 :path）在这一层完成字符串级别的粗转换，随后 FastAPI 再依据你的类型标注做更严格的校验与细粒度类型转换。

参数如何被识别为 Path 参数。 在依赖解析层 fastapi/dependencies/utils.py#L491-L497，当函数参数名与路由模板中的路径参数名一致、且没有显式的 Annotated/Depends 标注时，FastAPI 会自动构造 params.Path：

    elif field_info is None and depends is None:
        default_value = value if value is not inspect.Signature.empty else RequiredParam
        if is_path_param:
            field_info = params.Path(annotation=use_annotation)

也就是说，你甚至不需要写 Path(...)——函数签名里的参数名出现在路由模板中，就会被当作路径参数处理；类型标注则交给 Pydantic 完成解析、校验，并同步输出到 OpenAPI Schema，驱动 /docs 与 /redoc 的渲染。

测试覆盖。 教程示例对应的集成测试位于 tests/test_tutorial/test_path_params/，对五个示例（基础用法、int 类型校验、顺序、:path 转换器、Enum）逐一做了请求级断言；与 Starlette URL 转换器行为相关的底层测试可参考 tests/test_starlette_urlconvertors.py。

八、小结

回到这篇教程想传达的核心：在 FastAPI 中，借助简短、直观、符合标准的 Python 类型声明，你可以一次性获得：

• 编辑器支持：类型检查、代码补全等；
• 数据解析（Parsing）：请求字符串自动转成 Python 值；
• 数据校验（Validation）：非法值得到结构化、定位精确的错误响应；
• API 注解与自动文档：Swagger UI 与 ReDoc 两套界面自动生成。

而且这些能力只需声明一次。原文档将其总结为 FastAPI 相较其他框架最显著、最直观的优势之一（在原始性能之外）——这正源于「类型标注即契约」的设计：同一份声明同时服务于运行时（解析与校验）和文档时（OpenAPI 生成），源码中的路由匹配（compile_path + param_convertors）与参数推断（params.Path）两层机制保证了这种一致性。

本文所有示例均可在仓库 docs_src/path_params/ 目录中按文件名找到原始代码，德语原文档见 docs/de/docs/tutorial/path-params.md。