跳到正文
零到全栈 · 卷 5 · 后端与 API

错误处理与日志

本合集目录
本章目录

单册说明:本文件是卷 5 的第 6 章,可独立阅读。前置:5.5(五个端点已跑通)。本章把三种错误形状收成一种,并让每条日志都能追到具体请求。

项 内容
所属卷 卷 5 · 后端与 API(第 6 / 8 章)
前置章节 5.5 FastAPI 路由、校验、文档
本章产出 app/errors.py + 访问日志中间件 + 一套可追溯的错误体
对应代码 backend/app/errors.py、backend/app/main.py(改造)
配图 无(后续统一制图)
读完的判定 能故意造出 422 和 500,并从日志里用 request_id 找到那一次请求

5.6.1 一句话结论:错误要分三层,日志要能回答"哪一次请求"

上一章结束时,你的接口有三种错误形状:

场景 实际返回
字段不合法 {"detail": [{"loc": ["body","title"], "msg": "..."}]}
摘录不存在 {"detail": "摘录不存在"}
代码崩了 一页 HTML(或裸的 Internal Server Error)

前端要为这三种写三套解析。更糟的是第三种:用户截图给你"报错了",你打开日志只看到一堆 traceback,不知道对应哪一次点击。

所以这一章做两件事,而且必须一起做:

错误体统一,前端才只需要一套解析;每条响应带 request_id,日志才能和用户报的错对上。

5.6.2 原理与方法

三层错误,三种归属

层 谁抛的 状态码 谁该改 用户看到什么
校验层 框架(RequestValidationError) 422 调用方 "标题不能为空"这种字段级提示
业务层 你(ApiError) 4xx 看情况:用户改输入,或产品改规则 "这条摘录不存在"
程序层 任何未捕获的异常 500 你 "服务器内部错误" + 一个编号

三层分开的价值在于别把责任搞混。把校验错报成 500,监控会半夜叫你;把程序错报成 400,前端会以为是自己传错了,开始瞎改参数。

FastAPI 里三层各有落点:

层 拦截点
校验层 @app.exception_handler(RequestValidationError)
业务层 @app.exception_handler(ApiError),自己的异常类
程序层 中间件的 except Exception 兜底(下面解释为什么不放在 handler 里)

为什么业务错误要自定义异常

HTTPException 也能用,但它只有一个 detail:

raise HTTPException(status_code=404, detail="摘录不存在")

前端拿到 {"detail": "..."},无法用程序判断"这是没找到还是没权限"。自定义异常多带一个机器码:

raise ApiError(404, "not_found", f"id={note_id} 的摘录不存在")
字段 例子 谁读它
状态码 404 浏览器、日志、监控
code not_found 前端 if (err.code === "not_found")
message id=42 的摘录不存在 人

code 是契约的一部分:可以新增,不能改名。改一次,前端所有分支就静默失效。

本书的错误码表(后续章节只增不改):

code 状态码 什么时候
validation_error 422 字段缺失、类型不对、超长
not_found 404 资源不存在
method_not_allowed 405 方法不对(如对集合发 PUT)
internal_error 500 未捕获异常

为什么 500 用中间件兜,而不是 exception_handler(Exception)

两种写法都能返回统一体,差别在日志:

写法 日志里有什么 问题
@app.exception_handler(Exception) 有 traceback 打不出这次请求的耗时,也拿不到自己生成的 request_id(除非从 request.state 取,但那要求中间件先跑过)
中间件 except Exception traceback + 耗时 + request_id + 方法 + 路径,一行齐 需要自己写

我实测过前一种:一次 500 会在日志里留下三段堆栈(中间件一段、异常处理器一段、ASGI 服务器一段),而且只有一段带 request_id。中间件兜底则是一行摘要 + 一段堆栈,摘要有 id、有耗时。

一句话:错误处理管"返回什么",中间件管"记什么",500 这件事两者都要,所以放一起。

日志该记什么,不该记什么

该记 为什么 不该记 为什么
时间、级别 定位"什么时候开始坏的" 密码、密码哈希 日志会被复制、被转发、被截图
request_id 把前端报错和后端记录连起来 Authorization / Cookie 等于把令牌写进了明文文件
方法 + 路径 知道是哪个端点 完整请求体 摘录正文是用户隐私;体积还可能撑爆磁盘
状态码 区分"客户端错"和"服务端错" 完整响应体 同上,且通常没必要
耗时 发现慢请求、慢查询 用户邮箱等个人信息 合规风险,排障时用 id 就够
异常类型 + 堆栈 修 bug 的唯一线索 数据库连接串 里面带账号密码

判断口诀:这条信息如果出现在别人的截图里,我会不会难受? 会,就别记。

日志级别:四个够用

