FastAPI 路径参数

FastAPI 路径参数Path Parameters1. 基础用法fromfastapiimportFastAPI appFastAPI()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):alexnetalexnetresnetresnetlenetlenetapp.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):bookbookelectronicselectronicsapp.get(/catalog/{item_type})asyncdefget_catalog(item_type:ItemType):return{item_type:item_type}3. Path() 参数验证fromfastapiimportPathfromtypingimportOptionalapp.get(/items/{item_id})asyncdefread_item(item_id:intPath(...,# 必填路径参数本身就是必填的title项目ID,description项目的唯一标识符,gt0,# 大于 0le1000000,# 小于等于 1000000),):return{item_id:item_id}数值约束约束含义适用类型gt大于int,floatge大于等于int,floatlt小于int,floatle小于等于int,floatmultiple_of必须是某数的倍数int,float# 页码1~1000 之间的整数app.get(/pages/{page})asyncdefread_page(page:intPath(ge1,le1000),):return{page:page}# 价格大于 0 的浮点数精确到 0.01app.get(/price/{price})asyncdefread_price(price:floatPath(gt0,multiple_of0.01),):return{price:price}字符串约束约束含义min_length最小长度max_length最大长度pattern正则匹配app.get(/users/{username})asyncdefread_user(username:strPath(min_length3,max_length20,pattern^[a-zA-Z0-9_-]$,# 正则仅允许字母数字下划线连字符),):return{username:username}4. 多个路径参数app.get(/users/{user_id}/items/{item_id})asyncdefread_user_item(user_id:intPath(gt0),item_id:intPath(gt0),):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_idmeapp.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. 路径参数 查询参数fromtypingimportOptionalapp.get(/items/{item_id})asyncdefread_item(item_id:intPath(gt0),# 路径参数q:Optional[str]Query(defaultNone),# 查询参数short:boolQuery(defaultFalse),# 查询参数):item{item_id:item_id}ifq:item.update({q:q})ifnotshort:item.update({description:A long description})returnitemcurlhttp://localhost:8000/items/5?qphoneshorttrue# {item_id:5,q:phone}curlhttp://localhost:8000/items/5# {item_id:5,description:A long description}7. 路径参数 请求体frompydanticimportBaseModelclassItemUpdate(BaseModel):name:strprice:floatapp.put(/items/{item_id})asyncdefupdate_item(item_id:intPath(gt0),item:ItemUpdateNone,# 请求体):return{item_id:item_id,item:item}8. 参数声明顺序Python 要求带默认值的参数必须在无默认值参数之后。但路径参数本身就是必填的可以用Path(...)解决# ❌ 错误Python 语法不允许非默认参数在默认参数之后asyncdefread_item(q:str,# 无默认值item_id:intPath(gt0),# 有默认值Path()):...# ✅ 方式1都给默认值asyncdefread_item(q:strQuery(default...),item_id:intPath(gt0),):...# ✅ 方式2路径参数放前面asyncdefread_item(item_id:intPath(gt0),q:strQuery(default...),):...# ✅ 方式3FastAPI 不关心声明顺序按参数名匹配# FastAPI 通过参数名与 Path/Query/Body 匹配不依赖声明顺序asyncdefread_item(item_id:intPath(gt0),# 名为 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_modelItemResponse,)asyncdefread_item(item_id:intPath(...,description项目的唯一标识符,# 参数描述),):...在/docs页面中item_id会显示为 required path parameter带有描述和约束信息。速查表用法示例说明基础item_id: int自动类型转换和验证验证Path(gt0, le100)数值范围约束字符串验证Path(min_length3, pattern...)长度和正则约束枚举限制ModelName(str, Enum)限定可选值路径包含/{file_path:path}允许参数值含/多路径参数/users/{uid}/items/{iid}按名称匹配固定路径优先/users/me在/users/{id}前避免被参数捕获总结路径参数的核心是URL 中的变量 Python 类型注解自动验证。Path()提供数值/字符串约束和文档元数据枚举类型限定可选值:path处理含斜杠的路径值。记住固定路径声明在前、参数声明顺序不影响 FastAPI 匹配即可。