api-error-handling

API 错误处理

目录

• 概览
• 适用场景
• 快速开始
• 参考指南
• 最佳实践

概览

构建健壮的错误处理系统，实现标准化错误响应、详细日志记录、错误分类和用户友好的错误消息。本技能涵盖从抛出类型化错误到日志记录、监控和面向客户端的响应格式化的完整生命周期。

适用场景

• 在各个端点统一处理 API 错误
• 通过请求跟踪调试生产环境问题
• 实现错误恢复策略（重试、熔断器）
• 监控错误率并设置告警
• 向客户端提供有意义且可操作的错误消息
• 在处理前验证请求输入
• 跟踪错误模式随时间的变化

快速开始

最简标准化错误响应格式：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "statusCode": 422,
    "requestId": "req_abc123xyz789",
    "timestamp": "2025-01-15T10:30:00Z",
    "details": [
      { "field": "email", "message": "Invalid email format", "code": "INVALID_EMAIL" }
    ]
  }
}

自定义错误类（Node.js）：

class ApiError extends Error {
  constructor(code, message, statusCode = null, details = null) {
    super(message);
    this.code = code;
    this.statusCode = statusCode || ERROR_CODES[code]?.status || 500;
    this.details = details;
    this.timestamp = new Date().toISOString();
  }
}

// Usage
throw new ApiError("NOT_FOUND", "User not found", 404);
throw new ApiError("VALIDATION_ERROR", "Missing fields", 422, fieldErrors);

参考指南

references/ 目录中的详细实现：

指南	内容
错误代码和响应格式	完整的 ERROR_CODES 映射、响应格式化器、全局中间件（Node.js + Python）
重试策略和熔断器	指数退避、抖动、熔断器模式
监控和跟踪	Sentry 集成、错误率指标、/metrics/errors 端点
验证模式	输入验证、架构守卫、在错误发生前检测异常响应

最佳实践

✅ 应该

• 在所有端点使用一致的错误响应格式
• 在每个错误中包含 requestId 和 traceId，以便观测
• 以 ERROR 级别记录 5xx 错误；以 WARN 级别记录 4xx 错误
• 提供可操作的错误消息——告知客户端需要修复什么
• 使用标准 HTTP 状态码（4xx 客户端错误、5xx 服务端错误）
• 对瞬时故障实施指数退避重试
• 使用熔断器防止故障级联
• 尽早验证输入，并一次性返回所有字段错误
• 监控错误率，并对异常飙升发出告警

❌ 不应该

• 向客户端暴露堆栈跟踪或内部实现细节
• 对错误响应返回 HTTP 200
• 悄无声息地吞掉错误
• 记录敏感数据（密码、令牌、个人身份信息）
• 使用“出了点问题”之类含糊的消息
• 将错误处理逻辑与业务逻辑混在一起
• 对非幂等操作或客户端错误（4xx）进行重试
• 让不同端点返回不同格式的错误