fastapi中文手册：Query参数 & 字符串验证

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

主要特性：

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

一、Query参数

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

query 参数 q 是 str 类型, 并且默认为 None, 说明它是可选的。

二、为`Query`参数附加验证

我们将设置：即使 q 是可选的，只要提供了q，它的长度就不能超过50个字符。

1. Import `Query`

为了实现这个参数验证，首先需要从 fastapi 导入 Query

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` 设置`max_length`验证

现在使用 Query方法设置参数的默认值，另外设置 max_length 为 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(None) 替换默认值None'，所以Query`的第一个参数是定义默认值。

q: str = Query(None)

…也可直接用下面方法使得参数变为可选:

q: str = None

但是Query方法明确地将其声明为查询参数。

然后，我们可以将更多参数传递给Query。在这种情况下，适用于字符串的 max_length参数：

q: str = Query(None, max_length=50)

这将验证数据，当数据无效时显示清楚的错误，并在OpenAPI Schema路径操作中记录参数。

四、添加其他验证

你也可以添加 min_length参数，设置最短长度:

q: str = Query(None, min_length=n, max_length=m)

举例：

from fastapi import FastAPI, Query

app = FastAPI()

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

五、添加正则表达式验证

您可以定义参数应匹配的正则表达式：

 q: str = Query(None, regex="regular expression") ):

举例：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
 q: str = Query(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

这个特定的正则表达式检查接收到的参数值：

^: 以…开头，之前没有字符。
fixedquery: 匹配 fixedquery 字符串.
$: 以…结尾，fixedquery后不匹配任何字符.

如果您对所有这些 **“正则表达式” ** 想法感到迷惑，请不要担心。对于许多人来说，这是一个很难的话题。您仍然可以做很多事情而无需正则表达式。

但是只要您需要正则的时候，就去学习它们，就知道您已经可以直接在** FastAPI **中使用它们了。

六、设置默认值

同样的方法，你可以不使用None作为Query第一个参数，也可以设置其他的值。

假如，你现在想设置一个查询参数为 q , 其中 min_length 为 3, 并且设置默认值为 "fixedquery":

from fastapi import FastAPI, Query

app = FastAPI()

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

注意：设置查询参数的默认值，同样使得该参数是可选的。

七、设置查询参数变为必需

当我们不需要声明更多的验证或元数据时，可以通过不声明默认值就可以使q查询参数成为必需，例如：

q: str

而不是:

q: str = None

现在我们用 Query来声明:

q: str = Query(None, min_length=3)

当你想使用 Query声明该查询参数必需的时候, 你可以使用 ... 作为第一个参数:

from fastapi import FastAPI, Query

app = FastAPI()

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

注意：如果您之前没看过...：它是一个特殊的单一值，它是Python的一部分，被称为“省略号”。
这将使 FastAPI知道此参数是必需的。

八、设置Query 参数列表 / 多个值

当你明确用 Query定义查询参数的时候，你也可以声明该参数获取一个列表，或者说获取多个值。

例如，声明查询参数 q 可以在URL中出现多次，你可以这样写：

q: List[str] = Query(None)

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

那么，URL将会如下：

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

您会在 path操作函数 中的 函数参数 q中的Python列表中收到多个q查询参数的*值（foo和bar）。

因此，对该URL的响应为:

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

注意： 要声明类型为list的查询参数，如上例所示，您需要显式使用Query，否则它将被解释为请求正文。

交互式API文档将相应更新，以允许多个值：

1. Query 参数列表/多个值设置默认值

如果没有提供值，您还可以定义一个默认值列表：

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"] 并且你的响应为:

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

2. 使用 `list`

你可以直接使用 list 而不是 List[str]:

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

注意： 留意这个例子，FastAPI将不会检查列表中的内容。
例如, List[int] 将会检查 List 里面元素是否都为整数. 但是 list 本身并不会检查。

九、声明更多元数据

您可以添加有关该参数的更多信息。

该信息将包含在生成的OpenAPI中，并由文档用户界面和外部工具使用。

注意：

请记住，不同的工具可能具有不同级别的OpenAPI支持。

尽管在大多数情况下，缺少的功能已经计划进行开发，但其中一些可能不会显示所有已声明的额外信息。

你可以添加 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

十、别名参数

如果你想设置参数为 item-query

比如:

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

但是 item-query 并不是有效的Python变量名。与之形式最像的参数名为 item_query.但是你却想参数直接为 item-query…

此时你可以定义一个 alias 参数，并且 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

十一、弃用参数

现在假如，你再也不需要某个参数了。

但是您必须将其保留一段时间，因为有许多客户在使用它，但是您希望文档将其清楚地显示为已弃用。

你只需要传递参数 deprecated=True 给 Query即可:

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

文档将会如下:

十二、总结

你可以声明一些额外的验证和元数据给你的 Query参数.

常用的验证和元数据：

alias
title
description
deprecated

对字符串的特定验证：

min_length
max_length
regex

这一章，你明白了如果为str设置验证，下一章，我们将带你查看如果给其他类型设置验证，比如数字。

{{userData.name}}已认证

一、Query参数

二、为`Query`参数附加验证

1. Import `Query`

三、使用 `Query` 设置`max_length`验证

四、添加其他验证

五、添加正则表达式验证

六、设置默认值

七、设置查询参数变为必需

八、设置Query 参数列表 / 多个值

1. Query 参数列表/多个值设置默认值

2. 使用 `list`

九、声明更多元数据

十、别名参数

十一、弃用参数

十二、总结

优惠活动

桃知优选

法律声明

在线工单

ntr教师[GALLI嘉丽] 舞蹈生日记 017 相霖[46P]

挠老师丝袜脚-模特：IESS异思趣向小六《车内办公》

肉丝美脚JKFUN-003 甜米春游【1】

模特LindaLinda VOL.731 性感上衣配蓝短裙秀完美身材写真

{{userData.name}}已认证

此组别内的文章

需要支持？

fastapi中文手册：Query参数 & 字符串验证

一、Query参数

二、为Query参数附加验证

1. Import Query

三、使用 Query 设置max_length验证

四、添加其他验证

五、添加正则表达式验证

六、设置默认值

七、设置查询参数变为必需

八、设置Query 参数 列表 / 多个值

1. Query 参数 列表/多个值 设置默认值

2. 使用 list

九、声明更多元数据

十、别名参数

十一、弃用参数

十二、总结

以下内容可能对你有帮助：

优惠活动

桃知优选

法律声明

在线工单

ntr教师[GALLI嘉丽] 舞蹈生日记 017 相霖[46P]

挠老师丝袜脚-模特：IESS异思趣向小六《车内办公》

肉丝美脚JKFUN-003 甜米 春游【1】

模特LindaLinda VOL.731 性感上衣配蓝短裙秀完美身材写真

二、为`Query`参数附加验证

1. Import `Query`

三、使用 `Query` 设置`max_length`验证

八、设置Query 参数列表 / 多个值

1. Query 参数列表/多个值设置默认值

2. 使用 `list`

肉丝美脚JKFUN-003 甜米春游【1】