什么是路径参数？
路径参数是 URL 路径中的变量部分，用于捕获特定的值并传递给请求处理函数。它们使得我们能够创建动态的路由，根据不同的参数值返回不同的内容。
基础用法
1. 固定路径路由
from fastapi import FastAPI
app = FastAPI()
@app.get("/args1/1")
def path_args1():
return {"message": "id1"}这是最简单的路由形式，路径是固定的，不包含任何参数。访问 /args1/1 将始终返回相同的响应。
2. 带参数路径的基本定义
@app.get("/args2/{id}")
def path_args2():
return {"message": "id2"}注意：这个例子实际上有一个问题！我们在路径中定义了 {id} 参数，但在函数参数中没有接收它。虽然语法上不会报错，但这通常不是我们想要的行为。
3. 正确的参数接收
@app.get("/args3/{id}")
def path_args3(id):
'''函数的顺序就是路由的顺序'''
return {"message": id}这是正确的用法。路径中的 {id} 会被捕获并作为参数传递给函数。访问 /args3/123 将返回 {"message": "123"}。
类型注解的重要性
4. 使用类型提示
@app.get("/args4/{id}")
def path_args4(id: int):
'''函数的顺序就是路由的顺序'''
return {"message": id}通过添加 : int 类型注解，FastAPI 会自动进行以下操作：
数据验证：确保传入的值可以转换为整数
数据转换：将字符串参数自动转换为整数类型
API 文档：在自动生成的文档中显示参数类型
如果访问 /args4/abc，FastAPI 会自动返回一个错误响应，说明参数类型不匹配。
多参数路由
5. 多个路径参数
@app.get("/args5/{id}/{name}")
def path_args5(id: str, name: str):
'''函数的顺序就是路由的顺序'''
return {"id": id, "name": name}可以定义包含多个参数的路由。参数在函数中的顺序应该与它们在路径中出现的顺序一致，但 FastAPI 实际上会根据参数名称进行匹配，所以顺序不是强制性的。
访问 /args5/123/john 将返回：
{
"id": "123",
"name": "john"
}路径参数的高级特性
类型支持的丰富性
FastAPI 支持丰富的 Python 类型：
from datetime import datetime
from typing import List, Optional
@app.get("/users/{user_id}/posts/{post_id}")
def get_user_post(
user_id: int,
post_id: int,
category: Optional[str] = None
):
return {
"user_id": user_id,
"post_id": post_id,
"category": category
}使用枚举限制参数值
from enum import Enum
class UserType(str, Enum):
ADMIN = "admin"
USER = "user"
GUEST = "guest"
@app.get("/users/{user_type}/{user_id}")
def get_user_by_type(user_type: UserType, user_id: int):
return {
"user_type": user_type,
"user_id": user_id
}文件路径作为参数
@app.get("/files/{file_path:path}")
def read_file(file_path: str):
return {"file_path": file_path}使用 :path 转换器可以匹配包含斜杠的路径。
最佳实践
始终使用类型注解：这不仅能提供自动验证，还能改善代码的可读性和 IDE 支持。
参数命名要有意义：使用清晰的参数名称，如
user_id而不是简单的id。考虑参数顺序：虽然 FastAPI 按名称匹配，但保持路径中参数顺序与函数参数顺序一致可以提高代码可读性。
合理使用默认值和可选参数：对于非必需的参数，使用
Optional类型和默认值。文档字符串：为你的路由函数添加文档字符串，这些会自动显示在 API 文档中。