Error Handling (错误处理)

🛡️ 核心理念: 错误是程序的一部分，优雅地处理错误比避免错误更重要。

🔴 第一原则：永不崩溃，优雅降级

任何错误都不应该导致整个应用崩溃！

❌ 错误思路: "这个错误不应该发生，直接 throw"
✅ 正确思路: "这个错误可能发生，准备好降级方案"

❌ 错误思路: "用户看到错误信息就知道怎么做了"  
✅ 正确思路: "用户需要明确的指引和可操作的建议"

处理优先级: 预防 > 捕获 > 降级 > 通知用户

When to Use This Skill

使用此技能当你需要：

• 设计错误处理架构
• 实现重试逻辑（指数退避）
• 编写用户友好的错误消息
• 实现优雅降级策略
• 设计结构化日志格式
• 处理 API 调用失败

Not For / Boundaries

此技能不适用于：

• 业务逻辑验证（使用表单验证）
• 类型检查（使用 TypeScript）
• 安全漏洞处理（使用安全审计）

Quick Reference

🎯 错误处理决策流程

错误发生 → 分类识别 → 可恢复? → 重试/降级 → 记录日志
                ↓
            不可恢复 → 友好提示 → 记录日志 → 上报监控

📋 错误处理检查清单

🔍 错误分类体系

✅ 错误处理最佳实践

// ✅ 正确：分层处理，优雅降级
try {
  return await primaryService.fetch();
} catch (error) {
  if (isRetryable(error)) {
    return await withRetry(() => primaryService.fetch());
  }
  if (hasFallback) {
    return await fallbackService.fetch();
  }
  logError(error);
  throw new UserFriendlyError('服务暂时不可用，请稍后重试');
}

// ❌ 错误：直接抛出原始错误
try {
  return await service.fetch();
} catch (error) {
  throw error; // 用户看到 "TypeError: Cannot read property..."
}

🚫 禁止行为

错误处理工作流

Phase 1: 错误捕获

// 1. 使用 try-catch 捕获同步错误
try {
  riskyOperation();
} catch (error) {
  handleError(error);
}

// 2. 使用 .catch() 捕获异步错误
asyncOperation()
  .catch(handleError);

// 3. 使用全局错误处理器
window.addEventListener('unhandledrejection', (event) => {
  handleError(event.reason);
});

Phase 2: 错误分类

function classifyError(error: unknown): ErrorCategory {
  if (error instanceof NetworkError) return 'network';
  if (error instanceof AuthError) return 'auth';
  if (error instanceof ValidationError) return 'validation';
  if (error instanceof RateLimitError) return 'rate_limit';
  if (error instanceof ServerError) return 'server';
  return 'unknown';
}

Phase 3: 错误处理

async function handleError(error: unknown): Promise<void> {
  const category = classifyError(error);
  
  switch (category) {
    case 'network':
      await handleNetworkError(error);
      break;
    case 'auth':
      await handleAuthError(error);
      break;
    case 'rate_limit':
      await handleRateLimitError(error);
      break;
    default:
      await handleUnknownError(error);
  }
}

Phase 4: 用户通知

function notifyUser(error: AppError): void {
  const message = getLocalizedMessage(error);
  const action = getSuggestedAction(error);
  
  toast.error(message, {
    action: action ? {
      label: action.label,
      onClick: action.handler,
    } : undefined,
  });
}

Examples

Example 1: API 调用错误处理

Input: “需要调用外部 API，可能会失败”

Steps:

1. 识别可能的错误类型
2. 实现重试逻辑
3. 准备降级方案
4. 编写用户友好消息

Expected Output:

async function fetchUserData(userId: string): Promise<User> {
  try {
    return await withRetry(
      () => api.users.get(userId),
      {
        maxRetries: 3,
        baseDelay: 1000,
        retryCondition: isRetryableError,
      }
    );
  } catch (error) {
    // 降级：返回缓存数据
    const cached = await cache.get(`user:${userId}`);
    if (cached) {
      logWarning('使用缓存数据', { userId, error });
      return cached;
    }
    
    // 无法降级，抛出用户友好错误
    throw new UserFriendlyError(
      '无法获取用户信息，请检查网络连接后重试',
      { cause: error }
    );
  }
}

Example 2: 表单提交错误处理

Input: “表单提交可能返回验证错误”

Expected Output:

async function submitForm(data: FormData): Promise<Result> {
  try {
    return await api.submit(data);
  } catch (error) {
    if (error instanceof ValidationError) {
      // 显示字段级错误
      return {
        success: false,
        fieldErrors: error.fieldErrors,
      };
    }
    
    if (error instanceof ConflictError) {
      return {
        success: false,
        message: '数据已被修改，请刷新后重试',
      };
    }
    
    // 其他错误
    logError('表单提交失败', error);
    return {
      success: false,
      message: '提交失败，请稍后重试',
    };
  }
}

Example 3: 批量操作错误处理

Input: “批量处理多个项目，部分可能失败”

Expected Output:

async function batchProcess<T>(
  items: T[],
  processor: (item: T) => Promise<void>
): Promise<BatchResult> {
  const results = await Promise.allSettled(
    items.map(item => processor(item))
  );
  
  const succeeded = results.filter(r => r.status === 'fulfilled');
  const failed = results.filter(r => r.status === 'rejected');
  
  if (failed.length > 0) {
    logWarning('批量处理部分失败', {
      total: items.length,
      succeeded: succeeded.length,
      failed: failed.length,
      errors: failed.map(r => (r as PromiseRejectedResult).reason),
    });
  }
  
  return {
    total: items.length,
    succeeded: succeeded.length,
    failed: failed.length,
    message: failed.length > 0
      ? `处理完成，${failed.length} 项失败`
      : '全部处理成功',
  };
}

References

• references/graceful-degradation.md: 优雅降级模式
• references/retry-patterns.md: 重试逻辑模板（指数退避）
• references/message-templates.md: 中文错误消息模板、结构化日志格式

Maintenance

• Sources: 项目最佳实践, 社区经验总结
• Last Updated: 2025-01-01
• Known Limits:
  • 错误分类需根据具体业务调整
  • 重试策略需考虑幂等性