Node.js 作为全栈中间层，如何处理 AI 接口的长连接超时和重试逻辑？

在 Node.js 全栈中间层处理 AI 接口的长连接超时和重试，核心思路是分层防御。你需要构建一个从请求发起到流式传输结束的完整容错体系。

🛡️ 第一步：错误分类与处理策略

处理任何错误前，先要判断错误的性质，这决定了后续采取何种策略。

可重试的临时性错误 (Transient Errors)：这类错误通常由网络抖动或服务瞬间过载引起，重试是有效的。
- 网络错误：如 ECONNRESET、ETIMEDOUT、ECONNREFUSED 等。
- 超时错误：客户端请求超时或服务端网关超时 (504)。
- 服务端错误：HTTP 状态码 500、502、503 等。
- 速率限制：HTTP 状态码 429。这是 AI 接口最常见的错误之一。
不可重试的硬性错误 (Hard Errors)：这类错误源于请求本身的问题，重试是徒劳的。
- 参数错误 (400)：如模型名称错误、提示词过长等。
- 认证错误 (401/403)：如 API Key 无效或过期。
- 内容过滤错误：请求触发了 AI 提供商的安全过滤机制。

⏱️ 第二步：超时处理：为长连接设置“双保险”

AI 接口（尤其是推理模型）响应时间可能很长（30秒甚至120秒以上），超时设置不能“一刀切”。

请求级超时 (Request Timeout)：为整个请求设置一个总超时时间，兜底防止请求无限挂起。例如，使用 axios 时配置 timeout: 120000。
连接级超时 (Connection Timeout)：建立 TCP 连接的超时时间，通常设为一个较小的值（如 10秒）。
读取超时 (Read Timeout)：从建立连接到接收到第一个数据包的超时时间。

在 Node.js 中实现超时

使用 Axios：

import axios from 'axios';

const aiClient = axios.create({
  baseURL: 'https://api.openai.com/v1',
  timeout: 120000, // 整个请求120秒超时
  // 更细粒度的超时可以通过 'http(s).Agent' 配置
});

使用原生 fetch + AbortController：这是更现代、更灵活的方式。

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

try {
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    signal: controller.signal,
    // ...
  });
  // ... 处理响应
} catch (error) {
  if (error.name === 'AbortError') {
    console.error('请求超时');
  }
} finally {
  clearTimeout(timeoutId);
}

🔄 第三步：重试逻辑：构建智能的重试机制

重试的核心是指数退避 (Exponential Backoff) 和抖动 (Jitter)，以避免在服务恢复时产生“惊群效应”。

1. 核心重试策略

指数退避：每次重试的等待时间呈指数增长，如 1s, 2s, 4s, 8s。
抖动 (Jitter)：在指数退避的基础上增加随机性，防止大量请求在同一时刻涌入。
尊重 Retry-After 头：当收到 429 错误时，AI 提供商通常会在响应头中携带 Retry-After 字段，明确告知需要等待的时间。

2. 实现方式：从轮子到框架

方案一：使用成熟的库（推荐）
- @munesoft/retryx：专为 API 和 AI 设计的智能重试库，支持 AI 模式（自动处理 429/5xx）、多种退避策略等。
```
import retryx from "@munesoft/retryx";

const data = await retryx(
  () => fetch("https://api.openai.com/v1/chat/completions", { /* ... */ })
    .then(r => r.json()),
  {
    retries: 3,
    ai: true, // 启用AI感知的重试逻辑
  }
);
```
- axios-retry：为 Axios 增加重试能力，可自定义重试条件和延迟。
- resilient-exec：一个轻量级的、确定性的重试工具。

方案二：手写重试逻辑（理解原理）

