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

Python FastApi（3）：路径参数

news 来源：原创 2025/5/8 16:42:36

FastAPI 支持使用 Python 字符串格式化语法声明路径参数（变量）：

from fastapi import FastAPI

app = FastAPI()


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

这段代码把路径参数 item_id 的值传递给路径函数的参数 item_id。运行示例并访问 http://127.0.0.1:8000/items/foo，可获得如下响应：

1 声明路径参数的类型

声明路径操作函数中路径参数的类型，默认则解析为str。类型声明将为函数提供错误检查、代码补全等编辑器支持。本例把 item_id 的类型声明为 int。

from fastapi import FastAPI

app = FastAPI()


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

运行示例并访问 http://127.0.0.1:8000/items/3，返回的响应如下：

注意，函数接收并返回的值是 3（ int），不是 "3"（str）。FastAPI 通过类型声明自动解析请求中的数据。

通过浏览器访问 http://127.0.0.1:8000/items/foo，接收如下 HTTP 错误信息：

{
    "detail": [
        {
            "loc": [
                "path",
                "item_id"
            ],
            "msg": "value is not a valid integer",
            "type": "type_error.integer"
        }
    ]
}

这是因为路径参数 item_id 的值（"foo"）的类型不是 int。值的类型不是 int 而是浮点数（float）时也会显示同样的错误，比如： http://127.0.0.1:8000/items/4.2。

FastAPI 使用 Python 类型声明实现了数据校验。注意，上面的错误清晰地指出了未通过校验的具体原因。这在开发调试与 API 交互的代码时非常有用。

2 查看文档

访问 http://127.0.0.1:8000/docs，查看自动生成的 API 文档，注意，路径参数的类型是整数。

FastAPI 使用 OpenAPI 生成概图，所以能兼容很多工具。因此，FastAPI 还内置了 ReDoc 生成的备选 API 文档，可在此查看 http://127.0.0.1:8000/redoc：

3 顺序

有时，路径操作中的路径是写死的。比如要使用 /users/me 获取当前用户的数据。然后还要使用 /users/{user_id}，通过用户 ID 获取指定用户的数据。由于路径操作是按顺序依次运行的，因此，一定要在 /users/{user_id} 之前声明 /users/me ，否则，/users/{user_id} 将匹配 /users/me，FastAPI 会认为正在接收值为 "me" 的 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}

4 预设值

路径操作使用 Python 的 Enum 类型接收预设的路径参数。

4.1 创建 `Enum` 类

导入 Enum 并创建继承自 str 和 Enum 的子类。通过从 str 继承，API 文档就能把值的类型定义为字符串，并且能正确渲染。然后，创建包含固定值的类属性，这些固定值是可用的有效值：

from enum import Enum

from fastapi import FastAPI


# AlexNet、ResNet、LeNet 是机器学习模型。
class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

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

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

API 文档会显示预定义路径参数的可用值：

4.2 使用 Python 枚举类型

枚举类 ModelName 中的枚举元素支持比较操作：

使用 model_name.value 或 your_enum_member.value 获取实际的值（本例中为字符串）：

即使嵌套在 JSON 请求体里（例如， dict），也可以从路径操作返回枚举元素。返回给客户端之前，要把枚举元素转换为对应的值。客户端中的 JSON 响应如下：

5 包含路径的路径参数

假设路径操作的路径为 /files/{file_path}。但需要 file_path 中也包含路径，比如，home/johndoe/myfile.txt。

OpenAPI 不支持声明包含路径的路径参数，因为这会导致测试和定义更加困难。不过，仍可使用 Starlette 内置工具在 FastAPI 中实现这一功能。而且不影响文档正常运行，但是不会添加该参数包含路径的说明。

此时，该文件的 URL 是这样的：/files/home/johndoe/myfile.txt。直接使用 Starlette 的选项声明包含路径的路径参数：

/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}

注意，包含 /home/johndoe/myfile.txt 的路径参数要以斜杠（/）开头。本例中的 URL 是 /files//home/johndoe/myfile.txt。注意，files 和 home 之间要使用双斜杠（//）。