错误处理与日志
本合集目录
本章目录
单册说明:本文件是卷 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 一次就会发现:请求根本没到你的代码,控制台先红了——那是浏览器的同源策略在拦。下一章专门处理它。