一、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参数.
常用的验证和元数据：
aliastitledescriptiondeprecated
对字符串的特定验证：
min_lengthmax_lengthregex
这一章，你明白了如果为str设置验证，下一章，我们将带你查看如果给其他类型设置验证，比如数字。
网友评论