（2149期）API Error Handling – 构建高韧性系统的错误处理指南

构建高韧性系统的错误处理指南 系统性错误处理设计指南，覆盖多语言模式、熔断降级、HTTP响应规范及可观测性实践，帮助构建高韧性服务架构 使用说明 核心用途 本技能提供跨语言、跨层次的错误处理系统化方法论，核心价值在于：将错误处理从事后补救提升为架构设计要素。涵盖四大维度： 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误部署生产，暴露堆栈 | 原始说明 Error handling patterns across languages and layers — operational vs programmer errors, retry strategies, circuit breakers, error boundaries, HTTP responses, graceful degradation, and structured logging. Use when designing error strategies, building resilient APIs, or reviewing error management.