4、错误处理核心原则：错误分类、传播模型与重试策略

在构建与 S3 兼容对象存储交互的 NestJS 中间件时，错误处理绝非简单的 try-catch。一个健壮的错误处理体系需要从三个维度进行设计：错误分类（区分错误来源与性质）、错误传播模型（决定错误如何向上传递与转换）、幂等性与重试策略（确保系统在失败后能安全恢复）。本章将逐一剖析这些核心原则，并给出在 NestJS 中间件中的落地实践。

4.1 错误分类：客户端错误、服务端错误与网络错误

错误分类是错误处理的第一步。将错误归入正确的类别，决定了后续的日志记录级别、告警策略以及是否触发重试。在 S3 接口场景下，错误主要分为三大类：

以下是一个在 NestJS 服务层进行错误分类的代码示例：

// s3-error-classifier.service.ts
import { Injectable, Logger } from '@nestjs/common';
import {
  S3Client,
  GetObjectCommand,
  NoSuchKey,
  NoSuchBucket,
  S3ServiceException,
} from '@aws-sdk/client-s3';

@Injectable()
export class S3ErrorClassifierService {
  private readonly logger = new Logger(S3ErrorClassifierService.name);

  async getObject(bucket: string, key: string) {
    try {
      const command = new GetObjectCommand({ Bucket: bucket, Key: key });
      return await this.s3Client.send(command);
    } catch (error) {
      // 1. 客户端错误：不重试，直接返回
      if (error instanceof NoSuchKey || error instanceof NoSuchBucket) {
        this.logger.warn(`客户端错误：资源不存在 - ${error.name}`);
        throw error; // 让过滤器处理为 404
      }

      // 2. 服务端错误：可重试
      if (error instanceof S3ServiceException && error.$retryable === true) {
        this.logger.error(`服务端错误：S3 服务不可用 - ${error.message}`);
        throw error; // 让重试拦截器处理
      }

      // 3. 网络错误：可重试
      if (error.code === 'ECONNRESET' || error.code === 'ETIMEDOUT') {
        this.logger.error(`网络错误：连接中断 - ${error.code}`);
        throw new S3NetworkException(error.message);
      }

      // 4. 未知错误：兜底
      this.logger.error(`未知错误：${error.message}`, error.stack);
      throw new InternalServerErrorException('S3 操作异常');
    }
  }
}

4.2 错误传播模型：从中间件到全局过滤器的链路

错误传播模型定义了错误在 NestJS 请求处理管道中的流动路径。一个清晰的传播模型可以避免错误被多次捕获、日志重复记录或状态码被错误覆盖。在 S3 中间件场景下，推荐采用三层传播模型：

下图展示了错误在 NestJS 各层之间的传播路径：

4.3 幂等性与重试策略

在分布式系统中，网络抖动或服务临时不可靠是常态。重试是提高系统可用性的重要手段，但必须与幂等性结合，否则重试可能导致数据不一致或资源重复创建。

4.3.1 幂等性判断：哪些 S3 操作是幂等的？

幂等性是指无论执行一次还是多次，系统状态都保持一致。在 S3 操作中，不同操作的幂等性不同：

4.3.2 指数退避与抖动（Jitter）

简单的固定间隔重试会导致“惊群效应”（Thundering Herd），即大量客户端在同一时刻发起重试，压垮后端服务。因此，生产环境必须使用指数退避 + 随机抖动策略。

以下是一个在 NestJS 中间件中实现重试策略的代码示例：

// retry.interceptor.ts
import { Injectable, Logger, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, throwError, timer } from 'rxjs';
import { retryWhen, mergeMap, delayWhen } from 'rxjs/operators';

@Injectable()
export class RetryInterceptor implements NestInterceptor {
  private readonly logger = new Logger(RetryInterceptor.name);
  private readonly maxRetries = 3;
  private readonly baseDelay = 1000; // 1 秒

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      retryWhen(errors =>
        errors.pipe(
          mergeMap((error, index) => {
            // 只对服务端错误和网络错误进行重试
            if (this.isRetryable(error) && index < this.maxRetries) {
              const delay = this.calculateDelay(index);
              this.logger.warn(
                `操作失败，第 ${index + 1} 次重试，延迟 ${delay}ms - ${error.message}`
              );
              return timer(delay);
            }
            // 不可重试或达到最大次数，直接抛出
            return throwError(() => error);
          })
        )
      )
    );
  }

  private isRetryable(error: any): boolean {
    // 服务端错误 (5xx) 或网络错误
    return error.status >= 500 || error.code === 'ECONNRESET' || error.code === 'ETIMEDOUT';
  }

  private calculateDelay(attempt: number): number {
    // 指数退避: baseDelay * 2^attempt + 随机抖动 (0 ~ 1000ms)
    const exponentialDelay = this.baseDelay * Math.pow(2, attempt);
    const jitter = Math.random() * 1000;
    return Math.min(exponentialDelay + jitter, 10000); // 最大延迟 10 秒
  }
}

下图展示了指数退避重试策略的流程：

4.4 本章小结

错误处理的核心原则是构建可靠 S3 中间件的基石。通过本章的学习，你应该掌握：

• 错误分类：将错误明确划分为客户端错误（4xx）、服务端错误（5xx）和网络错误，并采取不同的处理策略。
• 错误传播模型：采用服务层 → 中间件层 → 全局过滤器的三层传播模型，确保错误被正确分类、日志被完整记录、响应被统一格式化。
• 幂等性与重试策略：对幂等操作使用指数退避 + 随机抖动的重试策略；对非幂等操作，在重试前必须进行前置条件检查或使用唯一标识符。