本文介绍在 Pydantic v2 中，如何通过 @field_validator(mode="before") 在验证前统一转小写，再结合 Literal 实现简洁、安全、无需枚举大小写变体的枚举式字符串约束。
本文介绍在 pydantic v2 中，如何通过 `@field_validator(mode="before")` 在验证前统一转小写，再结合 `literal` 实现简洁、安全、无需枚举大小写变体的枚举式字符串约束。
在使用 Pydantic 定义数据模型时，常需对字符串字段施加「仅允许特定取值」的约束（如物种名只能是 "antelope" 或 "zebra"），同时又希望该约束不区分大小写——即 "Antelope"、"ANTELOPE" 和 "antelope" 均应合法。遗憾的是，Pydantic 的 Literal["antelope", "zebra"] 默认严格匹配原始输入，而 ConfigDict(str_to_lower=True) 仅影响后续处理（如序列化或默认行为），不会改变验证顺序，因此无法让 Literal 在小写上下文中生效。
正确的解决路径是：在字段验证开始前，主动将输入字符串标准化为小写。这可通过 @field_validator(..., mode="before") 实现——该装饰器注册的函数会在类型转换和 Literal 校验之前执行，确保传入 Literal 验证器的已是规范化后的值。
以下是一个完整、可运行的示例：
from pydantic import BaseModel, field_validator
from typing import Literal
class Animal(BaseModel):
species: Literal["antelope", "zebra"]
@field_validator("species", mode="before")
def to_lower(cls, value):
if isinstance(value, str):
return value.lower()
return value
# ✅ 全部通过验证
print(Animal(species="antelope")) # species='antelope'
print(Animal(species="AnTeLoPe")) # species='antelope'
print(Animal(species="ZEBRA")) # species='zebra'
# ❌ 抛出 ValidationError
# Animal(species="frog") # ValueError: Input should be 'antelope' or 'zebra'
⚠️ 注意事项：
-
mode="before"是关键：它保证转换发生在Literal校验之前；若使用mode="after"，则校验已失败，转换无效。 - 类型检查需保留：
isinstance(value, str)防止非字符串输入（如数字、None）调用.lower()导致异常。 - 不依赖正则：避免了手动转义特殊字符（如
"user-name"、"C++"）的复杂性与安全隐患。 - 兼容性：此方案适用于 Pydantic v2.x（≥2.0），不适用于 v1（v1 中应使用
@validator+pre=True）。
总结：大小写不敏感的字面量约束并非 Pydantic 内置开箱即用的功能，但通过前置字段验证器标准化输入，即可以极简、健壮、可维护的方式达成目标——既保持 Literal 的类型安全与 IDE 支持，又消除重复枚举大小写变体的冗余与风险。
