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

fastapi路径参数

news 2025/11/10 12:25:03

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

例如： http://127.0.0.1:8000/变量将这个变量写到代码中

from fastapi import FastAPIapp = FastAPI()@app.get("/items/{id}"_）
async def read_item(id):return {"item_id": id}

运行示例并访问 http://127.0.0.1:8000/items/foo，可获得如下响应：

{"item_id":"foo"}

当然也可以加入类型声明

from fastapi import FastAPIapp = FastAPI()@app.get("/items/{id}"_）
async def read_item(id：str): #声明传入的类型是strreturn {"item_id": id}

声明变量类型以后路径传入的值就应该和定义类型相符合否则会报错

查看文档

访问 http://127.0.0.1:8000/docs，查看自动生成的 API 文档：

注意路径函数顺序

有时，路径操作中的路径是写死的。
比如要使用 /users/me 获取当前用户的数据。
然后还要使用 /users/{user_id}，通过用户 ID 获取指定用户的数据。
由于路径操作是按顺序依次运行的，因此，一定要在 /users/{user_id} 之前声明 /users/me ：

from fastapi import FastAPIapp = FastAPI()@app.get("/users/me")
async def read_user_me():return {"user_id": "无聊"}@app.get("/users/{user_id}")
async def read_user(user_id: str):return {"user_id": user_id}

否则，/users/{user_id} 将匹配 /users/me，FastAPI 会认为正在接收值为 “me” 的 user_id 参数。

预设值（让用户在固定选项中跳舞）

路径操作使用 Python 的 Enum 类型接收预设的路径参数，让用户在圈子里跳舞。
创建 Enum 类
导入 Enum 并创建继承自 str 和 Enum 的子类。
通过从 str 继承，API 文档就能把值的类型定义为字符串，并且能正确渲染。
然后，创建包含固定值的类属性，这些固定值是可用的有效值：

from enum import Enumfrom fastapi import FastAPIclass ModelName(str, Enum):a1 = "a1"b2 = "b2"c3 = "c3"app = FastAPI()@app.get("/models/{model_name}")
async def get_model(model_name: ModelName): #类型注解if model_name is ModelName.a1:return {"model_name": model_name, "message": "Deep Learning FTW!"}if model_name.value == "b2":return {"model_name": model_name, "message": "LeCNN all the images"}return {"model_name": model_name, "message": "Have some residuals"}

包含路径的路径参数

在 FastAPI 中，包含路径的路径参数指的是路径参数本身包含斜杠（/）的情况（例如类似文件路径的参数，如 files/docs/intro.txt）。默认情况下，FastAPI 的路径解析会将斜杠视为路径分隔符，直接使用包含斜杠的参数会导致路由匹配失败，因此需要特殊处理。

解决方式：使用 `path` 转换器

FastAPI 提供了一个特殊的路径参数转换器 path，用于接收包含斜杠的路径字符串。使用方式是在路径参数前添加 path: 前缀，声明该参数需要匹配完整的子路径（包括斜杠）。

示例说明

假设需要实现一个接口，根据传入的文件路径（如 files/reports/2023/sales.pdf）返回对应文件的信息，代码如下：

from fastapi import FastAPIapp = FastAPI()# 使用 path 转换器接收包含路径的参数
@app.get("/get-file/{file_path:path}")
async def get_file(file_path: str):return {"file_path": file_path, "message": "文件路径解析成功"}

关键说明

路径参数声明：
路径参数 file_path 前添加了 path: 前缀，表明它会匹配 URL 中 /get-file/ 之后的所有内容（包括斜杠、子目录等）。
请求示例：
- 当访问 http://localhost:8000/get-file/files/docs/intro.txt 时，file_path 会被解析为 files/docs/intro.txt。
- 当访问 http://localhost:8000/get-file/images/photo.jpg 时，file_path 会被解析为 images/photo.jpg。
与普通路径参数的区别：
若不使用 path 转换器（即声明为 /get-file/{file_path}），则 URL 中的斜杠会被视为路径分隔符，例如访问 files/docs/intro.txt 会被 FastAPI 解析为多个路径片段，导致路由匹配失败（提示 404 错误）。