FastAPI全局异常处理是保障系统稳定性的底线，必须注册RequestValidationError、HTTPException和Exception三类处理器，其中依赖注入失败异常需被优先捕获，否则将直接返回500错误。
FastAPI 项目里，全局异常处理不是“锦上添花”，而是避免 500 Internal Server Error 直接暴露 traceback、让前端无法解析错误、线上问题排查困难的底线保障。
为什么不能只靠 HTTPException
HTTPException 是手动抛出的“已知错误”，比如参数缺失、资源未找到。但它完全覆盖不了三类关键场景：
- Pydantic 模型验证失败时自动抛出的
RequestValidationError（对应 HTTP 422），默认响应结构嵌套、字段名（如loc/msg）和团队约定不一致； - 数据库连接中断、第三方 API 超时等引发的底层
Exception，若不拦截，会返回带完整堆栈的 500 响应，存在安全风险； - 依赖注入函数（如
Depends(get_db)）初始化失败时，错误发生在路由进入 controller 之前，HTTPException根本没机会被 raise。
必须注册的三个核心异常处理器
FastAPI 的异常处理是分层注册的，漏掉任意一层都会导致“裸奔”。按优先级顺序，这三类 handler 必须显式定义：
-
@app.exception_handler(RequestValidationError)：接管所有 Pydantic 验证错误，把detail数组转成扁平errors字段，中文提示可在此统一替换； -
@app.exception_handler(HTTPException)：捕获所有主动raise HTTPException(...)的情况，确保status_code和detail被包装进项目约定的响应体（如{"code": 400, "message": "...", "data": null}）； -
@app.exception_handler(Exception)：兜底处理所有未被捕获的异常，**务必记录日志并隐藏敏感信息**，生产环境绝不能返回str(exc)。
app.add_exception_handler 比装饰器更灵活
用 @app.exception_handler 写死在模块里，不利于模块化或插件式扩展。实际项目中推荐用 app.add_exception_handler() 动态注册：
提示词大师-python版
下载
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
立即学习“Python免费学习笔记（深入）”；
- 可以将异常处理器定义在
src/exceptions.py中，再在main.py里统一导入注册，保持入口清晰； - 支持运行时条件注册，比如开发环境保留部分 traceback，生产环境强制过滤；
- 便于单元测试——你可以单独 import handler 函数，传入 mock
Request和exc验证返回结构，无需启动整个 app。
示例注册方式：
from fastapi import FastAPI
from src.exceptions import (
validation_exception_handler,
http_exception_handler,
generic_exception_handler,
)
app = FastAPI()
app.add_exception_handler(RequestValidationError, validation_exception_handler)
app.add_exception_handler(HTTPException, http_exception_handler)
app.add_exception_handler(Exception, generic_exception_handler)
自定义异常类要继承 HTTPException 或 Exception
业务异常（如“余额不足”“订单已取消”）不该直接 raise ValueError("xxx")，否则会被 Exception handler 捕获，丢失状态码语义。正确做法是定义明确的异常类：
- 继承
HTTPException：适用于需强绑定 HTTP 状态码的场景，例如InsufficientBalanceException(status_code=402, detail="余额不足")； - 继承
Exception并自定义属性：更灵活，比如加error_code: int字段，再由全局Exceptionhandler 统一映射到状态码和响应体； - 避免在异常类里做复杂逻辑（如调用 DB 或发 HTTP 请求），handler 才是做日志、告警、降级的地方。
真正容易被忽略的是：**依赖注入失败的异常，永远比 controller 抛出的异常更早触发，必须确保它被上述三类 handler 中的某一个覆盖，否则用户看到的永远是原始 500 页面**。
