FastAPI 路径参数（Path Parameters）

1. 基础用法

fromfastapiimportFastAPI app=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id:int):return{"item_id":item_id}

# 请求curlhttp://localhost:8000/items/42# 响应: {"item_id": 42}# 类型不匹配时自动返回 422 错误curlhttp://localhost:8000/items/foo# {"detail":[{"loc":["path","item_id"],"msg":"value is not a valid integer","type":"type_error.integer"}]}

路径参数的类型由函数参数的类型注解决定，FastAPI 自动解析和验证。

2. 路径参数类型

# 整数@app.get("/items/{item_id}")asyncdefread_item(item_id:int):return{"item_id":item_id}# 字符串@app.get("/users/{username}")asyncdefread_user(username:str):return{"username":username}# 浮点数@app.get("/measurements/{value}")asyncdefread_measurement(value:float):return{"value":value}# 枚举（限定可选值）fromenumimportEnumclassModelName(str,Enum):alexnet="alexnet"resnet="resnet"lenet="lenet"@app.get("/models/{model_name}")asyncdefget_model(model_name:ModelName):ifmodel_nameisModelName.alexnet:return{"model":model_name,"message":"Deep Learning"}return{"model":model_name}# Path 类型（Path 也是 str 的子类，支持枚举）classItemType(str,Enum):book="book"electronics="electronics"@app.get("/catalog/{item_type}")asyncdefget_catalog(item_type:ItemType):return{"item_type":item_type}

3. Path() 参数验证

fromfastapiimportPathfromtypingimportOptional@app.get("/items/{item_id}")asyncdefread_item(item_id:int=Path(...,# 必填（路径参数本身就是必填的）title="项目ID",description="项目的唯一标识符",gt=0,# 大于 0le=1000000,# 小于等于 1000000),):return{"item_id":item_id}

数值约束

# 页码：1~1000 之间的整数@app.get("/pages/{page}")asyncdefread_page(page:int=Path(ge=1,le=1000),):return{"page":page}# 价格：大于 0 的浮点数，精确到 0.01@app.get("/price/{price}")asyncdefread_price(price:float=Path(gt=0,multiple_of=0.01),):return{"price":price}

字符串约束

@app.get("/users/{username}")asyncdefread_user(username:str=Path(min_length=3,max_length=20,pattern="^[a-zA-Z0-9_-]+$",# 正则：仅允许字母数字下划线连字符),):return{"username":username}

4. 多个路径参数

@app.get("/users/{user_id}/items/{item_id}")asyncdefread_user_item(user_id:int=Path(gt=0),item_id:int=Path(gt=0),):return{"user_id":user_id,"item_id":item_id}

curlhttp://localhost:8000/users/5/items/42# {"user_id": 5, "item_id": 42}

5. 路径参数顺序规则

固定路径必须在参数路径之前声明，否则会被参数路径提前匹配：

# ❌ 错误：/users/me 会被 /users/{user_id} 捕获，user_id="me"@app.get("/users/{user_id}")asyncdefread_user(user_id:str):...@app.get("/users/me")asyncdefread_me():...# ✅ 正确：固定路径在前@app.get("/users/me")asyncdefread_me():...@app.get("/users/{user_id}")asyncdefread_user(user_id:str):...

6. 路径参数 + 查询参数

fromtypingimportOptional@app.get("/items/{item_id}")asyncdefread_item(item_id:int=Path(gt=0),# 路径参数q:Optional[str]=Query(default=None),# 查询参数short:bool=Query(default=False),# 查询参数):item={"item_id":item_id}ifq:item.update({"q":q})ifnotshort:item.update({"description":"A long description"})returnitem

curl"http://localhost:8000/items/5?q=phone&short=true"# {"item_id":5,"q":"phone"}curl"http://localhost:8000/items/5"# {"item_id":5,"description":"A long description"}

7. 路径参数 + 请求体

frompydanticimportBaseModelclassItemUpdate(BaseModel):name:strprice:float@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int=Path(gt=0),item:ItemUpdate=None,# 请求体):return{"item_id":item_id,"item":item}

8. 参数声明顺序

Python 要求带默认值的参数必须在无默认值参数之后。但路径参数本身就是必填的，可以用Path(...)解决：

# ❌ 错误：Python 语法不允许非默认参数在默认参数之后asyncdefread_item(q:str,# 无默认值item_id:int=Path(gt=0),# 有默认值（Path()）):...# ✅ 方式1：都给默认值asyncdefread_item(q:str=Query(default=...),item_id:int=Path(gt=0),):...# ✅ 方式2：路径参数放前面asyncdefread_item(item_id:int=Path(gt=0),q:str=Query(default=...),):...# ✅ 方式3：FastAPI 不关心声明顺序，按参数名匹配# FastAPI 通过参数名与 Path/Query/Body 匹配，不依赖声明顺序asyncdefread_item(item_id:int=Path(gt=0),# 名为 item_id → 路径参数q:Optional[str]=None,# 名为 q → 查询参数):...

9. 包含路径的路径参数

当路径参数本身包含/时，使用 Starlette 的 path 类型：

# 普通路径参数不能包含 /@app.get("/files/{file_path}")# /files/some/file.txt → 404，因为 / 被解析为路径分隔符# 使用 :path 类型允许包含 /@app.get("/files/{file_path:path}")asyncdefread_file(file_path:str):return{"file_path":file_path}

curlhttp://localhost:8000/files/some/dir/file.txt# {"file_path": "some/dir/file.txt"}

10. OpenAPI 文档中的路径参数

路径参数自动出现在文档的Parameters区域：

@app.get("/items/{item_id}",summary="获取项目详情",# 简短描述description="根据 ID 获取项目的详细信息",# 详细描述response_model=ItemResponse,)asyncdefread_item(item_id:int=Path(...,description="项目的唯一标识符",# 参数描述),):...

在/docs页面中，item_id会显示为 required path parameter，带有描述和约束信息。

速查表

总结：路径参数的核心是URL 中的变量 + Python 类型注解自动验证。Path()提供数值/字符串约束和文档元数据，枚举类型限定可选值，:path处理含斜杠的路径值。记住固定路径声明在前、参数声明顺序不影响 FastAPI 匹配即可。