Query Parameters and String Validations

python

发布日期: 2020-04-11

文章字数: 934

阅读时长: 4 分

阅读次数:

Query Parameters and String Validations

FastAPI 允许对参数进行验证和声明附加信息

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

参数 q 的类型是 str，默认值为 None，因此是可选的

Additional validation

下面的例子强制要求即使 q 是可选的，但是只要被提供，长度就不能超过 50 个字符

from fastapi import FastAPI, Query

app = FastAPI()


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

步骤：

导入 Query
使用 Query 作为函数参数的默认值：
- Query 的第一个参数作为原函数参数的默认值
- 可以添加其他关键字参数来验证数据，如 max_length ，min_length，regex 等
- Query 显式表明了该参数为查询参数
- 如果 Query 有默认值，那么该参数是可选的
- 如果期望声明必须参数，可以使用 ... 作为 Query第一个参数

Query parameter list / multiple values

当使用 Query 显示定义查询参数时，可以声明该参数接受值列表

from typing import List

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: List[str] = Query(None)):
    query_items = {"q": q}
    return query_items

在上面的例子中，如果访问

http://localhost:8000/items/?q=foo&q=bar

查询参数 q 的值是一个列表

{
  "q": [
    "foo",
    "bar"
  ]
}

注：当使用 list 类型声明查询查询参数时，必须使用 Query，否则会被解释成 request body

Query parameter list / multiple values with defaults

同样的，可以为 list 类型定义默认值

from typing import List

from fastapi import FastAPI, Query

app = FastAPI()


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

如果访问

http://localhost:8000/items/

返回值为

{
  "q": [
    "foo",
    "bar"
  ]
}

注：在上述例子中，如果使用 list 代替 list[str]，那么 FastAPI 将不会做类型检查，例如

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list = Query(None)):
    query_items = {"q": q}
    return query_items

Declare more metadata

可以为参数添加更多的信息

这些信息将会被包含在自动生成的 OpenAPI 中，并且可以被用户文档界面和其他工具所使用

注：不同的工具可能对 OpenAPI 的支持程度不同

下面是利用 Query 声明额外信息的例子

添加 title

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(None, title="Query string", min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

添加 description

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str = Query(
        None,
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Alias parameters

在 Query 中使用 alias 关键字可以为参数声明别名

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(None, alias="item-query")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

在上述例子中 item-query 是 q 的别名，即访问：

http://127.0.0.1:8000/items/?item-query=foobaritems

相当于不使用别名访问

http://127.0.0.1:8000/items/?q=foobaritems

注：使用别名之后将取代原名称，即声明别名 item-query 之后，只能通过上述第一个 URL 访问

Deprecating parameters

使用 deprecated 表明该参数将被废弃(仍可以使用，但在文档中会标注)

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str = Query(
        None,
        alias="item-query",
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
        max_length=50,
        regex="^fixedquery$",
        deprecated=True,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results