FastAPI查询参数：如何用Query和Path实现参数过滤

在使用FastAPI构建API时，参数处理是核心环节之一。查询参数（URL问号后的参数）和路径参数（URL路径中的参数）是最常见的两种参数类型。FastAPI提供了Query和Path工具，帮助我们更优雅地处理这些参数的验证、过滤和文档生成。本文将通过简单示例，一步步讲解如何用它们实现参数过滤。

一、查询参数：基础使用¶

查询参数是URL中问号?后面的键值对，例如 http://example.com/greet?name=Alice&age=25 中的 name 和 age。FastAPI会自动解析这些参数并映射到函数参数上。

示例1：基础查询参数

from fastapi import FastAPI

app = FastAPI()

@app.get("/greet")
async def greet(name: str, age: int):
    return {"message": f"Hello, {name}! You are {age} years old."}

关键点：
name: str 和 age: int 是函数参数，FastAPI会自动将URL中的查询参数转换为对应类型（如字符串转整数）。
如果不提供 name 或 age，会直接报错（参数必填）。
测试：访问 http://localhost:8000/greet?name=Bob&age=20，返回 {"message": "Hello, Bob! You are 20 years old."}。

二、用Query处理查询参数过滤¶

当需要对查询参数进行验证、设置默认值或描述时，Query 工具会派上用场。例如限制参数长度、确保数值范围、设置默认值等。

1. 让参数可选（设置默认值）¶

如果查询参数不是必须的，可以通过 Query(None) 设置默认值为 None，或直接赋值默认值。

示例2：可选查询参数

from fastapi import Query

@app.get("/greet")
async def greet(
    name: str = Query(None, description="你的名字（可选）"),  # 设置默认值为None
    age: int = Query(18, description="你的年龄（默认18岁）")  # 设置默认值18
):
    return {"message": f"Hello, {name or 'Guest'}! You are {age} years old."}

关键点：
Query(None) 表示参数可选（访问时可不带该参数）。
age: int = Query(18) 直接设置默认值，若用户不提供 age，则使用18。
测试：
访问 http://localhost:8000/greet（不带参数），返回 Hello, Guest! You are 18 years old.。
访问 http://localhost:8000/greet?name=Charlie，返回 Hello, Charlie! You are 18 years old.。

2. 参数验证：限制范围和格式¶

Query 支持多种验证规则，例如限制字符串长度、数值范围、正则表达式等。

示例3：验证查询参数

from fastapi import Query

@app.get("/search")
async def search(
    keyword: str = Query(
        ...,  # 表示参数必填（必须提供，不允许默认值）
        min_length=3,  # 字符串最小长度3
        max_length=50,  # 字符串最大长度50
        description="搜索关键词（3-50字符）"
    ),
    page: int = Query(
        1,  # 默认值1
        ge=1,  # 大于等于1（ge=greater than or equal）
        le=100,  # 小于等于100（le=less than or equal）
        description="页码（1-100）"
    )
):
    return {"keyword": keyword, "page": page}

关键点：
... 显式标记参数为必填（即使未设置默认值，也可强制必填）。
min_length/max_length 限制字符串长度，ge/le 限制数值范围。
测试：
访问 http://localhost:8000/search?keyword=abc&page=5，返回正常结果。
若 keyword 长度为2（如 ab），或 page 为0/101，FastAPI会自动返回422错误：参数不符合验证规则。

三、路径参数：基础使用¶

路径参数是URL路径中固定位置的参数，例如 http://example.com/users/123 中的 123（表示用户ID）。

示例4：基础路径参数

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id, "message": f"用户 {user_id} 的信息"}

关键点：
user_id: int 表示路径参数类型为整数。
若访问 http://localhost:8000/users/abc（非整数），FastAPI会报错：参数类型错误。

四、用Path处理路径参数过滤¶

与 Query 类似，Path 用于对路径参数进行类型验证、范围过滤和描述设置。

示例5：路径参数验证

from fastapi import Path

@app.get("/users/{user_id}")
async def get_user(
    user_id: int = Path(
        ...,  # 路径参数默认必填
        gt=0,  # 大于0（gt=greater than）
        description="用户ID（必须为正整数）"
    ),
    name: str = Path(
        None,  # 可选参数
        description="用户名（可选）"
    )
):
    return {"user_id": user_id, "name": name or "未提供"}

关键点：
gt=0 确保 user_id 必须是正整数（若为负数或0，会验证失败）。
Path(None) 让 name 成为可选路径参数（若用户不提供，返回默认值）。
测试：
访问 http://localhost:8000/users/100，返回 {"user_id": 100, "name": "未提供"}。
访问 http://localhost:8000/users/-5（负数ID），FastAPI返回422错误：用户ID必须为正整数。

五、Query和Path的核心作用¶

参数验证：自动检查参数类型、范围、格式，避免非法数据进入业务逻辑。
默认值设置：让参数可选（如 Query(None)），提升接口灵活性。
文档生成：FastAPI自动将参数规则（如长度、范围）渲染到Swagger UI（访问 /docs 查看），无需手动写文档。

总结¶

查询参数用 Query 处理，可设置默认值、必填性、长度/范围验证等。
路径参数用 Path 处理，可限制整数范围、类型转换等。
Query 和 Path 不仅简化了参数过滤逻辑，还通过自动文档让API更易用。

通过合理使用这两个工具，你可以快速构建健壮、易维护的FastAPI接口，让参数处理更高效。