在FastAPI应用开发中，Pydantic模型被广泛用于请求参数的校验，当客户端传入的参数不符合模型定义的类型、格式或约束时，Pydantic会自动抛出验证错误，FastAPI默认会返回包含错误详情的JSON响应。但在实际生产场景中，默认的响应格式往往无法满足业务需求，我们需要对这些验证错误进行更优雅的处理。
Pydantic数据验证错误的默认表现
首先我们看一个基础的Pydantic模型定义和接口示例，观察默认的验证错误返回：
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class UserCreateSchema(BaseModel):
username: str = Field(min_length=3, max_length=10, description="用户名长度3-10位")
age: int = Field(gt=0, le=120, description="年龄范围1-120")
@app.post("/users")
def create_user(user: UserCreateSchema):
return {"msg": "用户创建成功", "user": user.dict()}
当我们传入不符合要求的参数，比如username长度为2，age为-1时，默认返回的错误响应如下：
{
"detail": [
{
"loc": ["body", "username"],
"msg": "ensure this value has at least 3 characters",
"type": "value_error.any_str.min_length"
},
{
"loc": ["body", "age"],
"msg": "ensure this value is greater than 0",
"type": "value_error.number.not_gt"
}
]
}
这种默认格式存在几个问题：错误信息是英文的，对前端和用户不友好；错误结构固定，无法和项目自定义的错误响应格式统一；缺少业务层面的错误码定义。
自定义Pydantic验证错误处理器
FastAPI支持自定义异常处理器，我们可以捕获Pydantic抛出的RequestValidationError异常，对其进行处理后返回自定义格式的响应。
步骤1：定义统一错误响应格式
首先定义项目通用的错误响应结构，包含错误码、错误信息和请求路径等字段：
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from pydantic import BaseModel
app = FastAPI()
# 自定义错误响应模型
class ErrorResponse(BaseModel):
code: int
msg: str
data: dict | None = None
步骤2：实现自定义异常处理器
编写处理函数，将Pydantic的验证错误转换为自定义格式：
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
# 提取所有错误详情
error_details = []
for error in exc.errors():
# 错误位置，比如body.username
loc = "->".join([str(item) for item in error["loc"]])
# 错误信息，将默认的英文提示转换为中文
msg = error["msg"]
if "min_length" in error["type"]:
msg = f"{loc} 长度不足最小要求"
elif "not_gt" in error["type"]:
msg = f"{loc} 值必须大于指定阈值"
error_details.append({"loc": loc, "msg": msg})
return JSONResponse(
status_code=400,
content=ErrorResponse(
code=400,
msg="请求参数验证失败",
data={"errors": error_details}
).dict()
)
再次请求之前的/users接口，传入错误参数后返回的结果变为：
{
"code": 400,
"msg": "请求参数验证失败",
"data": {
"errors": [
{"loc": "body->username", "msg": "body->username 长度不足最小要求"},
{"loc": "body->age", "msg": "body->age 值必须大于指定阈值"}
]
}
}
自定义Pydantic验证器实现业务规则校验
除了处理默认的验证错误，我们还可以在Pydantic模型中自定义验证器，实现更复杂的业务规则校验，并抛出自定义的错误信息。
from pydantic import BaseModel, Field, validator
class UserCreateSchema(BaseModel):
username: str = Field(min_length=3, max_length=10, description="用户名长度3-10位")
age: int = Field(gt=0, le=120, description="年龄范围1-120")
password: str = Field(min_length=6, description="密码至少6位")
# 自定义验证器，校验用户名不能包含特殊字符
@validator("username")
def username_no_special_char(cls, v):
if not v.isalnum():
raise ValueError("用户名只能包含字母和数字")
return v
# 自定义验证器，校验密码不能和用户名相同
@validator("password")
def password_not_same_as_username(cls, v, values):
if "username" in values and v == values["username"]:
raise ValueError("密码不能和用户名相同")
return v
当传入的用户名包含特殊字符时，自定义验证器抛出的错误也会被之前的异常处理器捕获，统一转换为自定义的错误响应格式。
全局错误处理的优化建议
- 可以将错误码定义为枚举类型，避免硬编码，方便后续维护
- 敏感信息比如数据库错误信息不要在验证错误中返回，避免信息泄露
- 可以根据不同的业务场景定义不同的错误响应模板，比如参数错误、权限错误等分类处理
- 在开发环境可以保留详细的错误位置信息，生产环境可以简化错误信息，只返回用户友好的提示
总结
通过自定义FastAPI的RequestValidationError异常处理器，结合Pydantic的自定义验证器，我们可以实现Pydantic数据验证错误的优雅处理，让接口的错误响应更规范、更友好，也更符合项目的整体设计要求。这种方式既保留了Pydantic强大的数据校验能力，又可以根据业务需求灵活调整错误返回逻辑，提升整个接口层的可维护性。