FastAPI中HTTPException专用于标准HTTP错误响应，自带status_code和detail；而Exception是兜底异常，需手动注册处理器并隐藏traceback，两者类型优先级不同，不可混用。
FastAPI 中 Exception 和 HTTPException 的处理逻辑差异
FastAPI 默认只捕获 HTTPException 并转为对应状态码响应，其他未捕获的 Python 异常（比如 ValueError、KeyError）会直接 500 报错并暴露 traceback —— 这不是开发或生产环境该有的行为。
全局异常处理器本质是用 app.add_exception_handler() 注册回调函数，但必须分清：处理 HTTPException 是“协议层转发”，而处理 Exception 是“兜底拦截”。两者注册顺序无关，但类型匹配优先级高，所以 HTTPException 处理器不会被泛用的 Exception 处理器覆盖。
- 不要试图只注册一个
Exception处理器来统一处理所有错误 —— 你会丢失status_code和headers等原生信息 -
HTTPException实例自带status_code和detail，适合直接映射成标准响应 - 自定义异常类建议继承
HTTPException，而非裸Exception，否则需手动构造状态码
如何注册带结构化响应的全局 Exception 处理器
生产环境需要隐藏原始 traceback，返回统一 JSON 格式错误体（如 {"code": 500, "message": "Internal server error"}），同时记录日志。注意：不能直接在处理器里 raise 新异常，否则会再次触发处理器导致死循环。
from fastapi import Request
from fastapi.responses import JSONResponse
import logging
logger = logging.getLogger(__name__)
async def global_exception_handler(request: Request, exc: Exception):
logger.exception("Unhandled exception at %s", request.url)
return JSONResponse(
status_code=500,
content={"code": 500, "message": "Internal server error"},
)
app.add_exception_handler(Exception, global_exception_handler)
- 必须用
async def定义处理器，即使内部是同步逻辑 —— FastAPI 调用时按协程执行 -
request: Request参数不可省略，它是获取路径、客户端 IP 等上下文的唯一入口 - 别在处理器里调用
app.logger.error()—— FastAPI 没这个属性，用标准logging模块 - 若需区分开发/生产行为（如开发时返回 traceback），可通过
os.getenv("ENV") == "dev"控制，但切勿在生产响应中暴露exc.__traceback__
为什么 RequestValidationError 需要单独注册
FastAPI 对 Pydantic 请求校验失败默认返回 422，但响应格式是 {"detail": [...]}，和你定义的全局错误结构不一致。它不属于 HTTPException，也不属于裸 Exception，而是 pydantic.ValidationError 的子类，必须显式捕获。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
from fastapi.exceptions import RequestValidationError
from pydantic import ValidationError
async def validation_exception_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=422,
content={"code": 422, "message": "Validation failed", "errors": exc.errors()},
)
app.add_exception_handler(RequestValidationError, validation_exception_handler)
- 别漏掉导入
RequestValidationError—— 它在fastapi.exceptions下，不是pydantic原生模块 -
exc.errors()返回的是 list of dict，包含loc、msg、type字段，可直接透出给前端做字段级提示 - 如果项目用了自定义
BaseModel校验逻辑并抛出ValidationError，需额外注册该异常类型，否则会被兜底Exception处理器吞掉
中间件 vs 异常处理器：什么情况下不该用 add_exception_handler
异常处理器只对路由函数执行过程中抛出的异常生效。如果异常发生在中间件里（比如 JWT 解析失败、CORS 预检失败）、或发生在后台任务（BackgroundTasks）、或发生在依赖注入函数中且未被路由调用链捕获，add_exception_handler 就完全不起作用。
- JWT 认证失败通常应在依赖项（如
Depends(get_current_user)）里抛HTTPException(401)，这样能进异常处理器；若在中间件里raise，则必须在中间件内自己return JSONResponse - 后台任务中发生的异常无法被路由层捕获，应改用
try/except+ 日志 + 可选告警，而不是指望全局处理器 - 数据库连接池耗尽、Redis 超时等底层异常，建议在 DAO 层包装成明确业务异常（如
DatabaseConnectionError），再注册对应处理器，避免所有错误都归为 500
异常处理器不是万能胶，它只管“从 @app.get 开始到响应生成结束”这一段。更外层的生命周期控制，得靠中间件、依赖项设计和基础设施监控来补足。
