HTTP状态码与异常类须一一对应,如UserNotFoundError→404、InvalidInputError→422;业务逻辑只抛异常,由全局处理器统一转为标准JSON响应并记录日志。

HTTP状态码和异常类要一一对应
RESTful API 的异常响应不是随便抛个 Exception 就完事的。客户端依赖状态码做流程判断,比如 404 触发重试逻辑,422 提示表单校验失败。Python Web 框架(如 Flask、FastAPI)默认把未捕获异常转成 500,这会掩盖真实语义。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 定义明确的异常类,继承自
HTTPException(Flask)或HTTPException/RequestValidationError(FastAPI),每个类绑定唯一状态码,例如UserNotFoundError→404,InvalidInputError→422 - 避免用
try/except Exception:兜底——它会吞掉你本该暴露的类型信息,也拦不住系统级错误(如内存溢出) - 在中间件或全局异常处理器里统一格式化响应体,确保所有异常都返回
{"detail": "xxx"}这类标准结构,而不是混合str、dict或空体
不要在业务逻辑里直接 return 错误响应
常见错误是写成这样:if not user: return jsonify({"error": "not found"}), 404。这会让异常流散落在各处,难以统一日志、监控或添加审计头(如 X-Request-ID)。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 业务函数只负责抛异常,不构造 HTTP 响应。比如 DAO 层查不到用户就 raise
UserNotFoundError("user 123 not found"),路由函数里只写get_user(123),让上层处理 - 框架级异常处理器(如 Flask 的
@app.errorhandler(UserNotFoundError))才负责转成 JSON + 状态码 - 这样能保证所有 404 都走同一套日志模板,也方便后续加 Sentry 上报或自动重试策略
验证失败要用框架原生机制,别手写 if 判断
手动写 if not data.get("email") or "@" not in data["email"]: 再 raise 异常,既重复造轮子,又难统一错误字段名(比如前端期待 email 字段报错,你返回了 data)。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 用 Pydantic 模型(FastAPI 默认)或 Flask-RESTx 的
reqparse做请求体/查询参数校验,它们天然生成符合 OpenAPI 规范的422响应,字段名、错误信息位置都对齐 - 自定义校验逻辑写在 Pydantic 的
@field_validator里,而不是视图函数里,这样能复用且被文档自动收录 - 注意 Pydantic v2 的
ValidationError和 FastAPI 的RequestValidationError是两回事——前者用于模型内部校验,后者是 FastAPI 包装后的顶层异常,全局处理器要同时注册两者
数据库异常必须转换,不能裸露给客户端
像 psycopg2.IntegrityError 或 sqlalchemy.exc.NoResultFound 这类异常,包含数据库驱动细节(如 “duplicate key value violates unique constraint”),直接返回等于泄露服务架构,还可能被用于 SQL 注入探测。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 在 DAO 层或 ORM session commit 后立刻捕获 DB 异常,转成语义清晰的业务异常:比如
IntegrityError→DuplicateResourceError(409),NoResultFound→ResourceNotFoundError(404) - 别忽略
DBAPIError的子类差异——IntegrityError和OperationalError处理方式不同,前者是客户端可修复的(改数据重试),后者可能是连接池枯竭,该触发熔断 - 日志里记录原始 DB 异常(含 SQL、参数),但响应体里只返回泛化消息,例如 “资源已存在” 而非 “违反唯一约束 idx_user_email”
最易被忽略的是异常上下文的传递:比如一个用户创建流程涉及发邮件、写数据库、调第三方 API,某步失败时,要保留原始异常链(用 raise NewError(...) from original_exc),否则排查时根本分不清是网络超时还是序列化失败。


















