fastapi教程翻译(三)：Query参数
一、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. 警告
这可能是高级用法的示例。
如果你正在使用 mypy ，它可能出现如下的类型声明：
limit: int = None
将会报错如下：
Incompatible types in assignment (expression has type "None", variable has type "int")
在这个例子中，你可以使用 Optional 告诉 mypy，这个值可能是 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参数中不可使用！
