别再 HTTP 200 一把梭了：用 RFC 9457 Problem Details 给 FastAPI 错误响应"立规矩"

伩仁2026-09-06 11:59

结论先行：如果你还在用 {code, message, data} 把所有响应包成 HTTP 200，前端、网关、监控其实都在"裸奔"。RFC 9457（原 7807）的 Problem Details 才是正解------真实 HTTP 状态码 + 结构化错误体 + 可扩展业务字段，三件一起给你。本文给一套能在 FastAPI 里直接抄的落地实现，外加我踩过的 5 个坑。

一、背景：你是不是也这样写过接口？

json 复制代码 
// 成功
{ "code": 0, "message": "ok", "data": { "id": 1 } }
// 失败（注意：HTTP 还是 200！）
{ "code": 40400, "message": "用户不存在", "data": null }

这套"统一响应写法"在早年很流行，但它在中大型项目里会慢慢反噬你：

  1. 网关/负载均衡看不懂：Nginx、Kong、云厂商的熔断和限流都是看 HTTP 状态码的，你永远返回 200，它们一律认为"请求成功"，错误流量被当成正常流量。
  2. 监控告警变脆弱 ：想统计"昨天 404 了多少次"，只能去解析 body 里的 code 字段，Prometheus 配起来又臭又长。
  3. 前端每个请求都要写 if (res.code !== 0)：axios 拦截器里一堆硬编码魔法数字，新人接手一脸懵。

我自己的 fastapi-backend 最早就是这套"统一响应写法"，后来整体翻成了 RFC 9457 + 真实状态码 + 类型注解驱动序列化，下面把完整做法摊开讲。

二、核心概念速览（RFC 9457 快查表）

RFC 9457《Problem Details for HTTP APIs》是 RFC 7807 的继承/更新版，核心格式没变，只是把规范做更严谨。它定义了一种错误媒体的标准形态：

  • Content-Type: application/problem+json
  • 标准字段（前 5 个是规范的，后面可自由扩展）
字段 必填 含义
type ✅ 问题类型 URI，如 https://api.xxx/problems/not-found，或 about:blank
title ✅ 人类可读的简短标题（不随请求变化）
status ✅ HTTP 状态码（应和响应状态码一致）
detail 本次请求的具体说明（随请求变化）
instance 出问题的具体资源 URI 或 trace 标识，排查用
trace_id / fields 等 扩展成员：业务自定义，规范允许的

场景 → 错误表达 快查表（直接在团队里当规范用）

业务场景 HTTP 状态 type title
参数校验失败 422 .../problems/validation-error Request Validation Failed
未登录/鉴权失败 401 .../problems/unauthorized Unauthorized
无权限 403 .../problems/forbidden Forbidden
资源不存在 404 .../problems/not-found Resource Not Found
业务冲突（如重复创建） 409 .../problems/conflict Conflict
服务端内部错误 500 .../problems/internal Internal Server Error

关键点 ：业务错误类型用 type 这个 URI 表达，别塞进 HTTP 状态码 （HTTP 状态码就那几十个，塞不下你的业务码）。扩展字段（如 trace_id、fields）才是你放业务细节的地方。

三、完整实现步骤

技术栈：FastAPI + Pydantic v2。下面 6 个文件可直接复制进项目。

1. 响应模型（schemas.py）

python 复制代码 
# schemas.py
from typing import Any, Optional
from pydantic import BaseModel, Field


class ProblemDetail(BaseModel):
    """RFC 9457 Problem Details 响应模型"""
    type: str = Field(default="about:blank", description="问题类型 URI")
    title: str = Field(..., description="简短标题，不随请求变化")
    status: int = Field(..., description="HTTP 状态码，应与响应一致")
    detail: Optional[str] = Field(default=None, description="本次请求的具体说明")
    instance: Optional[str] = Field(default=None, description="出问题的资源 URI 或 trace")
    # ↓↓↓ 扩展成员：业务自定义字段，规范明确允许 ↓↓↓
    trace_id: Optional[str] = None
    fields: Optional[dict[str, Any]] = None

2. 业务异常层（apperr.py）------ 把"错误"变成一等公民

python 复制代码 
# apperr.py
from typing import Optional
from fastapi import status


class AppError(Exception):
    """业务异常基类：自带真实 HTTP 状态码 + RFC9457 字段"""
    def __init__(
        self,
        http_status: int,
        problem_type: str,
        title: str,
        detail: Optional[str] = None,
        instance: Optional[str] = None,
    ):
        self.http_status = http_status
        self.problem_type = problem_type
        self.title = title
        self.detail = detail
        self.instance = instance
        super().__init__(title)


# 常用错误（快查表里的那些，直接复用）
class ValidationError(AppError):
    def __init__(self, detail=None):
        super().__init__(
            status.HTTP_422_UNPROCESSABLE_ENTITY,
            "https://api.example.com/problems/validation-error",
            "Request Validation Failed", detail)


