在 pydantic 2 中，`@field_validator` 不再支持 `each_item=true`；若需对 `list[str]` 中每个字符串元素执行预处理（如格式转换），应使用 `beforevalidator` 与 `annotated` 组合，在类型注解层面定义元素级验证逻辑。

在 Pydantic 1 中，@validator(..., each_item=True) 可以便捷地为 List 字段的每个元素调用验证函数。但 Pydantic 2 彻底重构了验证机制：@field_validator 仅作用于整个字段值（即 list 对象本身），不再自动遍历子项。因此，将验证逻辑“下沉”到元素类型层面，是实现逐项处理的标准且推荐做法。

✅ 正确实现方式：使用 BeforeValidator + Annotated

核心思路是：为列表中的每个元素定义带验证的类型别名，再将其用于 List[...] 注解。BeforeValidator 会在每个字符串被解析前单独调用，天然支持“每项独立验证”。

以下是完整、可运行的示例：

复制AI写代码

⚠️ 常见误区与注意事项

• ❌ 错误：在 @field_validator("imports", mode="before") 中直接处理 str
  mode="before" 接收的是整个 list（如 ["a", "b"]），而非单个 str；若函数签名写为 def complement_imports(cls, value: str) -> str:，将导致类型错误或逻辑失效。

• ❌ 错误：将 BeforeValidator 写在 Field(...) 内部（如 Field(default_factory=list, ...)）
  Field 的参数不接受验证器；验证器必须通过 Annotated 在类型注解中声明。

• ✅ 最佳实践：提取验证函数并定义类型别名（如 ImportItem）
  不仅提升可读性与可维护性，还便于在多个字段或模型中复用（例如 exports: List[ImportItem]）。

• ? 补充说明：BeforeValidator 执行时机早于类型转换（如 str → str 本身无转换，但若配合 int 等类型则会先验证后转换），确保业务逻辑前置生效。

总结

Pydantic 2 的验证设计更强调类型即契约：每个数据单元（包括集合中的元素）都应拥有明确、自包含的验证规则。放弃 each_item 并非功能退化，而是推动开发者显式建模数据语义。对于 List[T] 的逐项处理，请始终优先选择 Annotated[T, BeforeValidator(...)] 模式——它精准、安全、符合现代 Pydantic 的哲学，并为未来扩展（如添加 AfterValidator 或 PlainSerializer）预留清晰路径。