本文介绍如何在 FastAPI 业务逻辑层（如数据库校验、跨资源一致性检查等非模型内场景）中，复用 Pydantic 原生的结构化错误格式（含 loc、msg、type 字段），实现多错误聚合与统一 422 响应，避免手动拼接错误或降级为 500 错误。
本文介绍如何在 fastapi 业务逻辑层（如数据库校验、跨资源一致性检查等非模型内场景）中，复用 pydantic 原生的结构化错误格式（含 `loc`、`msg`、`type` 字段），实现多错误聚合与统一 422 响应，避免手动拼接错误或降级为 500 错误。
在使用 FastAPI + Pydantic 构建 API 时，我们习惯于享受 Pydantic 提供的清晰、结构化且可批量返回的验证错误（如 detail: [{ "loc": ["body", "email"], "msg": "...", "type": "..." }]）。然而，当验证逻辑超出模型边界——例如检查用户名是否已存在、关联文档 ID 是否真实存在于数据库、或执行原子性约束（如唯一索引冲突）——这些逻辑不应也不适合放在 Pydantic 的 @field_validator 或 @model_validator 中，原因包括：
- 依赖 I/O（如数据库查询），违背验证器应轻量、无副作用的原则；
- 无法保证事务一致性（先查后插易引发竞态）；
- 实际约束应由数据库层兜底（如 UNIQUE 索引），应用层仅需优雅捕获并反馈。
但若直接在路由或服务函数中 raise ValueError("...") 或自定义异常，则会丢失 Pydantic 的标准化错误结构，导致前端难以解析、用户体验割裂（单次仅报一个错）、状态码错误（默认 500 而非语义明确的 422）。
幸运的是，Pydantic v2 提供了底层工具链，让我们能在模型外部「模拟」其错误生成机制，关键在于 pydantic_core.InitErrorDetails 与 ValidationError.from_exception_data() 的组合使用。
✅ 正确做法：用 InitErrorDetails 构建结构化错误
pydantic_core.InitErrorDetails 是 Pydantic 内部用于描述单个验证失败项的数据类，支持精确指定错误位置（loc）、消息（msg）、类型（type）和上下文（ctx）。配合 ValidationError.from_exception_data()，可将多个 InitErrorDetails 实例聚合成符合 FastAPI 预期的 ValidationError 实例：
# services/user_service.py
from pydantic import ValidationError
from pydantic_core import InitErrorDetails
from sqlalchemy.orm import Session
def create_user(db: Session, user_in: UserCreate) -> User:
errors = []
# 检查邮箱唯一性（数据库层）
if get_user_by_email(db, user_in.email):
errors.append(
InitErrorDetails(
type="value_error",
loc=("email",), # 对应请求体中的字段路径
input=user_in.email,
ctx={"reason": "already_exists"},
msg="Email already registered.",
)
)
# 检查用户名长度（虽可在 Pydantic 模型内做，此处仅为演示多错误聚合）
if len(user_in.username) < 3:
errors.append(
InitErrorDetails(
type="string_too_short",
loc=("username",),
input=user_in.username,
ctx={"min_length": 3},
msg="Username must be at least 3 characters long.",
)
)
# 检查关联文档 ID 是否存在（跨资源校验）
for i, doc_id in enumerate(user_in.related_document_ids or []):
if not document_exists(db, doc_id):
errors.append(
InitErrorDetails(
type="foreign_key_violation",
loc=("related_document_ids", i), # 支持嵌套/数组索引定位
input=doc_id,
msg=f"Related document ID {doc_id} does not exist.",
)
)
# 一次性抛出所有错误（而非逐个 raise）
if errors:
raise ValidationError.from_exception_data(
title="User Creation Validation Error",
line_errors=errors,
)
# ✅ 执行实际创建（此时已确保业务规则通过）
return User.create(db, user_in)? 关键点：loc 元组必须与 OpenAPI 请求体结构对齐（如 ("body", "email") 可简写为 ("email",)，FastAPI 会自动补全 "body" 前缀）；input 字段用于错误上下文还原；ctx 可携带结构化元信息供前端差异化处理。
⚠️ 注意事项与最佳实践
-
状态码修复：直接 raise ValidationError 会导致 FastAPI 返回 500（因未被内置异常处理器识别）。必须显式注册全局异常处理器，将其映射为 422 Unprocessable Entity：
# exceptions.py from fastapi import Request from fastapi.responses import JSONResponse from pydantic import ValidationError def setup_exception_handlers(app): @app.exception_handler(ValidationError) async def validation_exception_handler(request: Request, exc: ValidationError): return JSONResponse( status_code=422, content={"detail": exc.errors()}, # 完全兼容 Pydantic 标准格式 )在主应用初始化时调用 setup_exception_handlers(app) 即可。
不可继承 ValidationError：Pydantic v2 将 ValidationError 标记为 final，因此禁止子类化。务必使用 from_exception_data() 工厂方法构造实例，而非尝试继承重写。
避免与模型内验证重复：将纯数据格式校验（如长度、正则）保留在 Pydantic 模型中；仅将依赖外部状态或 I/O 的业务规则移至服务层，并用上述方式复用错误结构。二者互补，而非替代。
性能提示：InitErrorDetails 是轻量数据类，无运行时开销。聚合错误的代价远低于多次数据库往返或前端反复提交。
✅ 总结
通过 pydantic_core.InitErrorDetails + ValidationError.from_exception_data()，你可以在任意业务代码中精准复现 Pydantic 的错误结构，实现：
✅ 多错误一次性聚合返回（提升用户体验）；
✅ 字段级精确定位（loc 支持嵌套与数组索引）；
✅ 与 FastAPI 原生错误响应完全兼容（422 + detail 数组）；
✅ 零额外依赖，纯 Pydantic 官方支持方案。
这不仅解决了“数据库唯一性校验如何返回标准错误”的痛点，更建立起模型内验证（数据合法性）与模型外验证（业务一致性）之间的统一错误语言，是构建健壮、可维护 API 的关键实践。
