FastAPI 中的 Query：优化你的数据获取策略

黑金IT

已于 2024-09-02 19:16:58 修改

阅读量828

点赞数 17

文章标签： fastapi python

于 2024-09-02 19:02:45 首次发布

本文链接：https://blog.csdn.net/ylong52/article/details/141827266

版权

在 FastAPI 中，Query 是一个依赖项类，用于处理来自 HTTP 请求的查询参数。查询参数是 URL 的一部分，通常用于 GET 请求，它们在 URL 的路径之后，以 ? 开头，参数之间用 & 分隔。例如：http://example.com/api/items?name=foo&age=42。

`Query` 的作用和用途：

类型声明：Query 允许你为查询参数声明一个预期的数据类型，如 str、int、float、bool 等。这有助于确保接收到的数据类型正确，并且可以在请求不符合预期时自动生成错误响应。
默认值：你可以为查询参数指定一个默认值，如果客户端没有提供该参数，就会使用默认值。
验证：Query 可以用于验证传入的数据，例如，检查字符串的长度、数值的范围等。
文档生成：FastAPI 会自动生成交互式 API 文档（如 Swagger UI），Query 的参数会作为文档的一部分，提供参数的类型、默认值、描述等信息，这有助于 API 的使用者理解如何正确地使用 API。
依赖注入：在 FastAPI 中，Query 用作依赖注入的一部分，这意味着你可以在路由函数中直接使用它，FastAPI 会处理参数的解析和验证。

`Query` 的优点：

自动验证：通过 Query 声明的参数会自动进行类型验证和值验证，如果请求不符合参数的声明，FastAPI 会返回一个清晰的错误响应。
减少代码冗余：使用 Query 可以减少手动解析和验证查询参数的代码，使得路由函数更加简洁。
提高安全性：通过声明预期的数据类型和值，Query 有助于防止不安全的或恶意的数据输入。
增强可读性：在路由函数中使用 Query 可以清晰地表明哪些参数是可选的，哪些是必需的，以及它们的默认值和类型。
易于维护：当 API 发生变化时，只需更新 Query 的声明即可，无需修改大量的手动解析代码。
自动文档：Query 的参数信息会自动包含在 API 文档中，这对于 API 的测试和文档维护非常有用。
灵活性：Query 支持多种参数选项，如 alias、title、description、examples 等，这些都可以用于增强 API 文档的可读性和易用性。

Query 是 FastAPI 中处理查询参数的强大工具，它通过提供类型安全、自动验证、文档生成和依赖注入等功能，极大地简化了
API 的开发和维护工作。

示例：

FastAPI 路由以接受两个查询参数 q 和 name，你可以在函数签名中定义这两个参数。以下是如何修改你的代码来实现这一点：

from typing import Union
from fastapi import FastAPI, Query

app = FastAPI()

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

在这个例子中，q 参数保持不变，它是一个可选的字符串，可以为 None，并且有一个最大长度限制。name 参数是新添加的，它也是一个可选的字符串，并且默认为空字符串（""）。如果客户端在查询中提供了 name 参数，它将被包含在响应中。

如何传值：

传递 q 和 name 参数:
请求 URL: /items/?q=some_query&name=JohnDoe
结果: {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}], "q": "some_query", "name": "JohnDoe"}
只传递 q 参数:
请求 URL: /items/?q=some_query
结果: {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}], "q": "some_query"}
只传递 name 参数:
请求 URL: /items/?name=JohnDoe
结果: {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}], "name": "JohnDoe"}
不传递任何参数:
请求 URL: /items/
结果: {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
传递空字符串作为 q 或 name 参数:
请求 URL: /items/?q=&name=
结果: {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}], "q": "", "name": ""}

这样，你的 API 端点现在可以灵活地处理两个查询参数，并且可以根据客户端的请求返回相应的数据。

示例二：
作业：

from fastapi import FastAPI, Query
from typing import Union, Literal

app = FastAPI()

@app.get("/items/")
async def read_items(q: Union[Literal["true", "false"], None] = Query(default=None, alias="q")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

提示

Union[Literal[“true”, “false”], None]
Union：这是 Python 类型提示中的一个特殊类型，表示参数可以接受多种类型中的任意一种。在这里，它表示 q 参数可以是两种类型中的任意一种。
Literal[“true”, “false”]：这是 Python 3.8 引入的一个类型提示，用于指示变量只能是括号中列出的确切字符串字面值。在这个例子中，Literal 指定 q 参数只能是字符串 “true” 或 “false”。
None：表示 q 参数也可以是 None 类型，即不提供该参数。
综合来看，Union[Literal[“true”, “false”], None] 表示 q 参数可以是字符串 “true”、字符串 “false” 或者是 None。

Query(default=None, alias=“q”)
Query：这是 FastAPI 中的一个依赖项类，用于声明一个 HTTP 请求的查询参数。
default=None：这是 Query 的一个参数，指定了当查询参数 q 没有在请求中提供时的默认值。在这个例子中，如果 q 没有被包含在请求中，它的值将默认为 None。
alias=“q”：这是 Query 的另一个参数，用于指定查询参数在 URL 中的实际名称。在这个例子中，即使在函数签名中使用了 alias，查询参数在 URL 中仍然应该使用 “q” 作为键。通常，alias 参数用于在函数参数名和 URL 中的参数名不一致时提供别名，但在这个例子中，它似乎没有改变任何东西，因为别名和参数名相同。