本文介绍如何在 Pydantic（v2+）中通过 @model_validator(mode="after") 实现跨字段的动态业务规则校验，例如根据 name 限制可选 category，再根据 category 约束 subcategory，适用于 FastAPI 接口参数强校验场景。
本文介绍如何在 pydantic（v2+）中通过 `@model_validator(mode="after")` 实现跨字段的动态业务规则校验，例如根据 `name` 限制可选 `category`，再根据 `category` 约束 `subcategory`，适用于 fastapi 接口参数强校验场景。
在构建高可靠性 API 时，仅靠字段类型和基础约束（如 str, Optional, Field(...)）往往不足以表达复杂的业务逻辑依赖关系。例如：subcategory 是否允许为空、其合法取值范围，可能完全取决于 name 和 category 的组合。Pydantic v2 弃用了旧版 @validator，推荐使用更统一、语义更清晰的 @model_validator(mode="after") 来处理此类跨字段联合校验。
核心思路：声明式规则 + 模型后置校验
我们采用字典结构预定义所有合法的层级关系（name → category → subcategory），并在模型实例化完成后，逐级验证输入是否符合该规则树：
from pydantic import BaseModel, model_validator
from typing import Optional, Dict, List, Any
# 声明业务规则：支持嵌套 None 表示“该层级可省略”
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], # 允许 name="foo" 但 category=None，此时 subcategory 必须为 None
},
"goo": {
None: [None], # name="goo" 时 category 和 subcategory 均必须为 None
},
"bar": {
"bar_a": ["bar_a1"],
"bar_b": [None], # category="bar_b" 时 subcategory 可省略（即 None）
}
}
✅ 优势说明：规则与逻辑分离，易于维护、测试和扩展；支持 None 显式表达“可选/不可用”语义；查表时间复杂度 O(1)，高效可靠。
实现校验逻辑
在 Pydantic 模型中定义字段，并使用 @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 的合法值（含 None）
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()}
✅ 请求 {"name": "foo", "category": "foo_1", "subcategory": "foo_11"} → ✅ 通过
❌ 请求 {"name": "foo", "category": "foo_1", "subcategory": "xxx"} → ❌ 返回 422 错误，含清晰提示
注意事项与最佳实践
- 规则热更新：若规则频繁变动，可将 events_schema 存于数据库或配置中心，启动时加载或按需刷新（注意线程安全）。
- 性能优化：对于超大规模规则集，可考虑构建反向索引（如 category → [name]）或使用 Enum + Literal 配合 Union 提升静态检查能力，但会牺牲灵活性。
- 错误友好性：生产环境建议捕获 ValidationError 并统一格式化为用户友好的业务错误码与消息（如 ERR_INVALID_EVENT_HIERARCHY）。
- 测试覆盖：务必为边界情况编写单元测试，例如 name 不存在、category=None 但 subcategory="x"、空字符串等。
通过 @model_validator(mode="after") 结合声明式规则表，你既能保持代码简洁性，又能精准表达复杂业务约束——这是构建健壮、可维护 API 数据层的关键实践。
