接口异常处理不能只靠try-except，因会吞掉网络超时、缺失重试、丢失业务语义、前端提示不友好、关键失败无告警；需分层拦截、策略响应、全链路可观测。

为什么接口异常处理不能只靠 try-except

很多开发者一想到异常处理，就立刻写 try...except Exception as e，然后打印日志、返回错误码。这看似完整，实则埋下隐患：网络超时被吞掉、重试逻辑缺失、业务语义丢失、错误信息对前端不友好、关键失败没告警。接口稳定性不是“不出错”，而是“出错可感知、可恢复、可追溯”。核心在于分层拦截 + 有策略响应 + 全链路可观测。

四类常见异常要分开对待

接口调用中，异常来源不同，应对方式必须差异化：

• 网络层异常（如 requests.ConnectionError、Timeout）：适合自动重试（带退避），但需限制次数和总耗时，避免雪崩。例如第三方支付回调超时，可重试 2 次，间隔 1s/2s；
• 服务端业务异常（如 HTTP 400/401/403/404/422）：应映射为明确的业务错误码（如 2001 表示参数校验失败），附带可读 message 和 error_key，方便前端精准提示；
• 服务端系统异常（如 HTTP 500/502/503）：不建议直接暴露给客户端，统一转为「系统繁忙，请稍后重试」，同时触发告警并记录完整 traceback；
• 本地逻辑异常（如 KeyError、TypeError、JSONDecodeError）：属于代码缺陷，不应被静默捕获，而应在开发/测试阶段暴露；若线上偶发，需记录上下文（请求 ID、入参快照）用于归因。

用装饰器统一收敛异常处理逻辑

避免每个视图函数都重复写 try-catch。推荐用 Flask 或 FastAPI 的依赖/中间件，或自定义装饰器封装通用流程：

例如一个轻量装饰器：
  @api_error_handler
  def create_order(request):
    # 业务代码，专注逻辑，不写 except

其内部完成：分类识别异常 → 设置标准响应结构（code/msg/data）→ 记录结构化日志（含 trace_id）→ 触发分级告警（5xx 上报 Sentry，高频 429 推企业微信）→ 必要时调用降级逻辑（如返回缓存订单列表）。

稳定性不止于“兜底”，还要主动防御

真正高可用的接口，异常处理只是最后一道防线。前置设计更关键：

• 对下游依赖加熔断（如使用 tenacity 或 pybreaker），连续失败 5 次自动熔断 60 秒；
• 关键路径强制设置超时（requests timeout=(3, 7)，协程用 asyncio.wait_for）；
• 输入参数用 Pydantic Model 校验，失败直接返回 422，不进业务逻辑；
• 敏感操作（如支付、删库）增加幂等键（idempotency-key header）和状态机校验，防止重放导致重复扣款。

日志与监控必须带上下文

一句 “Exception occurred” 毫无价值。每次异常记录至少包含：
- 唯一 trace_id（贯穿整个请求生命周期）
- 请求方法 + 路径 + 查询参数（脱敏）
- 响应状态码 + 自定义错误码
- 异常类型 + 精简 message（不含堆栈）
- 堆栈详情单独存入错误分析平台（如 ELK/Sentry）

配合 Prometheus 暴露指标：http_requests_total{status=~"5..", endpoint="/api/pay"}，再配 Grafana 告警——这才是可运维的稳定性。