FastAPI 字符串转布尔值技巧

本文介绍了如何在 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 的健壮性和可维护性。 此外，添加异常处理可以更有效地处理无效的输入值，提供更好的用户体验。