FastAPI Query 类详解：参数验证与高级用法

在 FastAPI 中，Query 类用于定义查询参数，并提供了多种参数来限制和描述这些参数。以下是一些常用的参数，它们可以用来限制和描述 Query 类的实例：

1. default:

   • 描述：设置参数的默认值。
   • 类型：任何类型。
   • 示例：default=None

2. alias:

   • 描述：为参数设置一个别名，这在 URL 中使用的名称与函数参数名称不一致时非常有用。
   • 类型：str
   • 示例：alias="my_alias"

3. title:

   • 描述：为参数设置一个标题，这通常用于 API 文档。
   • 类型：str
   • 示例：title="User ID"

4. description:

   • 描述：为参数提供一个描述，这在 API 文档中显示，有助于说明参数的用途。
   • 类型：str
   • 示例：description="The ID of the user"

5. gt (greater than):

   • 描述：参数值必须大于指定的值。
   • 类型：float 或 int
   • 示例：gt=0

6. lt (less than):

   • 描述：参数值必须小于指定的值。
   • 类型：float 或 int
   • 示例：lt=100

7. ge (greater than or equal to):

   • 描述：参数值必须大于或等于指定的值。
   • 类型：float 或 int
   • 示例：ge=0

8. le (less than or equal to):

   • 描述：参数值必须小于或等于指定的值。
   • 类型：float 或 int
   • 示例：le=100

9. min_length:

   • 描述：参数的最小长度（对于字符串）。
   • 类型：int
   • 示例：min_length=1

10. max_length:

    • 描述：参数的最大长度（对于字符串）。
    • 类型：int
    • 示例：max_length=50

11. regex:

    • 描述：参数值必须匹配指定的正则表达式。
    • 类型：str
    • 示例：regex="^[a-zA-Z0-9]+$"

12. example:

    • 描述：为参数提供一个示例值，这在 API 文档中显示。
    • 类型：任何类型。
    • 示例：example=10

这些参数可以帮助你定义查询参数的预期行为，同时提供额外的验证和文档说明。使用这些参数可以确保客户端发送的数据符合你的 API 的要求，并且可以自动生成清晰、有用的 API 文档。

为查询参数添加额外的校验和元数据，例如：

from fastapi import FastAPI, Query
from typing import Union

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: Union[str, None] = Query(default=None, min_length=3, max_length=50, regex="^fixedquery$")
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

在这个例子中，q 参数被定义为一个字符串，它有一个最小长度、最大长度和一个正则表达式模式。如果 q 参数的值不满足这些条件，FastAPI 将返回一个错误响应，并且这些验证规则会被自动记录在 API 文档中。

此外，Query 类还可以处理接收多个值的查询参数，例如：

from typing import List

@app.get("/items/")
async def read_items(q: List[str] = Query(default=["foo", "bar"], alias="query")):
    return {"queries": q}

在这个例子中，q 参数被定义为一个列表，它可以接收多个值，并且可以通过 alias 参数为它设置一个别名。