async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      if (!isRetryable(error)) throw error;

      // 1. 检查 Retry-After 头
      const retryAfter = error.response?.headers?.['retry-after'];
      let delay;
      if (retryAfter) {
        delay = parseInt(retryAfter, 10) * 1000;
      } else {
        // 2. 指数退避 + 抖动
        const baseDelay = Math.pow(2, attempt) * 1000;
        const jitter = baseDelay * 0.2;
        delay = baseDelay + (Math.random() * jitter);
      }

      console.log(`第 ${attempt + 1} 次重试，等待 ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

function isRetryable(error) {
  // 定义可重试的错误类型
  return [429, 500, 502, 503].includes(error.response?.status) ||
         error.code === 'ECONNRESET' ||
         error.code === 'ETIMEDOUT';
}

🌊 第四步：长连接（SSE/WebSocket）的特殊处理

对于流式响应，除了请求本身的超时和重试，还需额外关注连接的健康度。

准确检测客户端断开：在 Express 中，不要依赖 req.closed 或 req.on('close')，它们在长连接场景下可能不可靠。正确做法是监听底层 TCP Socket 的 close 事件。

// 在您的流式路由处理函数中
let isClientDisconnected = false;
req.socket.on('close', () => {
  isClientDisconnected = true;
  console.log('客户端真实断开连接');
  // 可以在这里停止向 AI 的流式请求，以节省资源
});

// 在向客户端推送数据时检查
for await (const chunk of aiStream) {
  if (isClientDisconnected) {
    break; // 客户端已断开，停止推送
  }
  res.write(`data: ${JSON.stringify(chunk)}\n\n`);
}

禁用中间代理缓冲：为确保流式数据实时到达客户端，需设置 X-Accel-Buffering: no 头，防止 Nginx 等反向代理缓存响应。

res.writeHead(200, {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  'Connection': 'keep-alive',
  'X-Accel-Buffering': 'no'
});

实现心跳 (Heartbeat)：对于 WebSocket 或长时间的 SSE 连接，定期发送心跳包（如注释行或 ping 事件）可以防止中间件（如负载均衡器）因超时而主动断开连接。

🏗️ 第五步：进阶韧性模式

对于生产级应用，可以组合使用更高级的模式。

熔断器 (Circuit Breaker)：当对某个 AI 提供商的请求失败率达到阈值时，熔断器会“跳闸”，在短时间内直接返回降级响应，不再发起请求，避免雪崩效应。可使用 opossum 库实现。
故障转移 (Failover)：当主 AI 服务（如 OpenAI）不可用时，自动切换到备用服务（如 Anthropic 或本地模型）。
重试预算 (Retry Budget)：在分布式系统中，限制重试的总次数或比例，防止重试风暴压垮下游服务。

📊 第六步：可观测性与监控

为你的重试和容错逻辑添加日志和监控。

记录关键事件：每次重试、重试成功、重试失败、熔断器状态变化等。
收集指标 (Metrics)：请求成功率、平均响应时间、重试率、熔断器触发次数等，用于告警和容量规划。

💎 总结

处理 Node.js 中间层的 AI 接口问题，关键在于构建一个分层、智能且可观测的容错体系：

分类错误：区分可重试与不可重试错误。
设置超时：为请求设置合理的总超时和阶段超时。
实现重试：采用指数退避+抖动的重试策略，并尊重 Retry-After 头。
处理长连接：监听底层 Socket 准确判断客户端断开，并禁用中间代理缓冲。
组合模式：在重试之上，叠加熔断器、故障转移等模式，构建高弹性的应用。

将这些最佳实践落地，你的 Node.js 中间层就能更稳健地应对 AI 接口的各种不确定性，为用户提供流畅可靠的体验。

🛡️ 第一步：错误分类与处理策略​

⏱️ 第二步：超时处理：为长连接设置“双保险”​

在 Node.js 中实现超时​

🔄 第三步：重试逻辑：构建智能的重试机制​

1. 核心重试策略​

2. 实现方式：从轮子到框架​

🌊 第四步：长连接（SSE/WebSocket）的特殊处理​

🏗️ 第五步：进阶韧性模式​

📊 第六步：可观测性与监控​

💎 总结​