应统一用app.add_exception_handler()注册异常处理器，返回JSONResponse显式指定status_code和content，避免状态码丢失；自定义BusinessError类替代HTTPException以支持业务code和扩展字段；兜底Exception处理器生产环境需隐藏堆栈信息。
直接用 app.add_exception_handler() 注册处理器，别写满屏 try/except；统一返回格式必须靠 JSONResponse 显式构造，不能只 return {"code": 400, "message": ...} —— 那会丢状态码、触发默认序列化、破坏 OpenAPI 文档。
HTTPException 默认行为不满足生产需求
FastAPI 对 HTTPException 确实自动转成 JSON，但只返回 {"detail": "xxx"}。这带来三个实际问题：
- 前端要为成功响应和错误响应写两套解析逻辑
- 缺少
code字段，无法做业务错误分类（比如 40001 表示手机号已注册，40002 表示验证码错误） - 没有请求上下文字段（如
x-request-id），线上排查时日志对不上
所以哪怕只处理 HTTPException，也得重写 handler，把 status_code 映射到自定义 code，并补全结构。
必须显式返回 JSONResponse，否则 status_code 会丢失
这是最常踩的坑：在异常处理器里写 return {"code": 400, "message": "xxx"}，看起来能跑，但实际返回是 200 状态码 + 错误体。因为 FastAPI 把 dict 当作正常响应体处理，不继承 status_code。
- 正确写法是
return JSONResponse(status_code=exc.status_code, content=...) -
content必须是 dict，且推荐用 Pydantic 模型.model_dump()生成，避免字段遗漏或类型错误 - 如果用了
response_model声明了 OpenAPI 错误结构，handler 返回的content字段必须与之严格一致，否则文档错位
自定义异常类比 raise HTTPException 更可控
业务层直接 raise HTTPException(status_code=400, detail="xxx") 看似简单，但会导致两个隐性问题：
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 所有 400 错误都混在一起，日志里无法快速区分是参数校验失败还是业务规则拒绝
- 没法附加额外字段，比如
error_code、retry_after、redirect_url
推荐定义继承 Exception 的类，例如：
class BusinessError(Exception):
def __init__(self, code: int, message: str, details: dict | None = None):
self.code = code
self.message = message
self.details = details
然后注册对应 handler：app.add_exception_handler(BusinessError, business_error_handler)。这样 controller 层只需 raise BusinessError(40001, "手机号已存在")，语义清晰，扩展性强。
未捕获异常（Exception）的 handler 要谨慎暴露信息
注册 app.add_exception_handler(Exception, ...) 是兜底必需的，但生产环境绝不能把原始异常堆栈返回给前端。
- 开发环境可加
traceback.format_exc()方便调试 - 生产环境应固定返回
{"code": 500, "message": "Internal server error"}，细节记日志即可 - 注意中间件和 exception handler 的执行顺序：异常先被中间件捕获（如果中间件没吞掉），再传给 handler；所以异常 handler 应该覆盖所有路由逻辑，但不覆盖中间件自身抛出的异常
真正难的是分层——controller 不该感知异常怎么渲染，service 不该知道 HTTP 状态码，而 handler 也不该去调用业务函数。各司其职的边界一旦模糊，后续加监控、改协议、切语言都会变重。