级别 用在哪 线上要不要留
DEBUG 变量值、分支走向 不留(量太大)
INFO 每次请求一行、启动信息 留
WARNING 可以继续但有隐患(重试成功、降级) 留
ERROR 请求失败且需要人介入(500) 留,并接告警

最常见的错误是"什么都打 INFO":请求体打 INFO、SQL 打 INFO、心跳打 INFO。结果是真出事时你在几万行里捞那一行。级别不是礼貌,是过滤条件。

basicConfig 不生效,与日志写到哪

两个实操问题,几乎每个人都会撞一次:

问题 原因 怎么办
调了 logging.basicConfig 但没有任何输出 root logger 已经有 handler(某个库先配置过),basicConfig 就直接返回,不报错 显式配置:force=True,或者用 dictConfig
日志打出来了,但找不到在哪个文件 默认输出到标准错误,不是文件 启动时重定向:python -m uvicorn app.main:app > app.log 2>&1

2>&1 的意思是"把标准错误也接到标准输出",两个流合到一个文件里。少了它,你会看到 app.log 里只有 uvicorn 的启动信息,自己的日志全跑到终端里去了。

还有一个必须提前想的问题:日志会一直长。 一天几百个请求不算什么,但如果有人拿脚本刷你的接口,一天就能写出几个 GB,磁盘满了服务就挂。本卷只在本地跑,重启终端就清空;卷 7 会上服务器,那里用系统的日志服务(journald)管轮转,不需要你自己写清理脚本。能交给系统做的事,不要写进业务代码。

一条日志的八个字段

2026-11-17 02:25:55 INFO  dudao.api request_id=09940759 POST /api/notes status=201 cost=197.0ms
# 字段 这一行里的值 排障时怎么用
1 时间 2026-11-17 02:25:55 和用户说的"大概两点半"对齐
2 级别 INFO 先筛 ERROR
3 来源 dudao.api 库多了以后区分是谁打的
4 request_id 09940759 用户报的编号直接搜
5 方法 POST 区分读写
6 路径 /api/notes 定位端点
7 状态 201 一眼看出结果类型
8 耗时 197.0ms 找慢请求,横向比较

前三个字段由 logging 的格式串生成,后五个由你在调用时拼进消息。这就是"结构化日志"的雏形:不是非得存成 JSON,而是每个字段的位置固定、含义固定,能被 grep 和脚本解析。卷 7 上服务器后会换成 JSON 格式交给日志系统,字段一个不少。

中间件的位置:为什么它能看到所有请求

@app.middleware("http")
async def access_log(request, call_next):
    ...
    response = await call_next(request)

call_next 把请求交给后面的路由;它返回时,响应已经生成。所以中间件能:

能做 用途
在请求前生成 request_id 并塞进 request.state 后面所有代码都能取到
在响应后读状态码、加响应头 X-Request-Id 给前端
捕获异常 兜住 500 并记录耗时

⚠️ 一个顺序知识:先加的中间件在内层,后加的外层。所以 CORS 中间件(第 7 章)要在访问日志之后加,这样连 500 响应也会带上 CORS 头——否则浏览器只会告诉你"CORS 错误",把真正的 500 藏起来。

5.6.3 动手:两个文件改完,三种错误都能查

app/errors.py

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException


class ApiError(Exception):
    """业务异常:由我们主动抛出,带状态码、机器码、人话。"""

    def __init__(self, status_code: int, code: str, message: str) -> None:
        self.status_code = status_code
        self.code = code
        self.message = message
        super().__init__(message)


def error_body(code: str, message: str, **extra) -> dict:
    body = {"error": {"code": code, "message": message}}
    body["error"].update(extra)
    return body


def install_error_handlers(app: FastAPI) -> None:
    @app.exception_handler(ApiError)
    async def handle_api_error(request: Request, exc: ApiError) -> JSONResponse:
        return JSONResponse(
            status_code=exc.status_code,
            content=error_body(exc.code, exc.message),
        )

    @app.exception_handler(RequestValidationError)
    async def handle_validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
        fields = [
            {
                "field": ".".join(str(part) for part in err["loc"] if part != "body"),
                "message": err["msg"],
            }
            for err in exc.errors()
        ]
        return JSONResponse(
            status_code=422,
            content=error_body("validation_error", "请求数据未通过校验", fields=fields),
        )

    @app.exception_handler(StarletteHTTPException)
    async def handle_http_error(request: Request, exc: StarletteHTTPException) -> JSONResponse:
        code = {404: "not_found", 405: "method_not_allowed"}.get(exc.status_code, "http_error")
        return JSONResponse(
            status_code=exc.status_code,
            content=error_body(code, str(exc.detail)),
            headers=getattr(exc, "headers", None),
        )

