SuperAPI AI 工具集

production-error-handling

部署与运维

查看项目

更新于 10-16 04:26

技能介绍

用途

该技能面向必须在外围组件接连故障时仍保持可用的系统,沉淀经过生产事故验证的错误处理模式。资料指出,这些模式来自真实生产事故:把短暂抖动放大成 4 小时中断的重试风暴、静默吞掉三周数据的裸 except: pass、以及因缺少超时让死掉的服务占满 200 个连接直至连接池枯竭。目标是让这些问题不再发生。

主要能力

1. 错误分类体系

在编写处理代码之前先对每个错误分类,不同错误需要不同响应。资料给出四类:

  • 瞬时(Transient):用退避重试,重试,N 次失败后告警。示例:网络超时、503、连接重置、限流(429)。
  • 永久(Permanent):立即失败,不重试,在异常频率时告警。示例:400、401、404、校验错误、畸形输入。
  • 部分(Partial):优雅降级,可选重试,低优先级告警。示例:缓存未命中、分析服务宕机、邮件服务宕机。
  • 致命(Fatal):快速崩溃,不重试,立即告警(PagerDuty)。示例:缺少配置、状态损坏、OOM、磁盘满。

资料还给出服务的异常层级设计:以 ServiceError 为基类,每个自定义异常继承它,并携带机器可读的 error_code 用于结构化日志和 API 响应。TransientError 是重试逻辑唯一应捕获的基类;捕获 ServiceError 表示“来自我们领域的问题”,而不会混入随机库异常;致命错误应让进程崩溃,不要试图从损坏状态恢复。

2. 带指数退避与抖动的重试

资料解释线性重试会导致惊群效应:服务恢复时所有等待客户端在同一间隔同时冲击它,导致再次宕机。正确公式为:

delay = min(base * 2^attempt + random(0, jitter), max_delay)

其中 base 为起始延迟(0.5s-1s),attempt 为从 0 开始的重试计数,jitter 为随机分量(0 到 base)用于打散客户端,max_delay 为上限(30s-60s)防止荒谬等待。

Python 使用 tenacity,示例展示了 retry_if_exception_type、wait_exponential_jitter、stop_after_attempt、before_sleep_log、after_log 的组合,以及带上下文日志的自定义重试条件。Node.js 使用 p-retry,示例展示 retries、minTimeout、maxTimeout、factor、randomize、onFailedAttempt 配置,并用 AbortError 表示永久错误立即中止。

资料列出不可协商的重试规则:绝不在没有幂等键的情况下重试非幂等请求(重试 POST /charge 可能重复扣款);绝不重试 4xx(429 除外);始终设置 max_retries(通常 3-5);始终设置 max_delay(30s-60s);始终为底层调用设置超时。

3. 熔断器模式

熔断器用于停止调用失败的服务,否则每个请求都会阻塞等待超时。状态机包含:Closed(正常,统计失败)、Open(跳闸,所有调用立即失败并走回退,不触达下游)、Half-Open(恢复超时后放行一个探测请求,成功则关闭,失败则重新打开)。

Python 使用 pybreaker,示例展示 CircuitBreakerListener 记录状态变化与失败,CircuitBreaker 配置 fail_max、reset_timeout、exclude(不把永久错误计入失败)、listeners,以及调用侧捕获 CircuitBreakerError 后走回退(入队稍后处理)。Node.js 使用 opossum,示例展示 timeout、errorThresholdPercentage、resetTimeout、volumeThreshold 配置,open/halfOpen/close 事件监听,以及 fallback 回退。

熔断器规则:为每个外部服务调用使用熔断器(API、数据库、缓存、消息代理);从失败计数中排除永久错误(404 不是服务故障);根据流量设置 fail_max / errorThresholdPercentage(高流量用百分比,低流量用绝对计数);recovery_timeout 应足够下游真正恢复(15s-60s);始终实现回退(返回缓存值、入队稍后处理或返回降级响应);记录每次状态变化,熔断器事件是早期预警系统。

4. 优雅降级

非关键功能不应拖垮关键功能:分析服务宕机时用户仍应能下单,邮件宕机时注册仍应成功。资料给出一个 graceful_degradation 装饰器,捕获非关键操作的失败并返回回退值,同时记录结构化日志,可选发送告警。示例包括:推荐引擎宕机时返回空列表、分析服务宕机时跳过埋点、邮件服务失败时返回 True 继续流程。

使用方式

资料以 Python 与 Node.js 代码示例呈现各模式的实现方式,涉及 tenacity、p-retry、pybreaker、opossum、structlog、httpx 等库。具体安装命令与完整配置步骤暂未提供。

适用场景

适用于需要在高故障环境中保持可用的后端服务,尤其是涉及外部服务调用、支付、用户资料获取、推荐、分析、邮件等依赖的场景。

限制

资料未提供完整的死信队列实现细节(标题提及但正文示例未展开),也未提供安装命令、版本要求或平台限制。部分内容(如 send_we 处)在资料中截断。