查询参数

    查询字符串是键值对的集合，这些键值对位于 URL 的 之后，并以 & 符号分隔。

    例如，在以下 url 中：

    1. http://127.0.0.1:8000/items/?skip=0&limit=10

    …查询参数为：

    • skip：对应的值为 0
    • limit：对应的值为 10

    由于它们是 URL 的一部分，因此它们的”原始值”是字符串。

    但是，当你为它们声明了 Python 类型（在上面的示例中为 int）时，它们将转换为该类型并针对该类型进行校验。

    应用于路径参数的所有相同过程也适用于查询参数：

    • （很明显的）编辑器支持
    • 数据”解析”
    • 数据校验
    • 自动生成文档

    由于查询参数不是路径的固定部分，因此它们可以是可选的，并且可以有默认值。

    在上面的示例中，它们具有 skip=0 和 limit=10 的默认值。

    因此，访问 URL：

    1. http://127.0.0.1:8000/items/

    将与访问以下地址相同：

    1. http://127.0.0.1:8000/items/?skip=0&limit=10

    但是，如果你访问的是：

    1. http://127.0.0.1:8000/items/?skip=20

    函数中的参数值将会是：

    • skip=20：在 URL 中设定的值
    • limit=10：使用默认值
    1. from typing import Union
    3. from fastapi import FastAPI
    4. app = FastAPI()
    7. @app.get("/items/{item_id}")
    8. async def read_item(item_id: str, q: Union[str, None] = None):
    9.     if q:
    10.         return {"item_id": item_id, "q": q}

    在这个例子中，函数参数 q 将是可选的，并且默认值为 None。

    Check

    还要注意的是，FastAPI 足够聪明，能够分辨出参数 item_id 是路径参数而 q 不是，因此 q 是一个查询参数。

    你还可以声明 bool 类型，它们将被自动转换：

    这个例子中，如果你访问：

    1. http://127.0.0.1:8000/items/foo?short=1

    或

    1. http://127.0.0.1:8000/items/foo?short=True

    或

    1. http://127.0.0.1:8000/items/foo?short=true

    或

    1. http://127.0.0.1:8000/items/foo?short=on

    或

    1. http://127.0.0.1:8000/items/foo?short=yes

    或任何其他的变体形式（大写，首字母大写等等），你的函数接收的 short 参数都会是布尔值 True。对于值为 False 的情况也是一样的。

    你可以同时声明多个路径参数和查询参数，FastAPI 能够识别它们。

    而且你不需要以任何特定的顺序来声明。

    当你为非路径参数声明了默认值时（目前而言，我们所知道的仅有查询参数），则该参数不是必需的。

    如果你不想添加一个特定的值，而只是想使该参数成为可选的，则将默认值设置为 None。

    但当你想让一个查询参数成为必需的，不声明任何默认值就可以：

    1. from fastapi import FastAPI
    3. app = FastAPI()
    6. @app.get("/items/{item_id}")
    7. async def read_user_item(item_id: str, needy: str):
    8.     return item

    这里的查询参数 needy 是类型为 str 的必需查询参数。

    如果你在浏览器中打开一个像下面的 URL：

    …因为没有添加必需的参数 needy，你将看到类似以下的错误：

    1. {
    2.     "detail": [
    3.         {
    4.             "loc": [
    5.                 "query",
    6.                 "needy"
    7.             ],
    8.             "msg": "field required",
    9.             "type": "value_error.missing"
    10.         }
    11.     ]
    12. }

    由于 needy 是必需参数，因此你需要在 URL 中设置它的值：

    1. http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

    …这样就正常了：

    1. {
    2.     "item_id": "foo-item",
    3.     "needy": "sooooneedy"
    4. }

    当然，你也可以定义一些参数为必需的，一些具有默认值，而某些则完全是可选的：

    在这个例子中，有3个查询参数：

    • needy，一个必需的 str 类型参数。
    • limit，一个可选的 int 类型参数。

    Tip

    你还可以像在 中那样使用 。