三个细节:

写法 为什么
err["loc"] 里过滤掉 "body" loc 形如 ("body","title"),前端只关心 title
兜住 StarletteHTTPException 路径不存在、方法不对是框架抛的,也要统一形状
headers=getattr(exc, "headers", None) 某些 HTTPException 带 Allow、WWW-Authenticate,别吞掉

StarletteHTTPException 这个名字看着别扭:FastAPI 的 HTTPException 继承自 Starlette 的,而框架内部抛的是父类。注册父类才能全兜住。

app/main.py(只列改动部分)

import logging
import time
import uuid

from typing import Annotated

from fastapi import Depends, FastAPI, Request
from fastapi.responses import JSONResponse

from . import store
from .errors import ApiError, error_body, install_error_handlers
from .models import Note, NoteCreate, NoteUpdate

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)-7s %(name)s %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)
logger = logging.getLogger("dudao.api")

app = FastAPI(title="读到 API", version="0.1.0")
install_error_handlers(app)


@app.middleware("http")
async def access_log(request: Request, call_next):
    request_id = uuid.uuid4().hex[:8]
    request.state.request_id = request_id
    started = time.perf_counter()
    try:
        response = await call_next(request)
        cost_ms = (time.perf_counter() - started) * 1000
        logger.info(
            "request_id=%s %s %s status=%s cost=%.1fms",
            request_id, request.method, request.url.path, response.status_code, cost_ms,
        )
    except Exception:
        cost_ms = (time.perf_counter() - started) * 1000
        logger.exception(
            "request_id=%s %s %s status=500 cost=%.1fms",
            request_id, request.method, request.url.path, cost_ms,
        )
        response = JSONResponse(
            status_code=500,
            content=error_body("internal_error", "服务器内部错误,请把 request_id 提供给管理员", request_id=request_id),
        )
    response.headers["X-Request-Id"] = request_id
    return response


def get_note_or_404(note_id: int) -> dict:
    note = store.get_note(note_id)
    if note is None:
        raise ApiError(404, "not_found", f"id={note_id} 的摘录不存在")
    return note


NoteDep = Annotated[dict, Depends(get_note_or_404)]

路由部分只改一处,但这一处出现在三个端点里。改动前后对照:

# 改前(5.5)
def get_note(note: NoteDep) -> dict:
    return note

def get_note_or_404(note_id: int) -> dict:
    note = store.get_note(note_id)
    if note is None:
        raise HTTPException(status_code=404, detail="摘录不存在")
# 改后(本章)
def get_note_or_404(note_id: int) -> dict:
    note = store.get_note(note_id)
    if note is None:
        raise ApiError(404, "not_found", f"id={note_id} 的摘录不存在")

端点的签名与函数体一行都不动——这正是 5.5 把 404 判断收进依赖的回报:改一处,三个端点同时生效。同时把 main.py 顶部那行 from fastapi import HTTPException 删掉(已经用不到了),换成 from .errors import ApiError, error_body, install_error_handlers。

造出三种错误

# 1. 422:字段不合法
curl -s -X POST http://127.0.0.1:8000/api/notes \
  -H "Content-Type: application/json" -d '{"title":"","content":"x"}'

# 2. 404:资源不存在
curl -s http://127.0.0.1:8000/api/notes/42

# 3. 500:把数据文件改坏(手动编辑 data/notes.json,只留一个 "[")
curl -s http://127.0.0.1:8000/api/notes

实测响应:

{"error":{"code":"validation_error","message":"请求数据未通过校验",
 "fields":[{"field":"title","message":"String should have at least 1 character"}]}}
{"error":{"code":"not_found","message":"id=42 的摘录不存在"}}
{"error":{"code":"internal_error","message":"服务器内部错误,请把 request_id 提供给管理员","request_id":"a733c0ab"}}

三种形状完全一致,前端只需要一个解析函数。

现在看日志:

2026-11-17 02:25:55 INFO    dudao.api request_id=09940759 POST /api/notes status=201 cost=197.0ms
2026-11-17 02:25:56 INFO    dudao.api request_id=e1211a70 GET /api/notes/42 status=404 cost=1.8ms
2026-11-17 02:25:56 ERROR   dudao.api request_id=a733c0ab GET /api/notes status=500 cost=1.4ms
Traceback (most recent call last):
  ...
json.decoder.JSONDecodeError: Expecting value: line 2 column 1 (char 2)

把响应体里的 a733c0ab 拿去搜:

grep a733c0ab uvicorn.log

你会拿到那一行摘要和完整堆栈。这就是用户报错 → 你查日志的完整链路。 顺便说一句:日志里还会有一行 uvicorn 自己打的 INFO: 127.0.0.1:60004 - "GET /api/notes/42 HTTP/1.1" 404 Not Found——它是传输层记录,我们的是应用层记录。两套并存是正常的,卷 7 会统一收拾。

