查询参数¶

当您声明了路径参数以外的其他函数参数时，它们会自动被解释为“查询”参数。

Python 3.9+

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

查询参数是以 ? 符号分隔的一组键值对，后面跟着 URL，并用 & 字符分隔。

例如，在 URL 中

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

查询参数是

skip：值为 0
limit：值为 10

由于它们是 URL 的一部分，“自然”而言是字符串。

但是当您使用 Python 类型声明它们时（在上例中，为 int），它们将被转换为该类型并进行验证。

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

编辑器支持（显然）
数据 “解析”
数据验证
自动文档

默认值¶

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

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

因此，访问 URL

http://127.0.0.1:8000/items/

将与访问 URL 相同

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

但是如果您访问，例如

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

您函数中的参数值将是

skip=20：因为您在 URL 中设置了它
limit=10：因为那是默认值

可选参数¶

同样，您可以通过将默认值设置为 None 来声明可选的查询参数。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

🤓 其他版本和变体

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

在这种情况下，函数参数 q 将是可选的，默认值为 None。

检查

另请注意，**FastAPI** 足够智能，能够识别出路径参数 item_id 是一个路径参数，而 q 不是，因此它是一个查询参数。

查询参数类型转换¶

您也可以声明 bool 类型，它们将被转换。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

🤓 其他版本和变体

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

在这种情况下，如果您访问

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

或者

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

或者

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

或者

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

或者

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

或者任何其他大小写变体（全大写、首字母大写等），您的函数将看到参数 short 的 bool 值为 True。否则为 False。

多个路径和查询参数¶

您可以同时声明多个路径参数和查询参数，**FastAPI** 会知道它们各自的类型。

而且您不必按特定顺序声明它们。

它们将通过名称进行检测。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: str | None = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

🤓 其他版本和变体

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: Union[str, None] = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

必需的查询参数¶

当您为非路径参数（目前，我们只看到过查询参数）声明默认值时，它就不是必需的。

如果您不想添加特定值但只想使其可选，请将默认值设置为 None。

但是当您想使查询参数必需时，您可以不声明任何默认值。

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item

在这里，查询参数 needy 是一个必需的 str 类型查询参数。

如果您在浏览器中打开一个类似以下的 URL

http://127.0.0.1:8000/items/foo-item

在不添加必需的参数 needy 的情况下，您将看到类似以下的错误

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "query",
        "needy"
      ],
      "msg": "Field required",
      "input": null
    }
  ]
}

由于 needy 是一个必需的参数，您需要在 URL 中设置它。

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

……这样就可以工作了。

{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}

当然，您可以定义一些参数为必需的，一些参数具有默认值，还有一些参数完全可选。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

🤓 其他版本和变体

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

在这种情况下，有 3 个查询参数：

needy，一个必需的 str。
skip，一个 int，默认值为 0。
limit，一个可选的 int。

提示

您也可以使用 Enum，就像在路径参数中一样。