弹性连接

构建具备容错能力的 API 客户端与实时连接，通过重试机制、熔断器和降级策略优雅地应对故障。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install resilient-connections

适用场景

• 需要处理瞬时故障的 API 客户端
• 应支持自动重连的实时连接
• 需要实现优雅降级的系统
• 任何调用外部服务的生产系统

模式 1：指数退避重试（Exponential Backoff）

interface RetryOptions {
  maxRetries: number;
  baseDelay: number;
  maxDelay: number;
  jitter?: boolean;
}

async function withRetry(
  fn: () => Promise,
  options: RetryOptions
): Promise {
  const { maxRetries, baseDelay, maxDelay, jitter = true } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      // 使用指数退避计算延迟
      let delay = Math.min(baseDelay * 2 ** attempt, maxDelay);
      
      // 添加抖动（jitter），避免“惊群效应”（thundering herd）
      if (jitter) {
        delay = delay * (0.5 + Math.random());
      }

      await sleep(delay);
    }
  }

  throw new Error('Unreachable');
}

// 使用示例
const data = await withRetry(
  () => fetch('/api/data').then(r => r.json()),
  { maxRetries: 3, baseDelay: 1000, maxDelay: 30000 }
);

模式 2：熔断器（Circuit Breaker）

enum CircuitState {
  Closed,    // 正常运行状态
  Open,      // 故障中，拒绝请求
  HalfOpen,  // 尝试恢复，试探性放行请求
}

class CircuitBreaker {
  private state = CircuitState.Closed;
  private failures = 0;
  private lastFailure = 0;
  
  constructor(
    private threshold: number = 5,
    private timeout: number = 30000
  ) {}

  async execute(fn: () => Promise): Promise {
    if (this.state === CircuitState.Open) {
      if (Date.now() - this.lastFailure > this.timeout) {
        this.state = CircuitState.HalfOpen;
      } else {
        throw new Error('Circuit breaker is open');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = CircuitState.Closed;
  }

  private onFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    
    if (this.failures >= this.threshold) {
      this.state = CircuitState.Open;
    }
  }
}

模式 3：弹性 Fetch 封装器

interface FetchOptions extends RequestInit {
  timeout?: number;
  retries?: number;
}

async function resilientFetch(
  url: string,
  options: FetchOptions = {}
): Promise {
  const { timeout = 10000, retries = 3, ...fetchOptions } = options;

  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  const fetchWithTimeout = async () => {
    try {
      const response = await fetch(url, {
        ...fetchOptions,
        signal: controller.signal,
      });

      if (!response.ok && response.status >= 500) {
        throw new Error(`Server error: ${response.status}`);
      }

      return response;
    } finally {
      clearTimeout(timeoutId);
    }
  };

  return withRetry(fetchWithTimeout, {
    maxRetries: retries,
    baseDelay: 1000,
    maxDelay: 10000,
  });
}

模式 4：自动重连 WebSocket

class ReconnectingWebSocket {
  private ws: WebSocket | null = null;
  private retries = 0;
  private maxRetries = 10;

  constructor(
    private url: string,
    private onMessage: (data: unknown) => void
  ) {
    this.connect();
  }

  private connect() {
    this.ws = new WebSocket(this.url);

    this.ws.onopen = () => {
      this.retries = 0;
    };

    this.ws.onmessage = (event) => {
      this.onMessage(JSON.parse(event.data));
    };

    this.ws.onclose = () => {
      if (this.retries < this.maxRetries) {
        const delay = Math.min(1000 * 2 ** this.retries, 30000);
        this.retries++;
        setTimeout(() => this.connect(), delay);
      }
    };
  }

  send(data: unknown) {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(data));
    }
  }

  close() {
    this.maxRetries = 0; // 阻止后续重连
    this.ws?.close();
  }
}

模式 5：优雅降级（Graceful Degradation）

async function fetchWithFallback(
  primary: () => Promise,
  fallback: () => Promise,
  cache?: T
): Promise {
  try {
    return await primary();
  } catch (primaryError) {
    console.warn('Primary failed, trying fallback:', primaryError);
    
    try {
      return await fallback();
    } catch (fallbackError) {
      console.warn('Fallback failed:', fallbackError);
      
      if (cache !== undefined) {
        console.warn('Using cached data');
        return cache;
      }
      
      throw fallbackError;
    }
  }
}

// 使用示例
const data = await fetchWithFallback(
  () => fetchFromPrimaryAPI(),
  () => fetchFromBackupAPI(),
  cachedData
);

相关技能

• 元技能（Meta-skill）： ai/skills/meta/realtime-dashboard/ —— 完整的实时仪表盘指南
• realtime-react-hooks —— React Hook 的使用方式
• websocket-hub-patterns —— 服务端模式

绝对禁止事项（NEVER Do）

• 切勿重试非幂等请求 —— POST/PUT 请求可能已成功执行但未返回响应
• 切勿使用固定延迟 —— 必须添加抖动（jitter）以避免“惊群效应”
• 切勿重试 4xx 错误 —— 客户端错误不会自行恢复
• 切勿让熔断器永远保持开启状态 —— 必须设置超时，使其能进入半开（HalfOpen）状态进行探测
• 切勿隐藏连接失败 —— 应向用户明确展示服务降级状态

速查参考

// 指数退避延迟计算
const delay = Math.min(baseDelay * 2 ** attempt, maxDelay);

// 加入抖动后的延迟
const jitteredDelay = delay * (0.5 + Math.random());

// 是否应重试的判断逻辑
const shouldRetry = 
  error.status >= 500 || 
  error.code === 'ETIMEDOUT' ||
  error.code === 'ECONNRESET';

// 熔断器状态转换
Closed -> (failures >= threshold) -> Open
Open -> (timeout elapsed) -> HalfOpen
HalfOpen -> (success) -> Closed
HalfOpen -> (failure) -> Open