fastapi中文手册：Query参数

FastAPI 是一个高性能 Web 框架，用于构建 API。

主要特性：

• 快速：非常高的性能，与 NodeJS 和 Go 相当
• 快速编码：将功能开发速度提高约 200％ 至 300％
• 更少的错误：减少约 40％ 的人为错误
• 直观：强大的编辑器支持，自动补全无处不在，调试时间更少
• 简易：旨在易于使用和学习，减少阅读文档的时间。
• 简短：减少代码重复。
• 稳健：获取可用于生产环境的代码，具有自动交互式文档
• 基于标准：基于并完全兼容 API 的开放标准 OpenAPI 和 JSON Schema 

一、Query参数

当你声明不属于路径参数的其他函数参数时，它们将自动解释为“Query”参数，也就是查询参数。

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]

query就是一系列的在URL?之后的key-value键值对，每对键值对用 & 分割开来。

例如，在这个URL：

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

…查询参数是:

• skip: 值为 0
• limit: 值为 10

由于它们都是URL的一部分，所以 “本质上” 它们都是字符串。

但是当你需要使用Python类型来声明query参数的时候(如上面的例子，需要用int)，他们就会被转换为响应的类型并且依据这个类型来验证传入参数。

适用于Path参数的所有过程也适用于Query参数

• 编辑器支持
• 数据解析
• 数据验证
• 自动文档

二、设置默认Query参数

query参数类不是path中固定的一部分，所以他们是可选的，并且可以有默认值。

在上面的例子中, 可以看到query参数拥有默认值 skip=0 和 limit=10.

那么，如果访问到这个URL：

http://127.0.0.1:8000/items/

将执行以下相同操作：

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

但是，如果你跳转到下面的地址：

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

视图函数中Query参数的值如下：

• skip=20: URL中设定的值
• limit=10: 默认的值

三、设置可选Query参数

同样，你也可以声明可选的Query参数，只需要将他们的默认值设置为None即可。

from fastapi import FastAPI

app = FastAPI()

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

在这个例子中，是凸函数参数q是可选的查询参数，默认值是None.

注意： FastAPI 足够灵活去区分 item_id 是路径参数，并且 q 是一个查询参数。

四、Query参数类型转换

你也可以将查询参数声明为 bool 类型，那么传入的参数会被转换：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str = 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

或者其他类型的变量，视图函数将会把query参数 short 转换为 True 或者 False.

五、同时使用 Path参数 和 Query参数的

你也可以同时声明多个Path参数和Query参数，*FastAPI 会分别区分参数。

你并不需要声明它们的时候按照指定的顺序，因为这些参数可以被参数名检测到

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, 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

六、必需的查询参数

当你需要定义一个查询参数，而且这个参数必须传入，那么你就不能为这个参数定义任意的默认值：

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": [
        {
            "loc": [
                "query",
                "needy"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

报错显示 needy 是必需的查询参数，需要在URL中设定.

现在访问如下路径：

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

…浏览器不报错，显示如下:

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

当然，您可以根据需要定义一些参数，一些具有默认值，而某些则完全可选：

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):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

在上面的例子中，这里有3个查询参数：

• needy, 必需传入的，且类型为str.
• skip, 类型为 int 且默认值为 0.
• limit, 可选传入参数 int.

建议

你也可以使用 Path 参数 中的 Enum 方法 the same way as with path parameters.

七、可选的类型声明

1. 警告

这可能是高级用法的示例。

如果你正在使用 cert，它可能出现如下的类型声明：

limit: int = None

将会报错如下：

Incompatible types in assignment (expression has type "None", variable has type "int")

在这个例子中，你可以使用 Optional 告诉 cert，这个值可能是 None，比如：

from typing import Optional

limit: Optional[int] = None

在 路径操作 中使用：

from typing import Optional

from fastapi import FastAPI

app = FastAPI()

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

注意： 该用法在 Path参数 中不可使用！