Pydantic 中如何为 Literal 字段处理空字符串并自动回退到默认值

Pydantic 中如何为 Literal 字段处理空字符串并自动回退到默认值

当 Pydantic 字段使用 Literal 类型（如 "enabled" | "disabled"）时，空字符串 "" 会直接触发类型校验失败，而非应用默认值；本文介绍通过 @field_validator(mode="before") 在解析前拦截并替换空值，实现优雅的默认值回退机制。

在使用 Pydantic 进行数据验证时，你是否遇到过这样的场景：一个字段只允许接受特定的几个字面值，比如 `"enabled"` 或 `"disabled"`。当用户不小心传了一个空字符串 `""` 进来，你期望它能优雅地回退到预设的默认值，但结果却直接抛出了一个冷冰冰的类型错误。这背后的原因，正是 Pydantic 对 Literal 类型的严格校验逻辑。

在 Pydantic v2 及更高版本中，Literal 类型字段的校验规则非常严格——它要求输入值必须精确等于声明的字面量之一。换句话说，只有 `"enabled"` 或 `"disabled"` 能过关，而空字符串 `""`、`None` 或者其他任何字符串都会在第一时间被拒绝，并触发一个 `literal_error`。关键在于，这个错误发生在 Pydantic 内置的校验层，甚至早于你编写的任何自定义验证器逻辑。这就是为什么你可能会发现，自己写的 `@validator` 装饰器根本没被调用。

那么，如何破解这个僵局呢？核心思路在于：赶在 Pydantic 执行严格的字面量匹配之前，先一步拦截那些“非法但情有可原”的输入，比如空字符串，并把它修正为合理的值。这正是 `mode="before"` 模式验证器的用武之地。

下面是一个完整且可直接运行的解决方案：

from pydantic import BaseModel, Field, field_validator
from typing_extensions import Annotated, Literal

ENABLED_DISABLED = Literal["disabled", "enabled"]

class GlobalSchema(BaseModel):
    location: Annotated[
        ENABLED_DISABLED,
        Field(description="Location: 'enabled' or 'disabled'")
    ] = "disabled"

    @field_validator("location", mode="before")
    def validate_location(cls, value):
        # 若输入为空字符串，主动替换为字段默认值
        if value == "":
            return cls.model_fields["location"].default
        return value  # 其他值交由后续内置校验（Literal 检查）

✅ 效果验证：

# 空字符串 → 自动转为默认值 "disabled"
print(GlobalSchema(location=""))  # location='disabled'

# 合法值 → 正常通过
print(GlobalSchema(location="enabled"))  # location='enabled'

# 非法值 → 抛出清晰错误（保留原始校验逻辑）
try:
    GlobalSchema(location="foo")
except Exception as e:
    print(e)
# 输出包含：Input should be 'disabled' or 'enabled'

⚠️ 几个需要注意的细节：

• 务必使用 `mode="before"`（这是 Pydantic v2 推荐的方式），旧版的 `@validator(..., pre=True)` 写法已被弃用。
• 不要在 `mode="after"` 或普通验证器里尝试修复这个问题——因为到那时，类型校验早已失败，程序根本执行不到那里。
• 通过 `cls.model_fields["location"].default` 来获取字段默认值是一种安全的方法，它兼容 `Field(default=...)` 和直接在类型注解后赋值 `= "disabled"` 这两种声明方式。
• 如果你还需要处理 `None`、纯空白字符串（比如 `" "`）或者其他特殊值，可以在 `before` 验证器中扩展判断逻辑。但需要谨慎，避免过度“宽容”而掩盖了真正的错误输入。

总结来说，Pydantic 的校验流程是分阶段进行的。`mode="before"` 验证器就像是设置在数据流水线上的“第一道闸门”，它给了我们一个机会，在官方校验开始前对原始输入进行预处理。合理利用这个机制，我们就能在保持 Pydantic 强大类型安全性的同时，为字段赋予更灵活、更健壮的容错能力。