FastAPI/Pydantic灵活的字符串到布尔类型转换实现指南

import sys
from typing import Annotated, Optional

# 兼容 Pydantic v1 和 v2 的导入
if sys.version_info >= (3, 9):
    from pydantic import BaseModel
    from pydantic.functional_validators import PlainValidator
else:
    # Pydantic v1 的导入方式，此处仅作示意，实际项目中可能需要更复杂的兼容处理
    # Pydantic v1 没有 PlainValidator，需要使用 validator 装饰器或自定义类型
    # 为了简化，本教程主要基于 Pydantic v2 的 PlainValidator
    pass

def str_to_bool_converter(v: str) -> bool:
    """
    将多种字符串表示转换为布尔值。
    不识别的字符串将导致 Pydantic 验证失败。
    """
    if not isinstance(v, str):
        # 如果输入不是字符串，Pydantic 会在 PlainValidator 之前处理类型，
        # 但为了健壮性，这里可以增加一个检查
        raise TypeError(f"Expected a string, got {type(v).__name__}")

    normalized_v = v.strip().lower() # 移除空白并转为小写，实现大小写不敏感

    # 定义“真”的字符串表示
    true_values = {"y", "yes", "on", "1", "enabled", "true"}
    # 定义“假”的字符串表示
    false_values = {"n", "no", "off", "0", "disabled", "false"}

    if normalized_v in true_values:
        return True
    elif normalized_v in false_values:
        return False
    else:
        # 如果字符串不匹配任何已知的真或假值，则抛出 ValueError
        # Pydantic 会捕获此错误并生成一个验证失败信息
        raise ValueError(f"Invalid boolean string representation: '{v}'")

# 定义可复用的扩展布尔类型
ExtendedBool = Annotated[bool, PlainValidator(str_to_bool_converter)]

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

# 假设 str_to_bool_converter 和 ExtendedBool 已经定义如上

class Misc(BaseModel):
    """
    Pydantic 模型，用于接收和验证来自外部服务的参数。
    """
    # 是否弹出复选框 ("true", "false", "yes", "no" 等)
    popup: ExtendedBool = Field(
        False, # 默认值
        description="是否弹出复选框 ('true'/'false', 'yes'/'no'等)"
    )
    # 是否有待显示的广告 ("yes", "no" 等)
    advert_pending: ExtendedBool = Field(
        False, # 默认值
        alias="advertPending", # 如果外部服务使用 camelCase
        description="是否有待显示的广告 ('yes'/'no'等)"
    )
    # 示例：一个可选的布尔字段
    is_active: Optional[ExtendedBool] = Field(
        None, # 默认值
        alias="isActive",
        description="用户是否活跃 (可选)"
    )

app = FastAPI()

@app.get("/api/status")
async def get_status(
    misc_params: Misc = Depends() # 使用 Pydantic 模型作为依赖
):
    """
    获取系统状态，演示自定义布尔类型转换。
    示例请求:
    - /api/status?popup=true&advertPending=yes
    - /api/status?popup=0&advertPending=On
    - /api/status?popup=false&advertPending=n&isActive=enabled
    - /api/status?popup=invalid_value # 将触发验证错误
    """
    return {
        "popup_status": misc_params.popup,
        "advert_pending_status": misc_params.advert_pending,
        "is_active_status": misc_params.is_active,
        "message": "参数已成功解析并转换为布尔值"
    }

# 或者直接在路径操作函数中使用 ExtendedBool
@app.get("/api/check_feature")
async def check_feature(
    feature_flag: ExtendedBool = Query(
        False, # 默认值
        alias="featureFlag",
        description="特性开关状态"
    )
):
    """
    直接在查询参数中使用 ExtendedBool。
    示例请求:
    - /api/check_feature?featureFlag=1
    - /api/check_feature?featureFlag=OFF
    """
    return {"feature_flag_status": feature_flag}

uvicorn main:app --reload