API Error Handling

🛡️ 构建高韧性系统的错误处理指南

系统性错误处理设计指南,覆盖多语言模式、熔断降级、HTTP响应规范及可观测性实践,帮助构建高韧性服务架构

收藏
8.1k
安装
2k
版本
1.0.0
CLS 安全性认证2026-07-14
点击查看完整报告 >

使用说明

核心用途

本技能提供跨语言、跨层次的错误处理系统化方法论,核心价值在于:将错误处理从事后补救提升为架构设计要素。涵盖四大维度:

1. 错误分类与哲学

  • 操作错误(网络超时、输入无效):优雅降级处理
  • 程序错误(空指针、类型错误):暴露崩溃,修复代码
  • 六大原则:Fail Fast、Fail Loud、边界处理、Let It Crash、具体捕获、上下文完备

2. 多语言实现模式

| 语言 | 核心机制 | 关键反模式 |
|------|---------|-----------|
| JavaScript | Error子类、`isOperational`标记 | `.catch(()=>{})`静默吞错 |
| Python | 上下文管理器、异常链 | `except:`裸捕获 |
| Go | `error`返回值、`errors.Is/As` | `_ = fn()`忽略错误 |
| Rust | `Result<T,E>`、`?`传播 | `.unwrap()`生产环境滥用 |

3. 弹性模式实现

  • 指数退避+抖动:避免重试风暴,代码可直接复用
  • 熔断器(Circuit Breaker):三态转换防止级联故障
  • 舱壁隔离(Bulkhead):限制单服务故障影响面
  • 优雅降级Promise.allSettled实现部分响应

4. 生产级规范

  • HTTP错误状态码精确使用(400 vs 422 vs 409的区分)
  • 标准错误信封:{error: {code, message, details, requestId}}
  • 结构化日志:JSON格式 + 关联ID传递
  • 8条绝对禁止:静默吞错、暴露堆栈、字符串抛错、缓存5xx等

显著优点

  • 即拿即用:提供可直接落地的代码模板(Express中间件、React Error Boundary、熔断器类)
  • 决策清晰:操作错误 vs 程序错误的二分法简化设计判断
  • 云原生适配:熔断、降级、可观测性与现代微服务架构高度契合

局限性与风险

  • 语言覆盖不全:缺少Java、C#、Kotlin等主流企业级语言的具体模式
  • 框架假设较强:Express/React/Go示例需适配到其他框架
  • 无性能数据:熔断阈值、退避参数缺乏基准测试建议值
  • 分布式链路:未深入涵盖OpenTelemetry、W3C Trace Context等标准

适合人群

  • 设计高可用API的后端工程师
  • 需要统一错误规范的架构师/技术负责人
  • 从单体迁移到微服务、需建立容错体系的团队
  • 技术债务较重、错误处理混乱亟需治理的遗留系统维护者

常规风险

| 风险场景 | 说明 |
|---------|------|
| 过度设计 | 小型项目滥用熔断、舱壁,增加复杂度 |
| 阈值误配 | 熔断阈值过高失去保护,过低导致误杀 |
| 日志风暴 | 高频错误未采样,导致存储成本激增 |
| 安全泄露 | `NODE_ENV=development`误部署生产,暴露堆栈 |

安全解读

核心用法

本 Skill 是一套面向全栈开发者的错误处理设计模式库,聚焦三大核心场景:API 边界错误治理、跨服务容错机制、可观测性体系建设。内容采用「原则 → 分类 → 实现 → 反模式」的递进结构,提供可直接落地的代码范式。

关键能力矩阵:

  • 错误分类治理:区分 Operational(网络超时、输入非法)与 Programmer(空指针、类型错误)两类错误,前者优雅降级,后者快速崩溃
  • 语言特定模式:JavaScript(Error 子类化)、Go(error wrapping)、Rust(Result 类型)等 4 种语言的 idiomatic 实践
  • 弹性基础设施:指数退避 + 抖动重试、熔断器(Circuit Breaker)、舱壁隔离(Bulkhead)的完整实现
  • HTTP 语义化:401/403/422/429 等状态码的精确使用场景,配套标准错误信封(error envelope)格式
  • 可观测性:结构化日志、追踪 ID 透传、错误聚合监控的集成方案

显著优点

1. 生产级完备性:熔断器、退避算法等复杂模式提供可直接复制的类/函数实现,非仅概念描述
2. 多语言覆盖:同一设计原则在 JS/Go/Python/Rust 中的差异化实现,降低团队技术栈迁移成本

3. 反模式清单:8 条「NEVER Do」红线和 8 类 Anti-Patterns 对照表,规避常见工程陷阱

4. 分层边界思维:强调「在边界处处理错误」(Controller/Gateway),避免各层重复捕获导致的上下文丢失

潜在局限

  • 框架耦合示例:Express/Error Boundary 等示例偏向 Node/React 生态,Java/Spring 或 .NET 开发者需自行映射
  • 同步场景偏重:对异步流(RxJS、Kotlin Coroutines、C# async streams)的错误传播模式覆盖不足
  • 缺少压测参数:熔断器阈值(5 次失败)、退避基数(1s)等数值未说明推导依据,需结合服务 SLA 调整

适合人群

  • 设计微服务交互协议的后端架构师
  • 构建 SDK 或内部平台的基础设施工程师
  • 需统一团队错误处理规范的技术负责人
  • 排查线上诡异「静音失败」问题的SRE/运维开发者

常规风险

1. 过度容错陷阱:盲目应用「优雅降级」可能掩盖核心业务失败,需明确「关键路径」与「增强功能」边界
2. 重试风暴:未配抖动的指数退避在故障恢复瞬间可能引发 thundering herd,建议结合断路器状态动态调整

3. 日志敏感信息泄露:示例中的错误信封包含 requestId,若复制到前端需确保不附带 userId 等 PII 字段

API Error Handling 内容

手动下载zip · 6.9 kB
README.mdtext/markdown
请选择文件