FastAPI 查询参数详解

在 FastAPI 中，查询参数（Query Parameters）是 URL 中?后面的部分，用于传递额外的数据。与路径参数不同，查询参数是可选的，通常用于过滤、排序或分页等场景。本文将详细介绍 FastAPI 中的查询参数，并通过多个示例帮助你更好地理解和使用它们。

什么是查询参数？

查询参数是 URL 中?后面的键值对，多个查询参数之间用&分隔。例如，在以下 URL 中：

/users?name=John&age=30

name=John和age=30就是查询参数。

name和age是键，John和30是值。

FastAPI 允许你通过定义函数参数来捕获这些查询参数，并自动进行类型转换和验证。

基本用法

让我们从一个简单的例子开始。假设我们有一个 API，用于获取用户列表，并支持通过name和age进行过滤。

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")

async def get_users(name: str = None, age: int = None):

  return {"name": name, "age": age}

代码解析

定义路径操作函数：我们使用@app.get("/users")装饰器定义了一个 GET 请求的路径操作函数。

查询参数：name和age是查询参数。它们的默认值为None，表示这些参数是可选的。

类型提示：name是str类型，age是int类型。FastAPI 会自动将查询参数转换为指定的类型。

返回结果：函数返回一个包含查询参数的字典。

测试 API

启动 FastAPI 应用后，你可以通过以下 URL 测试这个 API：

/users：返回{"name": null, "age": null}。

/users?name=John：返回{"name": "John", "age": null}。

/users?name=John&age=30：返回{"name": "John", "age": 30}。

查询参数的类型转换

FastAPI 支持多种类型的查询参数，包括int、float、str、bool等。你可以根据需要选择合适的类型。

示例：使用 bool 类型的查询参数

@app.get("/items")

async def get_items(is_active: bool = False):

  return {"is_active": is_active}

在这个例子中，is_active是一个布尔类型的查询参数。FastAPI 会自动将以下值转换为True或False：

True值：true,True,1,on,yes。

False值：false,False,0,off,no。

例如：

/items?is_active=true：返回{"is_active": true}。

/items?is_active=no：返回{"is_active": false}。

查询参数的默认值和必填性

查询参数可以是可选的，也可以是必填的。你可以通过设置默认值来控制查询参数的行为。

示例：可选查询参数

@app.get("/users")

async def get_users(name: str = None):

  return {"name": name}

在这个例子中，name是可选的。如果未提供name，FastAPI 会将其设置为None。

示例：必填查询参数

@app.get("/users")

async def get_users(name: str):

  return {"name": name}

在这个例子中，name是必填的。如果未提供name，FastAPI 会返回一个 422 错误（Unprocessable Entity）。

查询参数的验证

FastAPI 提供了强大的数据验证功能。你可以使用Query类对查询参数进行额外的验证。

示例：使用 Query 进行验证

from fastapi import Query

@app.get("/users")

async def get_users(

  name: str = Query(None, min_length=2, max_length=10),

  age: int = Query(..., gt=0, lt=100)

):

  return {"name": name, "age": age}

代码解析

Query类：Query是 FastAPI 提供的一个工具类，用于对查询参数进行额外的验证。

name参数：

默认值为None，表示可选。

min_length=2表示name的最小长度为 2。

max_length=10表示name的最大长度为 10。

age参数：

...表示必填。

gt=0表示age必须大于 0。

lt=100表示age必须小于 100。

测试 API

/users?name=Jo&age=25：返回{"name": "Jo", "age": 25}。

/users?name=JohnDoe&age=25：返回 422 错误，因为name的长度超过了 10。

/users?name=Jo&age=150：返回 422 错误，因为age必须小于 100。

查询参数与路径参数结合使用

查询参数和路径参数可以结合使用。例如，你可以通过路径参数指定资源 ID，并通过查询参数进行过滤。

示例：路径参数与查询参数结合

@app.get("/users/{user_id}/items")

async def get_user_items(

  user_id: int,

  category: str = None,

  limit: int = 10

):

  return {"user_id": user_id, "category": category, "limit": limit}

在这个例子中：

user_id是路径参数。

category和limit是查询参数。

{

"user_id": 123,

"category": "books",

"limit": 5

}

查询参数的别名

有时，查询参数的名称可能与 Python 的保留关键字冲突，或者你希望使用更友好的名称。这时，你可以使用alias为查询参数指定别名。

示例：使用别名

@app.get("/items")

async def get_items(q: str = Query(None, alias="query")):

  return {"query": q}

总结

FastAPI 的查询参数功能非常强大且灵活。通过查询参数，你可以轻松实现过滤、排序、分页等功能。FastAPI 还提供了丰富的类型支持和数据验证功能，帮助你构建健壮的 API。

在实际开发中，查询参数是构建 RESTful API 的重要组成部分。掌握查询参数的使用方法，可以帮助你更好地设计和实现 API。

希望本文对你理解和使用 FastAPI 的查询参数有所帮助！如果你有任何问题或建议，欢迎在评论区留言。