持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第10天，点击查看活动详情

查询参数Query

• 如果想要对查询参数做更多的校验，需要使用Query
• 比如：限制查询参数q为字符串类型，且字符串长度不超过10：
• 需要注意：如果使用max_length则查询参数的类型必须是str，否则报错。
• 除此之外，类似的校验还有：min_length,对于数字类型的校验还有：gt、ge、lt、le

 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: str = Query(max_length=10)):
     results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
     if q:
         results.update({"q": q})
     return results

使用Query设置默认值

• 在Query中使用default设置查询参数的默认值。

 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: str = Query(default="q", max_length=10)):
     results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
     if q:
         results.update({"q": q})
     return results

使用Query设置查询参数可选

• 通过default设置查询参数的默认值，当默认值是None则表示该查询参数是可选的。

 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: str = Query(default=None, max_length=10)):
     results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
     if q:
         results.update({"q": q})
     return results

补充：完善可选参数的类型提示：q: Optional[str] = Query(default=None, max_length=10)

使用Query设置查询参数必选

• 原则：在Query中只要不设置default=None，该参数就是必选的

  • case1: q: str = Query()
  • case2: q: str = Query(default=...)
  • case3: q: str = Query(default="123")，此时也是必选参数，只不过URL中如果没有则使用默认值"123"

 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: str = Query(default=...)):
     results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
     print(q)
     if q:
         results.update({"q": q})
     return results

正则表达式

• Query中还可以使用正则表达式,使用regex
• 比如：下面例子中的查询参数q必须是以fix开头的字符串，且长度不超过50个

 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: str = Query(max_length=50, regex="^fix")):
     results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
     if q:
         results.update({"q": q})
     return results

查询参数有多个值

• 当你使用 Query 显式地定义查询参数时，你还可以声明它去接收一组值，或换句话来说，接收多个值。
• 比如URL: http://localhost:8000/items/?q=foo&q=bar,此时q有两个值，响应结果：{"q":["foo","bar"]}
• 此时，在openapi文档上也可以看到相对应的提示。

 from typing import List
 ​
 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: List[str] = Query(default=...)):
     query_items = {"q": q}
     return query_items

补充1：要声明类型为 list 的查询参数，如上例所示，你需要显式地使用 Query

补充2：类型提示为列表，可以使用list或者使用typing.List[str],推荐使用后者。

• 设置多个默认值

 from typing import List
 ​
 from fastapi import FastAPI, Query
 ​
 app = FastAPI()
 ​
 ​
 @app.get("/items/")
 async def read_items(q: List[str] = Query(default=["foo", "bar"])):
     query_items = {"q": q}
     return query_items

Query更多设置

• title, 设置字段标题
• description, 设置字段描述信息
• alias, 设置字段的别名，设置后在URL中只能使用设置后的别名，函数中继续使用原先变量
• deprecated=True,设置该查询参数即将弃用。