class UnauthorizedError(AppError):
    def __init__(self, detail=None):
        super().__init__(
            status.HTTP_401_UNAUTHORIZED,
            "https://api.example.com/problems/unauthorized",
            "Unauthorized", detail)


class ForbiddenError(AppError):
    def __init__(self, detail=None):
        super().__init__(
            status.HTTP_403_FORBIDDEN,
            "https://api.example.com/problems/forbidden",
            "Forbidden", detail)


class NotFoundError(AppError):
    def __init__(self, detail=None):
        super().__init__(
            status.HTTP_404_NOT_FOUND,
            "https://api.example.com/problems/not-found",
            "Resource Not Found", detail)


class ConflictError(AppError):
    def __init__(self, detail=None):
        super().__init__(
            status.HTTP_409_CONFLICT,
            "https://api.example.com/problems/conflict",
            "Conflict", detail)

3. 全局异常处理器（handlers.py）------ 核心就在这里

python 复制代码 
# handlers.py
import logging
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

from .apperr import AppError
from .schemas import ProblemDetail

logger = logging.getLogger("api")


def _build(err: AppError, request: Request) -> ProblemDetail:
    # 从 request.state 取 trace_id（由下面的 Request-ID 中间件注入）
    trace_id = getattr(request.state, "trace_id", None)
    return ProblemDetail(
        type=err.problem_type,
        title=err.title,
        status=err.http_status,
        detail=err.detail,
        instance=str(request.url),
        trace_id=trace_id,
    )


def register_handlers(app: FastAPI) -> None:
    @app.exception_handler(AppError)
    async def on_app_error(request: Request, exc: AppError):
        problem = _build(exc, request)
        # 关键：状态码用真实的，媒体类型用 problem+json
        return JSONResponse(
            status_code=exc.http_status,
            content=problem.model_dump(exclude_none=True),
            media_type="application/problem+json",
        )

    @app.exception_handler(RequestValidationError)
    async def on_validation_error(request: Request, exc: RequestValidationError):
        problem = ProblemDetail(
            type="https://api.example.com/problems/validation-error",
            title="Request Validation Failed",
            status=422,
            detail="字段校验未通过",
            instance=str(request.url),
            trace_id=getattr(request.state, "trace_id", None),
        )
        return JSONResponse(
            status_code=422,
            content=problem.model_dump(exclude_none=True),
            media_type="application/problem+json",
        )

4. 依赖注入里直接抛错（deps.py）

python 复制代码 
# deps.py
from fastapi import Depends, Header
from .apperr import UnauthorizedError


async def get_current_user(authorization: str = Header(default="")):
    if not authorization.startswith("Bearer "):
        raise UnauthorizedError(detail="缺少或错误的 Authorization 头")
    token = authorization.removeprefix("Bearer ").strip()
    # 这里换成你真实的 token 校验逻辑
    if token != "valid-token":
        raise UnauthorizedError(detail="token 无效或已过期")
    return {"user_id": 1}

5. 路由里直接用（routes.py）

python 复制代码 
# routes.py
from typing import Optional
from fastapi import APIRouter, Depends
from pydantic import BaseModel

from .apperr import NotFoundError, ConflictError
from .deps import get_current_user

router = APIRouter()


class UserOut(BaseModel):
    id: int
    name: str


_FAKE_DB = {1: UserOut(id=1, name="信哥")}


@router.get("/users/{uid}", response_model=UserOut)
async def get_user(uid: int, _: dict = Depends(get_current_user)):
    user = _FAKE_DB.get(uid)
    if user is None:
        # 抛业务异常，由全局 handler 转成 404 + problem+json
        raise NotFoundError(detail=f"用户 {uid} 不存在")
    return user


@router.post("/users/{uid}", response_model=UserOut)
async def create_user(uid: int, _: dict = Depends(get_current_user)):
    if uid in _FAKE_DB:
        raise ConflictError(detail=f"用户 {uid} 已存在，请勿重复创建")
    _FAKE_DB[uid] = UserOut(id=uid, name="新用户")
    return _FAKE_DB[uid]

6. 接入 Request-ID：让 instance / trace_id 真正有用

我踩过最大的坑就是 instance 字段写了等于没写。后来在 fastapi-backend 里加了层 Request-ID 中间件，把 trace 喂给错误体，前端报错时把 trace_id 甩给后端，一查一个准：

python 复制代码 
# middleware.py
import uuid
from starlette.middleware.base import BaseHTTPMiddleware


class RequestIDMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        request.state.trace_id = (
            request.headers.get("X-Request-ID") or f"req-{uuid.uuid4().hex}"
        )
        response = await call_next(request)
        response.headers["X-Request-ID"] = request.state.trace_id
        return response

架构/流程图

