FastAPI 密码校验错误未按预期返回的解决方案

在 FastAPI 中使用 Pydantic v2 的 constr(min_length=6) 会导致密码长度校验在请求解析阶段提前触发 422 错误，绕过自定义 @validator 和业务逻辑；正确做法是移除字段级约束，在业务层手动校验并抛出 HTTPException。

这个问题其实挺典型的——不少刚接触 FastAPI + Pydantic v2 的朋友都会踩坑。简单来说，当你用 constr(min_length=6) 给密码字段加上约束时，Pydantic 会在请求体反序列化成模型实例的那一刻，自动捕获校验失败并直接转成 422 状态码的标准错误响应。这意味着你精心写的 @validator 根本不会被执行，更别提里面抛出的 HTTPException 了。结果就是：你期望返回 400 的“密码长度不足”提示，实际却收到一个 422 的 JSON 结构，字段名、错误位置全给你列出来，用户一脸懵。

问题的根源在于：密码长度这类带有业务语义的校验（比如“密码至少6位”），不应该依赖 Pydantic 的声明式约束。Pydantic 的 constr 本质上是一个预解析阶段的约束，它的触发时机比任何自定义校验器都早。一旦它失败，整个模型构建直接中断，后面的逻辑根本轮不到。

✅ 正确做法：把校验放回业务层

先精简数据模型，只保留类型声明，别加任何约束：

from pydantic import BaseModel

class AuthSchema(BaseModel):
    email: str
    password: str  # 移除 constr，交由业务逻辑控制

然后在路由处理函数里手动校验密码长度，并抛出你想要的 HTTP 异常：

from fastapi import HTTPException, status

@router.post("/login", response_model=CustomResponse)
async def login_user(
    user: AuthSchema,
    db: Session = Depends(db.get_session)):
    # ✅ 业务层校验：密码长度
    if len(user.password) < 6:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Password must be at least 6 characters long"
        )
    try:
        if not UserServices().verify_user_password(db, user.email, user.password):
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail="Invalid credentials"
            )
    except Exception as e:
        # 建议避免裸 catch，应捕获具体异常类型
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=str(e)
        )
    # 生成 token 并返回
    token = token_services.create_access_token({
        "id": user.id,  # ⚠️ 注意：此处 user.id 实际未从数据库加载，需修正
        "role": user.role
    })
    return CustomResponse(
        message="User logged in successfully",
        data={"token": token},
        status=200
    )

? 关键说明：

• user.id 和 user.role 在当前的 AuthSchema 中并不存在，实际应从数据库查询用户对象后获取。建议在 verify_user_password 中返回完整用户实体，再用于 token 构造，避免数据不一致风险。
• 若需复用校验逻辑，可将密码校验封装为独立函数（如 validate_password_strength(password: str)），便于单元测试与多处调用。

❌ 为什么 @validator + constr 不生效？

• constr(min_length=6) 是 Pydantic 的预解析约束，触发时机早于 @validator；
• 即使你写了 @validator("password")，只要 constr 已失败，整个模型构建即中断，@validator 不会被调用；
• FastAPI 拦截的是底层 PydanticValidationError，它会格式化为结构化 JSON（含 loc, type, url 等），而非你期望的纯文本 detail。

✅ 进阶建议：统一错误处理与增强可维护性

• 使用 try/except ValueError 包裹密码校验，便于未来扩展其他规则（如大小写字母、数字、特殊字符要求）；
• 考虑引入 pydantic.BaseModel 的 model_validator(mode="before")（v2 新特性）做轻量预处理，但仍不推荐用于需返回 HTTP 异常的场景；
• 对所有客户端可见错误，建议使用枚举类管理 detail 字符串，提升国际化与一致性。

通过将校验逻辑下沉至业务层，你不仅能精确控制错误状态码（400 而非 422）、消息格式与响应结构，还能与认证流程深度耦合，真正实现语义清晰、调试友好、易于演进的 API 设计。