17 FastAPI中的查询参数使用示例

在上一篇文章中，我们讨论了路径参数的使用，包括如何在FastAPI中定义和使用这些参数。今天，我们将重点关注查询参数的使用，以及如何在实际应用中将其与路径参数结合使用。

什么是查询参数？

查询参数是通过URL进行传递的额外数据，通常以键值对的形式出现在URL的问号?后面。例如，在以下URL中：

https://example.com/items?search=foo&limit=10

这里的search和limit就是查询参数。

在FastAPI中，查询参数显式地定义为函数参数，并且可以设置默认值。让我们来看一些案例。

基本使用示例

下面是一个简单的FastAPI应用示例，演示了如何定义和使用查询参数。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(search: str = None, limit: int = 10):
    return {"search": search, "limit": limit}

在这个示例中，我们定义了一个GET请求的路由/items/，其中包含两个查询参数：

• search: 一个可选的字符串参数，用于搜索项。
• limit: 一个整数参数，表示返回的最大项目数量，默认为10。

访问查询参数

要访问这些查询参数，只需要在URL中添加相应的键值对。例如，发送以下请求：

GET /items/?search=python&limit=5

将返回：

{
  "search": "python",
  "limit": 5
}

如果不提供查询参数search，则返回的结果为：

{
  "search": null,
  "limit": 10
}

多个查询参数的组合

FastAPI允许组合使用多个查询参数，很容易构建复杂的查询请求。以下是一个示例，演示如何在同一个端点中使用多个查询参数。

@app.get("/products/")
async def read_products(category: str = None, max_price: float = None):
    return {"category": category, "max_price": max_price}

可以通过如下URL请求：

GET /products/?category=electronics&max_price=300

返回：

{
  "category": "electronics",
  "max_price": 300
}

如果不提供category和max_price，将得到：

{
  "category": null,
  "max_price": null
}

查詢參數的數據驗證

在FastAPI中，你可以对查询参数进行更复杂的验证。例如，你可以添加自定义验证，将limit限制在一定的范围内：

from fastapi import Query

@app.get("/items/")
async def read_items(
    search: str = None,
    limit: int = Query(default=10, le=100, ge=1)  # limit必须在1到100之间
):
    return {"search": search, "limit": limit}

此代码段中，我们使用了Query来定义limit的合法范围。如果请求的limit不在这个范围内，将返回422错误。

总结

在这篇文章中，我们介绍了FastAPI中的查询参数，包括如何定义、访问和验证这些参数。查询参数是构建灵活API的一部分，使得客户端能够更方便地与服务端交互。通过使用默认值和验证器，我们可以有效地控制输入，保证数据的有效性。

在下一篇文章中，我们将讨论路径参数与查询参数的参数类型的定义与验证，继续深入探讨FastAPI的强大特性。