flowchart TD A[客户端请求] --> B{路由 / 依赖注入} B --> C[业务逻辑] C -->|正常返回| D[Typed Model<br/>response_model 序列化] C -->|抛出 AppError| E[AppError 处理器] B -->|参数校验失败| F[RequestValidationError 处理器] E --> G[ProblemDetail<br/>真实 HTTP 状态 + application/problem+json] F --> G D --> H[客户端] G --> H style G fill:#ffe0e0,stroke:#c0392b style D fill:#e0f7e0,stroke:#27ae60

四、接口调用效果演示

✅ 成功（正常走 response_model）

bash 复制代码 
curl -s http://localhost:8000/users/1 \
  -H "Authorization: Bearer valid-token"
json 复制代码 
{ "id": 1, "name": "信哥" }

HTTP 200，Content-Type application/json，标准业务模型。

❌ 参数校验失败（422）

bash 复制代码 
# uid 传个字符串触发校验
curl -s http://localhost:8000/users/abc -H "Authorization: Bearer valid-token"
json 复制代码 
{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Request Validation Failed",
  "status": 422,
  "detail": "字段校验未通过",
  "instance": "http://localhost:8000/users/abc",
  "trace_id": "req-3f2a9c1b"
}

HTTP 422，Content-Type application/problem+json。

❌ 业务错误：资源不存在（404）

bash 复制代码 
curl -s http://localhost:8000/users/999 -H "Authorization: Bearer valid-token"
json 复制代码 
{
  "type": "https://api.example.com/problems/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "用户 999 不存在",
  "instance": "http://localhost:8000/users/999",
  "trace_id": "req-7b1d4e8a"
}

❌ 鉴权失败（401）

bash 复制代码 
curl -s http://localhost:8000/users/1   # 不带 Authorization
json 复制代码 
{
  "type": "https://api.example.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "缺少或错误的 Authorization 头"
}

前端现在怎么写？ axios 拦截器里只看 response.status：401 跳登录、403 弹无权限、422 抖表单、500 上报。再也不用满屏 if (res.code !== 0) 了。

五、个人实战踩坑与经验

  1. 坑：HTTP 永远 200 的"伪成功"。网关、负载均衡、APM、云厂商的限流熔断，清一色只看 HTTP 状态码。你永远返回 200，它们一律判"成功"，错误流量被当正常流量放过，限流熔断形同虚设。改真实状态码后，光是"错误流量能进监控大盘"这一项就值回票价。
  2. 坑：response_model 用 dict / Union 导致 OpenAPI 丢结构 。前端联调时 Swagger 里看不到错误体长啥样。正确做法：成功响应用 response_model=UserOut（类型注解驱动序列化），错误统一走 handler，不在路由签名里掺和。
  3. 坑：application/problem+json 老客户端不认 。个别古董 SDK 只认 application/json。折中：保留 problem+json（规范推荐），但若你的调用方很老，降级成 application/json 也完全能工作，字段不变。
  4. 坑：instance 写成空或写死 。排查时毫无用处。务必接 Request-ID 中间件，把 trace_id 同时塞进响应头和错误体，形成闭环。
  5. 经验：用"快查表"统一团队表达。我们内部把上面对照表钉在 Confluence 首页，新人报错先查表再写，杜绝了"张三用 code=1001、李四用 status='ERR_USER'"的混乱。

六、总结

一句话 ：FastAPI 错误处理别再 200 一把梭------用 AppError 携带真实 HTTP 状态码，全局 handler 统一渲染成 RFC 9457 的 ProblemDetail，成功响应交给 response_model 类型注解驱动。网关、监控、前端三方都省心，新人也能照着快查表写。

完整代码已按模块拆分，复制即跑。下一篇可以聊聊怎么给这套错误体接 Sentry + 结构化日志，感兴趣的评论区扣 1。

相关推荐
吃饱了得干活1 小时前
Redis 不是死脑筋，它是一套“会进化”的存储系统
redis·后端
MeetTanG1 小时前
Go 实战锦囊｜errgroup：优雅地管理并发任务组
后端·go
PragmaticWorks1 小时前
DDD 学了很多却用不上？因为你把“责任”和“时机”揉在了一起
后端·领域驱动设计
凯哥Java1 小时前
System.setProperty 的正确姿势：Spring Boot 启动类里的“缺省值“魔法
java·spring boot·后端
柯克七七1 小时前
Vue刷新页面数据重置？一招解决Vuex状态丢失
后端
楚兴1 小时前
ACP 到底解决了什么？让 IDE 和 Coding Agent 解耦
人工智能·后端·架构
楚兴1 小时前
DeepSeek Harness 到底在做什么？拆开 Agent 的运行时
人工智能·后端·架构
名字还没想好☜2 小时前
Go 标准库 flag 包实战:参数解析、子命令、自定义 Value 类型与默认值
开发语言·后端·golang·go
米花米唐2 小时前
Spring AI 2.0 MCP服务器搭建与使用
后端
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02ZCode 周末送额度活动开启：3 亿 Token 免费领取03GitHub 镜像站点04蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接05历年考研数学一、数学二、数学三真题试卷及答案PDF062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费10VSCode+CodeX扩展，无法启动