本文介绍了如何在 FastAPI 应用中，将外部服务传递的字符串参数（如 "true"、"false"、"yes"、"no" 等）自动转换为布尔类型。通过自定义 Pydantic 验证器，我们能够灵活地处理各种字符串表示形式，确保数据类型的一致性和准确性，提升 API 的健壮性和易用性。
在构建 FastAPI 应用时，经常需要处理来自外部服务的请求参数。这些参数通常以字符串的形式传递，但有时我们需要将其转换为其他数据类型，例如布尔值。本教程将介绍如何利用 Pydantic 的验证器功能，优雅地实现字符串到布尔值的自动转换。
1. 创建自定义验证器函数
首先，我们需要创建一个函数，将各种字符串表示形式转换为布尔值。这个函数会接收一个字符串作为输入，并返回一个布尔值。
def str_to_bool(v: str) -> bool:
v = v.strip().lower()
if v in ["y", "yes", "on", "1", "enabled", "true"]:
return True
if v in ["n", "no", "off", "0", "disabled", "false"]:
return False
raise ValueError(f"Invalid boolean value: {v}") # 添加异常处理注意事项：
- v.strip().lower(): 对输入字符串进行预处理，去除首尾空格并转换为小写，以提高匹配的鲁棒性。
- 异常处理：如果输入字符串不属于任何已知的布尔值表示形式，则抛出一个 ValueError 异常，可以帮助开发者更好地发现和处理错误。
2. 使用 Annotated 和 PlainValidator 将验证器应用于 Pydantic 模型
接下来，我们使用 Annotated 和 PlainValidator 将自定义的 str_to_bool 函数应用于 Pydantic 模型中的字段。
from typing import Optional, Annotated
from pydantic import BaseModel
from pydantic.functional_validators import PlainValidator
extended_bool = Annotated[bool, PlainValidator(str_to_bool)]
class Misc(BaseModel):
# - whether to pop-up checkbox ("true" or "false")
popup: Optional[extended_bool] = None
# - whether an advertisement is pending to be displayed ("yes" or "no")
advertPending: Optional[extended_bool] = None解释：
- extended_bool = Annotated[bool, PlainValidator(str_to_bool)]: 这行代码创建了一个名为 extended_bool 的类型，它本质上是一个布尔类型，但附加了一个自定义的验证器 str_to_bool。
- popup: Optional[extended_bool] = None: 在 Misc 模型中，popup 字段被声明为 Optional[extended_bool]，这意味着它可以是 extended_bool 类型（即经过 str_to_bool 验证的布尔值），也可以是 None。
- Optional 的使用: 如果外部服务没有提供 popup 或 advertPending 的值，它们将保持为 None，不会触发验证器。
3. FastAPI 路由示例
现在，我们可以在 FastAPI 路由中使用这个 Pydantic 模型。
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(misc: Misc = Query(default=None)):
return misc示例用法：
- 访问 http://localhost:8000/items/?popup=true&advertPending=no 将返回：
{
"popup": true,
"advertPending": false
}- 访问 http://localhost:8000/items/?popup=1&advertPending=0 将返回：
{
"popup": true,
"advertPending": false
}- 访问 http://localhost:8000/items/?popup=invalid 将返回一个错误，因为 "invalid" 不是一个有效的布尔值表示形式。
4. 总结
通过使用 Pydantic 的 Annotated 和 PlainValidator，我们可以轻松地实现字符串到布尔值的自动转换，并将其集成到 FastAPI 应用中。 这种方法不仅代码简洁，而且类型安全，提高了 API 的健壮性和可维护性。 此外，添加异常处理可以更有效地处理无效的输入值，提供更好的用户体验。