最后把 data/notes.json 改回 [],别忘了。

5.6.4 三个坑

坑一:在 exception_handler 里又抛了异常

症状:报错时浏览器拿到的是一屏空白,或者 Internal Server Error,响应体不是你定义的 JSON;日志里出现 RuntimeError: Response content longer than Content-Length 或 No response returned。

成因:处理器本身出错(比如取 request.state.request_id 但中间件还没设、或者序列化了一个不可序列化的对象),异常在"处理异常"的过程中又抛出来,框架只能返回一个空的 500。

修法:处理器里的代码要简单到不可能失败:只做"拼 body + 返回 JSONResponse"。取值一律用 getattr(request.state, "request_id", "-") 兜底;不要在处理器里查数据库、算时间、写文件。兜底代码的复杂度,决定了你出事时能不能看到错误。

坑二:把令牌和正文打进了日志

症状:上线三个月后做安全自查,grep -i "authorization" app.log,出来几千行完整的 Bearer 令牌;或者磁盘一夜涨了 20G。

成因:调试时为了"看清楚",直接 logger.info(request.headers)、logger.info(body),然后忘了删。日志文件的权限通常比数据库宽松得多——它会被打包、被发到群里、被日志服务采集到第三方。

修法:① 只记"字段名和长度",不记值(title_len=42);② 需要排查内容问题时,临时开 DEBUG 并在用完后关掉;③ 在中间件里做一个"敏感头过滤",Authorization、Cookie 一律替换成 ***。判断口诀还是那句:会不会难受?

坑三:没有 request_id,前端报错和后端日志对不上

症状:用户说"下午三点多保存失败",你 grep 了十分钟,找到 8 条 500,不知道是哪一条;或者前端已经重试了三次,你分不清三条日志是同一次点击还是三次。

成因:日志里只有时间、方法、路径。同一分钟内同一个端点可能被调用几十次,时间戳精确到秒也不够。

修法:本章的做法——服务端生成、响应体返回、响应头也带一份(X-Request-Id)。前端在错误提示里显示"错误编号:a733c0ab",用户截图时就带上了。更进阶的做法是让前端生成 id 通过请求头传进来(跨服务追踪时需要),本卷不引入。

本章验收

  • 三种错误(422 / 404 / 500)的响应体形状完全一致
  • 500 的响应里有 request_id,且能在日志里 grep 到对应那一行
  • 日志每行都有时间、级别、request_id、方法、路径、状态、耗时
  • 能说出为什么业务异常要自定义、为什么 code 不能改名
  • 能列出至少三项"绝对不能进日志"的内容

自测

Q1:为什么不让前端直接显示后端返回的 message?

看答案 可以显示,但要分清场景。`message` 是给人看的,适合直接展示("标题不能为空");`code` 是给程序看的,用于分支("not_found" → 显示空状态页)。真正不能做的是"仅凭 message 判断"——文案一改,前端逻辑就崩。另外 500 的 message 是给管理员看的,直接展示给用户没有意义,应该显示"稍后重试"并把 request_id 放在小字里。更严谨的做法是前端按 code 维护自己的文案表,后端 message 只作为开发期的兜底。

Q2:日志里要不要记录完整的请求路径,包括查询串?

看答案 要看查询串,但要小心内容。`?tag=js&page=2` 是有价值的(能看出用户怎么筛的),而 `?token=xxx` 或 `?email=...` 就是泄露。折中方案:记录路径 + 查询串的**键名**,值按白名单决定是否保留;或者只记 `query_keys=tag,page`。本书的中间件用的是 `request.url.path`,不含查询串——这是一个刻意的保守选择:先保证不泄露,等真有需要再按白名单加。

Q3:为什么 500 的响应体里不能放 traceback?明明那样排错最快。

看答案 三个原因。① 泄露内部结构:堆栈里有文件路径、库名与版本、函数名,攻击者据此能挑已知漏洞;如果异常信息里带了 SQL 或连接串,等于直接送出数据库结构。② 对用户无用:他看不懂,也无法据此做任何事,只会更焦虑。③ 会养成坏习惯:一旦"反正线上能看到堆栈",就没人去把日志做对。正确做法是堆栈只进日志、响应里只给 request_id,用这个 id 在日志里换堆栈。FastAPI 的调试模式(debug=True)会返回 traceback,那个开关只能在本机开。

下一步

错误体统一了,日志也能追了。但你在浏览器里 fetch 一次就会发现:请求根本没到你的代码,控制台先红了——那是浏览器的同源策略在拦。下一章专门处理它。

→ 卷5-07-CORS与预检.md