本文介绍如何在 Pydantic（v2）中通过 @model_validator(mode="after") 实现多字段联动校验，例如根据 name 动态约束 category 取值，再根据 category 进一步约束 subcategory，完美适配 FastAPI 请求验证场景。
本文介绍如何在 pydantic（v2）中通过 `@model_validator(mode="after")` 实现多字段联动校验，例如根据 `name` 动态约束 `category` 取值，再根据 `category` 进一步约束 `subcategory`，完美适配 fastapi 请求验证场景。
在构建强约束 API（如事件分类系统）时，字段之间常存在层级依赖关系：name 决定合法的 category 集合，而 category 又决定其允许的 subcategory 值（甚至允许为空）。Pydantic 原生字段级验证器（如 @field_validator）无法跨字段访问其他字段值，因此必须使用模型级校验器——@model_validator(mode="after")。
以下是一个生产就绪的实现方案，兼顾可读性、可维护性与性能：
✅ 校验逻辑设计：声明式规则表
将业务规则抽象为嵌套字典 events_schema，结构清晰、易于扩展：
from typing import Optional, Dict, List
from pydantic import BaseModel, model_validator
events_schema: Dict[str, Dict[Optional[str], List[Optional[str]]]] = {
"foo": {
"foo_1": ["foo_11", "foo_111"],
"foo_2": ["foo_22", "foo_222"],
None: [None], # 允许 category 为 None → subcategory 必须为 None
},
"goo": {
None: [None], # name="goo" 时，category 和 subcategory 均必须为 None
},
# 可随时追加新事件类型，无需修改校验逻辑
}
? 设计优势：规则与校验逻辑解耦，运维人员可直接维护 JSON/YAML 格式的规则配置，避免硬编码逻辑。
✅ 模型定义与联动校验
使用 @model_validator(mode="after") 在所有字段解析完成后执行交叉验证：
class EventRequest(BaseModel):
name: str
category: Optional[str] = None
subcategory: Optional[str] = None
@model_validator(mode="after")
def verify_event_hierarchy(self) -> "EventRequest":
# Step 1: 校验 name 是否在规则库中
if self.name not in events_schema:
raise ValueError(f"Unsupported event name: '{self.name}'")
name_rules = events_schema[self.name]
# Step 2: 校验 category 是否属于该 name 下的合法值
if self.category not in name_rules:
allowed_categories = list(name_rules.keys())
raise ValueError(
f"Invalid category '{self.category}' for name '{self.name}'. "
f"Allowed: {allowed_categories}"
)
# Step 3: 校验 subcategory 是否属于该 (name, category) 组合下的合法值
allowed_subcategories = name_rules[self.category]
if self.subcategory not in allowed_subcategories:
raise ValueError(
f"Invalid subcategory '{self.subcategory}' for category '{self.category}' "
f"under name '{self.name}'. Allowed: {allowed_subcategories}"
)
return self
✅ FastAPI 中无缝集成
该模型可直接用于 FastAPI 路由参数或请求体，自动触发校验并返回结构化错误：
from fastapi import FastAPI
app = FastAPI()
@app.post("/events/")
def create_event(event: EventRequest):
return {"status": "valid", "data": event.model_dump()}
✅ 正确请求示例：
curl -X POST http://localhost:8000/events/ \
-H "Content-Type: application/json" \
-d '{"name":"foo","category":"foo_1","subcategory":"foo_11"}'
❌ 错误响应（自动返回 422 Unprocessable Entity）：
{
"detail": [
{
"type": "value_error",
"loc": ["body"],
"msg": "Invalid subcategory 'foo_22' for category 'foo_1' under name 'foo'. Allowed: ['foo_11', 'foo_111']",
"input": { ... }
}
]
}
⚠️ 注意事项与最佳实践
- None 的显式处理：规则中明确写入 None 表示“允许该字段为空”，避免 is None 判断遗漏；
- 性能考虑：字典查找为 O(1)，整个校验时间复杂度为常数级，适合高并发场景；
- 类型提示完整性：Optional[str] 与 List[Optional[str]] 确保 IDE 和 mypy 能正确推导类型；
- 扩展建议：如需支持动态加载规则（如从数据库或配置中心），可将 events_schema 改为函数调用或依赖注入；
- Pydantic v1 用户注意：请升级至 v2 并使用 @model_validator；v1 中对应的是 @root_validator(pre=False)，但已弃用。
通过这种声明式 + 模型级校验的组合方式，你既能精准表达复杂的业务约束，又能保持代码简洁、可测试、易维护——这才是现代 Python API 开发中字段依赖校验的推荐范式。
