FastAPI配置response_model返回嵌套JSON报ValidationError排查

你遇到的校验错误核心是response_model配置和实际返回结构不匹配：

pydantic.error_wrappers.ValidationError: 2 validation errors for UserOut
response -> username field required (type=value_error.missing)
response -> email field required (type=value_error.missing)

FastAPI会基于你在装饰器中指定的response_model，对接口return的内容做严格的结构校验：

• 你当前配置的response_model=_models.UserOut，要求返回值顶层直接包含username、pseudo、email三个字段
• 但你接口实际返回的结构顶层是message、data两个字段，用户相关字段全嵌套在data属性下，校验时找不到顶层要求的username、email字段，自然抛出缺失字段的错误。

另外你的模型定义存在冗余：UserIn继承UserOut后，重复声明了username、pseudo、email三个字段，这部分可以直接删除。

1. 定义匹配目标格式的响应模型 #

不要直接用UserOut作为接口的顶层响应模型，新增和你预期返回结构一致的嵌套模型：

from pydantic import BaseModel
from typing import Optional
import re

# 基础用户输出模型，保留原有定义即可
class UserOut(BaseModel):
  username: str
  pseudo: Optional[str] = None
  email: str

# 用户输入模型，继承UserOut后仅需新增password字段和校验方法，无需重复写父类已有的字段
class UserIn(UserOut):
  password: str

  def regex_check_email(self, email):
    match = re.match(email_regex, email)
    return bool(match)

  def regex_check_username(self, username):
    match = re.match(username_regex, username)
    return bool(match)

# 新增统一接口响应模型，和你要返回的结构完全对应
class UserCreateResponse(BaseModel):
  message: str
  data: UserOut

2. 修改接口的response_model配置 #

将接口装饰器的response_model指向新定义的嵌套响应模型，其余逻辑无需改动：

@app.post("/", response_model=_models.UserCreateResponse, status_code=status.HTTP_201_CREATED)
def postUser(userPost: _models.UserIn):
  if not userPost.regex_check_email(userPost.email):
    raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Email: {userPost.email} not valid format")
  if not userPost.regex_check_username(userPost.username):
    raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
                        detail=f"Username: {userPost.username} not valid format")
  db_user.append(userPost)
  return {"message": "OK", "data": userPost}

修改后接口返回的结构会完全匹配你的预期，也不会再抛出校验错误。

FastAPI的response_model核心作用有三个：

• 对返回数据做结构校验，不符合定义的请求直接抛出内部错误
• 自动过滤掉不在模型中定义的字段（比如你如果直接返回带password的UserIn对象，只要response_model里的data是UserOut，password字段会被自动过滤，不会泄露给前端）
• 自动生成符合模型结构的OpenAPI接口文档

如果后续项目中大部分接口都要返回message + data的统一格式，可以基于Pydantic的泛型能力封装通用响应模型，不用为每个接口单独写重复的响应结构。

内容的提问来源于stack exchange，提问作者ELel