push/pull 网络请求无超时和重试机制

[cunoe]

问题描述

src/commands/push.ts 和 src/commands/pull.ts 的 fetch 请求没有设置超时，也没有重试逻辑。

影响

• 网络不好时命令可能永远挂起
• 临时故障无法自动恢复

修复

• 添加 AbortController 超时（如 30s）
• 对 5xx 错误增加指数退避重试（最多 3 次）

[leaperone-bot]

🤖 Leo 自动分析

现在我对代码库有了全面的了解。以下是技术分析：

---

技术分析：Issue #14 — push/pull 网络请求无超时和重试机制

问题确认

Issue 描述准确且清晰。经代码审查确认，以下三处 fetch 调用均无超时和重试机制：

文件	行号	HTTP 方法	说明
src/commands/push.ts	L119-123	POST	推送环境变量到远程
src/commands/pull.ts	L140-143	GET	从远程拉取环境变量
src/utils/env/index.ts	L139	GET	fetchRemoteEnv() 获取远程 .env 文件（Issue 未提及但同样受影响）

影响分析

1. 挂起风险：网络异常（DNS 解析慢、服务端无响应等）时，fetch 会无限期等待，CLI 进程永远不退出
2. 瞬时故障不可恢复：服务端 5xx 错误、网络抖动等临时故障无法自动重试，用户只能手动重新执行
3. 用户体验差：CLI 工具在没有超时的情况下"假死"，用户无法判断是在等待还是出了问题

受影响文件及范围

需要修改的文件：

1. src/utils/fetch.ts（新建）— 封装带超时+重试的 fetch 工具函数
2. src/commands/push.ts — L119-123，替换裸 fetch 调用
3. src/commands/pull.ts — L140-143，替换裸 fetch 调用
4. src/utils/env/index.ts — L139，fetchRemoteEnv() 同样需要改造

建议实现方案

1. 新建 src/utils/fetch.ts 统一封装

// 核心思路
interface FetchWithRetryOptions {
  timeout?: number;        // 默认 30000ms (30s)
  maxRetries?: number;     // 默认 3
  retryableStatusCodes?: number[];  // 默认 [500, 502, 503, 504]
  initialDelay?: number;   // 初始退避延迟，默认 1000ms
  onRetry?: (attempt: number, error: Error) => void;  // 可选的重试回调（用于日志）
}

async function fetchWithRetry(
  url: string, 
  init?: RequestInit, 
  options?: FetchWithRetryOptions
): Promise<Response>

超时实现：使用 AbortController + setTimeout，Node 18+ 原生支持：

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);
try {
  const res = await fetch(url, { ...init, signal: controller.signal });
  return res;
} finally {
  clearTimeout(timeoutId);
}

重试实现：指数退避（exponential backoff）：

• 第 1 次重试：等待 1s
• 第 2 次重试：等待 2s
• 第 3 次重试：等待 4s
• 可添加随机抖动（jitter）避免雷群效应

重试条件：

• HTTP 5xx 状态码（服务端错误）
• 网络错误（fetch 抛出异常，如 TypeError、AbortError 超时）
• 不重试 4xx（客户端错误，如 401/403/404），这些是确定性失败

2. 改造调用点

push.ts 和 pull.ts 中的 MinimalFetch 类型定义和 globalThis.fetch 获取逻辑高度重复，应统一到 fetch.ts 工具模块中。改造后调用方只需：

import { fetchWithRetry } from '@/utils/fetch';

const response = await fetchWithRetry(remoteUrl, {
  method: 'POST',
  headers,
  body: JSON.stringify(payload),
});

3. 用户反馈

结合已有的 ora spinner 和 chalk，在重试时输出提示：

⚠️  Request failed (502), retrying in 2s... (attempt 2/3)

类型兼容性说明

当前代码定义了 MinimalFetch、MinimalResponse、MinimalRequestInit 等自定义类型（见 push.ts L89-102、pull.ts L110-122），用来避免直接引用全局 fetch 类型。新的工具函数需要保持这种兼容方式，或者更好的做法是：由于项目已声明 Node 18+，在 tsconfig.json 中确认 lib 包含 "DOM" 或使用 @types/node（已依赖 @types/node: ^24.3.0），可以直接使用原生 fetch 类型定义，消除重复的 Minimal 类型。

复杂度评估

小到中等 (Small-Medium)

• 核心逻辑（超时+重试封装）约 60-80 行代码
• 改造 3 个调用点，逻辑直观
• 无需引入新依赖，使用 Node 18+ 原生 AbortController
• 需要为工具函数编写单元测试

风险与待确认事项

项目	说明
幂等性	push（POST）的重试需确认服务端 API 幂等，否则可能产生重复数据。需确认 /api/v1/envx/.../push 是否幂等（通常 env push 应该是 upsert 语义）
超时值	30s 是否合适？大规模环境变量 push 可能需要更长时间。建议支持环境变量 ENVX_TIMEOUT 或配置文件覆盖
fetchRemoteEnv	src/utils/env/index.ts 的 fetchRemoteEnv() 也有同样问题，Issue 未提及但应一并修复
AbortController 兼容性	Node 15+ 已支持 AbortController，Node 18+ 完全可用，无兼容问题
测试	需 mock fetch 测试超时和重试逻辑，当前项目未见测试框架配置，可能需要先搭建测试环境

总结

这是一个合理且必要的改进，对 CLI 工具的健壮性有直接提升。建议：

1. 新建 src/utils/fetch.ts 统一封装超时+重试逻辑
2. 同时修复 push.ts、pull.ts 和 fetchRemoteEnv() 三处调用
3. 消除 MinimalFetch 等重复类型定义
4. 确认 push API 的幂等性后再启用 POST 重试
5. 超时时长建议可通过 ENVX_TIMEOUT 环境变量配置