FASTAPI 设置查询参数可选或必选

在 FastAPI 中灵活定义查询参数：必选和可选

在构建 RESTful API 时，我们经常需要从客户端请求中获取数据，这通常是通过查询参数实现的。FastAPI 为我们提供了灵活且强大的方法来定义查询参数，包括必选和可选参数。

必选查询参数

什么是必选查询参数？

必选查询参数是客户端请求中必须提供的参数。如果没有提供这些参数，API 将返回错误响应。

如何定义必选查询参数？

在 FastAPI 中，我们可以通过使用 Query 类并省略 default 参数来定义必选查询参数。以下是示例代码：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = Query(...)):
    return {"q": q}

在这种情况下，q 是一个必选的查询参数。如果客户端不提供 q 参数，FastAPI 将返回 422 Unprocessable Entity 错误。

可选查询参数

什么是可选查询参数？

可选查询参数是客户端请求中可以提供或不提供的参数。如果没有提供这些参数，API 将使用默认值。

如何定义可选查询参数？

我们可以通过使用 Query 类并提供一个 default 参数来定义可选查询参数。以下是示例代码：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = Query(None)):
    return {"q": q}

在这种情况下，q 是一个可选的查询参数。如果客户端不提供 q 参数，FastAPI 将使用 default 参数 None。

默认值

我们可以为查询参数指定默认值，以便在客户端未提供该参数时使用。以下是示例代码：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = Query("default")):
    return {"q": q}

在这种情况下，q 的默认值是 "default"。如果客户端不提供 q 参数，FastAPI 将使用 "default" 作为 q 的值。

数据类型

我们可以使用 Query 类的 type 参数来指定查询参数的数据类型。以下是示例代码：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: int = Query(...)):
    return {"q": q}

在这种情况下，q 的数据类型是 int。如果客户端提供了一个非整型的 q 参数，FastAPI 将返回 422 Unprocessable Entity 错误。

我们可以使用 Query 类的 description 参数为查询参数添加。以下是示例代码：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = Query(..., description="The query string")):
    return {"q": q}

在这种情况下，q 的描述是 "The query string"。当用户在 API 文档中查看 q 参数时，他们将看到这个描述。

总结

通过使用 Query 类，我们可以轻松地定义必选和可选的查询参数。我们还可以为查询参数指定默认值、数据类型和描述。这使得 FastAPI 非常适合构建具有灵活输入选项的 API。

常见问题解答

1. 什么时候应该使用必选查询参数？

当客户端必须提供特定信息才能处理请求时，应使用必选查询参数。

2. 什么时候应该使用可选查询参数？

当客户端可以提供或不提供特定信息时，应使用可选查询参数。

3. 我可以指定多个查询参数吗？

是的，你可以使用 Query 类定义任意数量的查询参数。

4. 如何处理无效的查询参数值？

FastAPI 会自动验证查询参数值是否与指定的数据类型匹配。如果值无效，FastAPI 将返回 422 Unprocessable Entity 错误。

5. 如何在 FastAPI 文档中显示查询参数？

FastAPI 会自动在 API 文档中显示查询参数。你还可以使用 description 参数添加描述。