JavaScript异步任务承诺创建器

Promise代码实现

/**
 * 基于 Promise 的“同会话仅执行一次”的用户资料获取任务
 * - GET /api/profile?with=settings，附带 Bearer 令牌
 * - 5000ms 超时，支持 AbortController 取消
 * - 最多重试 3 次（指数退避 + 抖动）
 * - 成功后写入本地（sessionStorage）缓存
 * - 全程进度回传
 * - 任务完成后释放控制器与监听器
 *
 * 使用环境：浏览器（如需 Node.js，请自定义存储与网络可用性检测）
 */

(function () {
  const PROFILE_CACHE_KEY = 'profile:cache:v1';
  const PROFILE_DONE_KEY = 'profile:done:v1';
  const PROFILE_INFLIGHT_KEY = 'profile:inflight:v1'; // 可用于诊断（不参与逻辑判定）

  // 单页面内的并发去重：同一时刻，复用同一个 Promise/控制器
  let sharedInFlight = null;

  /**
   * 启动一次“获取资料”的任务（同会话仅执行一次的保护内置）
   * 返回 { promise, abort }，方便在外部取消。
   *
   * @param {Object} options
   * @param {string} options.token - 必填，Bearer 令牌
   * @param {string} [options.url='/api/profile?with=settings'] - 请求地址
   * @param {number} [options.timeoutMs=5000] - 每次尝试的超时时间（毫秒）
   * @param {number} [options.retries=3] - 最大重试次数
   * @param {(progress: ProgressEventDetail) => void} [options.onProgress] - 进度回调
   * @param {AbortSignal} [options.signal] - 可选，外部传入的取消信号
   * @returns {{ promise: Promise<FetchProfileResult>, abort: () => void }}
   */
  function startProfileFetch({
    token,
    url = '/api/profile?with=settings',
    timeoutMs = 5000,
    retries = 3,
    onProgress,
    signal: externalSignal,
  } = {}) {
    if (!isBrowserEnv()) {
      const error = new Error('This implementation requires a browser environment.');
      error.code = 'ENV_UNSUPPORTED';
      return {
        promise: Promise.reject(error),
        abort() {},
      };
    }

    // 触发条件：网络可用
    if (!isNetworkAvailable()) {
      const err = new Error('Network unavailable');
      err.code = 'NETWORK_UNAVAILABLE';
      return {
        promise: Promise.reject(err),
        abort() {},
      };
    }

    // 触发条件：进入个人中心时调用该函数（由使用方控制）；此处只做“同会话仅执行一次”的保护
    // 如果本会话已经成功执行过，直接返回缓存
    const cached = readCache();
    const sessionDone = sessionStorage.getItem(PROFILE_DONE_KEY) === '1';
    if (sessionDone && cached) {
      const result = {
        data: cached.data,
        fromCache: true,
        attempts: 0,
        durationMs: 0,
        cachedAt: cached.cachedAt,
      };
      onProgressSafe(onProgress, { phase: 'skipped', progress: 100, detail: 'already_done_in_session' });
      return {
        promise: Promise.resolve(result),
        abort() {},
      };
    }

    // 单页面内并发去重：已有在途任务时复用
    if (sharedInFlight) {
      onProgressSafe(onProgress, { phase: 'attached_to_inflight', progress: 0 });
      return {
        promise: sharedInFlight.promise,
        abort: sharedInFlight.abort,
      };
    }

    // 创建主控制器（用于整条任务），支持外部 signal
    const mainController = new AbortController();
    const { signal: mainSignal } = mainController;
    const abort = () => {
      if (!mainSignal.aborted) mainController.abort(new DOMException('Aborted', 'AbortError'));
    };

    // 将外部 signal 与内部 mainController 关联
    let externalAbortCleanup = null;
    if (externalSignal) {
      const onExternalAbort = () => {
        if (!mainSignal.aborted) {
          mainController.abort(externalSignal.reason || new DOMException('Aborted', 'AbortError'));
        }
      };
      externalSignal.addEventListener('abort', onExternalAbort, { once: true });
      externalAbortCleanup = () => externalSignal.removeEventListener('abort', onExternalAbort);
    }

    // 构建在途对象，供并发复用
    const inflight = {};
    sharedInFlight = inflight;

    const startedAt = performance.now();
    sessionStorage.setItem(PROFILE_INFLIGHT_KEY, '1');

    const promise = (async () => {
      onProgressSafe(onProgress, { phase: 'started', progress: 5 });

      // 入参校验
      if (!token || typeof token !== 'string') {
        throw createNonRetryableError('TOKEN_MISSING', 'Bearer token is required.');
      }

      // 如果有缓存且尚未标记 session done，允许进一步请求，但可以先上报已存在本地缓存
      if (cached) {
        onProgressSafe(onProgress, { phase: 'local_cache_present', progress: 10, detail: 'stale_or_preload_cache' });
      }

      // 重试策略
      const maxRetries = Math.max(0, retries | 0);
      const baseDelay = 200; // ms
      let attempt = 0;

      while (true) {
        attempt += 1;
        const attemptLabel = `attempt_${attempt}`;
        onProgressSafe(onProgress, {
          phase: 'request',
          progress: 15,
          attempt,
          totalRetries: maxRetries,
        });

        // 为每次尝试创建独立控制器（用于 per-attempt 超时与取消合并）
        checkAbort(mainSignal); // 主任务是否已取消
        const attemptController = new AbortController();
        const attemptSignal = attemptController.signal;

        // 关联 mainSignal -> attemptSignal
        const unlink = linkAbort(mainSignal, attemptController);

        // 超时定时器（仅终止本次尝试，不会终止主任务）
        const timeoutId = setTimeout(() => {
          if (!attemptSignal.aborted) {
            attemptController.abort(new DOMException('Request timed out', 'TimeoutError'));
          }
        }, timeoutMs);

        try {
          const res = await fetch(url, {
            method: 'GET',
            headers: {
              'Accept': 'application/json',
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${token}`,
            },
            // 为了明确每次都请求最新数据，这里不依赖 HTTP 缓存
            cache: 'no-store',
            signal: attemptSignal,
          });

          onProgressSafe(onProgress, { phase: 'response', progress: 30, attempt, status: res.status });

          // 非 2xx
          if (!res.ok) {
            const err = new Error(`HTTP ${res.status}`);
            err.name = 'HTTPError';
            err.status = res.status;
            // 429/5xx/408 可重试，其它视为不可重试
            if (!isRetryableStatus(res.status)) {
              throw markNonRetryable(err, 'HTTP_NON_RETRYABLE');
            }
            throw err; // 进入重试流程
          }

          // 解析 JSON
          let data;
          try {
            data = await res.json();
          } catch (e) {
            throw markNonRetryable(e, 'JSON_PARSE_ERROR');
          }

          onProgressSafe(onProgress, { phase: 'parse', progress: 50, attempt });

          // 校验必需字段
          validateProfilePayload(data);
          onProgressSafe(onProgress, { phase: 'validate', progress: 70, attempt });

          // 写入本地缓存（同会话缓存）
          const cacheObj = { data, cachedAt: Date.now() };
          writeCache(cacheObj);
          sessionStorage.setItem(PROFILE_DONE_KEY, '1'); // 标记本会话已完成
          onProgressSafe(onProgress, { phase: 'cache', progress: 85 });

          // 成功完成
          const durationMs = Math.round(performance.now() - startedAt);
          onProgressSafe(onProgress, { phase: 'done', progress: 100, durationMs });

          return {
            data,
            fromCache: false,
            attempts: attempt,
            durationMs,
            cachedAt: cacheObj.cachedAt,
          };
        } catch (err) {
          // 归一化错误
          const normalized = normalizeError(err);

          // 若为取消
          if (isAbortError(normalized)) {
            onProgressSafe(onProgress, { phase: 'aborted', progress: 100, reason: normalized.name });
            throw normalized;
          }

          // 超时或可重试错误，进入重试；不可重试则直接抛出
          const canRetry = shouldRetry(normalized);
          const hasMore = attempt < maxRetries;

          if (canRetry && hasMore) {
            const backoff = computeBackoff(baseDelay, attempt);
            onProgressSafe(onProgress, {
              phase: 'retry',
              progress: 25,
              attempt,
              nextDelayMs: backoff,
              error: safeErrorForProgress(normalized),
            });

            // 等待退避时间，同时尊重主任务取消
            await delay(backoff, mainSignal);
            // 下一轮继续
          } else {
            // 无法重试或已达上限
            normalized.code ||= canRetry ? 'RETRY_EXHAUSTED' : normalized.code;
            onProgressSafe(onProgress, {
              phase: 'error',
              progress: 100,
              attempt,
              error: safeErrorForProgress(normalized),
            });
            throw normalized;
          }
        } finally {
          // 清理 per-attempt 资源
          clearTimeout(timeoutId);
          unlink();
        }
      }
    })()
      .finally(() => {
        // 任务最终收尾：释放控制器与监听器、在途标记
        if (externalAbortCleanup) {
          try { externalAbortCleanup(); } catch {}
          externalAbortCleanup = null;
        }
        sharedInFlight = null;
        try { sessionStorage.removeItem(PROFILE_INFLIGHT_KEY); } catch {}
        // 释放主控制器引用（帮助 GC）
        // 注意：不手动调用 abort，这里只是解除引用
      });

    inflight.promise = promise;
    inflight.abort = abort;

    return { promise, abort };
  }

  // ---------- 工具与内部函数 ----------

  function isBrowserEnv() {
    return typeof window !== 'undefined' && typeof document !== 'undefined';
  }

  function isNetworkAvailable() {
    // navigator.onLine 为启发式；如需更精确可在外层做探测
    return typeof navigator === 'undefined' ? true : navigator.onLine !== false;
  }

  function readCache() {
    try {
      const raw = sessionStorage.getItem(PROFILE_CACHE_KEY);
      if (!raw) return null;
      return JSON.parse(raw);
    } catch {
      return null;
    }
  }

  function writeCache(obj) {
    try {
      sessionStorage.setItem(PROFILE_CACHE_KEY, JSON.stringify(obj));
    } catch {
      // 忽略存储失败（配额/隐私模式），不影响主流程
    }
  }

  function onProgressSafe(cb, payload) {
    try {
      if (typeof cb === 'function') cb(payload);
    } catch {
      // 避免进度回调异常影响主流程
    }
  }

  function linkAbort(sourceSignal, targetController) {
    if (!sourceSignal) return () => {};
    const onAbort = () => {
      if (!targetController.signal.aborted) {
        targetController.abort(sourceSignal.reason || new DOMException('Aborted', 'AbortError'));
      }
    };
    sourceSignal.addEventListener('abort', onAbort, { once: true });
    return () => sourceSignal.removeEventListener('abort', onAbort);
  }

  function checkAbort(signal) {
    if (signal && signal.aborted) {
      throw signal.reason || new DOMException('Aborted', 'AbortError');
    }
  }

  function delay(ms, abortSignal) {
    if (ms <= 0) return Promise.resolve();
    return new Promise((resolve, reject) => {
      const id = setTimeout(() => {
        cleanup();
        resolve();
      }, ms);
      const onAbort = () => {
        cleanup();
        reject(abortSignal.reason || new DOMException('Aborted', 'AbortError'));
      };
      const cleanup = () => {
        clearTimeout(id);
        if (abortSignal) abortSignal.removeEventListener('abort', onAbort);
      };
      if (abortSignal) {
        if (abortSignal.aborted) {
          cleanup();
          reject(abortSignal.reason || new DOMException('Aborted', 'AbortError'));
          return;
        }
        abortSignal.addEventListener('abort', onAbort, { once: true });
      }
    });
  }

  function computeBackoff(base, attempt) {
    // 指数退避：base * 2^(attempt-1) + 抖动(0~250ms)，并做上限裁剪
    const jitter = Math.floor(Math.random() * 250);
    const exp = base * Math.pow(2, Math.max(0, attempt - 1));
    const backoff = Math.min(2000, exp) + jitter; // cap at ~2s + jitter
    return backoff;
  }

  function isRetryableStatus(status) {
    return status === 408 || status === 429 || (status >= 500 && status <= 599);
  }

  function isAbortError(err) {
    return err && (err.name === 'AbortError' || err.name === 'TimeoutError');
  }

  function markNonRetryable(err, code) {
    err.code = code || err.code || 'NON_RETRYABLE';
    err.nonRetryable = true;
    return err;
  }

  function normalizeError(err) {
    if (!err) return new Error('Unknown error');
    // 保留 name/message/code/status，避免包含敏感信息（不记录 token）
    return err;
  }

  function safeErrorForProgress(err) {
    return {
      name: err.name,
      message: err.message,
      code: err.code,
      status: err.status,
    };
  }

  function shouldRetry(err) {
    if (!err) return false;
    if (isAbortError(err)) return false;
    if (err.nonRetryable) return false;
    if (err.name === 'HTTPError') {
      return isRetryableStatus(err.status);
    }
    // fetch 网络错误、超时等可重试
    if (err.name === 'TypeError') return true;
    if (err.name === 'TimeoutError') return true;
    return false;
  }

  function createNonRetryableError(code, message) {
    const err = new Error(message);
    err.code = code;
    err.nonRetryable = true;
    return err;
  }

  function validateProfilePayload(obj) {
    // 按需求校验必需字段，可根据实际接口调整
    // 要求：id（string），name（string），settings（object）
    if (!obj || typeof obj !== 'object') {
      throw markNonRetryable(new Error('Invalid payload: not an object'), 'INVALID_PAYLOAD');
    }
    if (typeof obj.id !== 'string' || obj.id.length === 0) {
      throw markNonRetryable(new Error('Missing or invalid "id"'), 'INVALID_ID');
    }
    if (typeof obj.name !== 'string' || obj.name.length === 0) {
      throw markNonRetryable(new Error('Missing or invalid "name"'), 'INVALID_NAME');
    }
    if (typeof obj.settings !== 'object' || obj.settings === null) {
      throw markNonRetryable(new Error('Missing or invalid "settings"'), 'INVALID_SETTINGS');
    }
  }

  // 暴露到全局（按需调整命名/导出方式）
  window.startProfileFetch = startProfileFetch;
})();

/**
 * @typedef {Object} FetchProfileResult
 * @property {any} data - 解析与校验后的资料对象
 * @property {boolean} fromCache - 是否来自本地缓存（sessionStorage）
 * @property {number} attempts - 实际尝试次数
 * @property {number} durationMs - 完整任务耗时（毫秒）
 * @property {number} cachedAt - 缓存写入时间戳（毫秒）
 */

/**
 * @typedef {Object} ProgressEventDetail
 * @property {string} phase - 进度阶段：started/request/response/parse/validate/cache/done/retry/aborted/error/skipped/local_cache_present/attached_to_inflight
 * @property {number} progress - 0~100 的大致进度
 * @property {number} [attempt]
 * @property {number} [totalRetries]
 * @property {number} [status]
 * @property {number} [nextDelayMs]
 * @property {string} [detail]
 * @property {any} [error] - 简化后的错误对象（无敏感信息）
 * @property {number} [durationMs]
 */

代码说明

• 功能描述：

  • 发送携带 Bearer 令牌的 GET /api/profile?with=settings 请求；
  • 单次尝试 5000ms 超时，支持 AbortController 取消；
  • 最多重试 3 次，采用指数退避（含抖动）；
  • 对响应 JSON 进行必需字段校验（id/name/settings）；
  • 成功后将结果写入 sessionStorage 缓存，并在本会话标记为已完成；
  • 同一会话内再次调用会直接返回缓存（不再发起网络请求）；
  • 单页面内并发去重：同一时刻复用同一个在途 Promise；
  • 全流程提供进度回调；
  • 任务结束后释放控制器与事件监听，避免内存泄漏。

• 参数说明：

  • token: 必填，后端认证用的 Bearer 令牌字符串
  • url: 可选，请求地址，默认 /api/profile?with=settings
  • timeoutMs: 可选，每次请求尝试的超时时间，默认 5000ms
  • retries: 可选，最大重试次数，默认 3
  • onProgress: 可选，进度回调函数，接收 ProgressEventDetail 对象
  • signal: 可选，外部 AbortSignal，用于外部取消整个任务

• 返回值：

  • 返回对象 { promise, abort }
    • promise: Promise
      • resolve:
        • data: 经过验证的资料对象
        • fromCache: 是否来自本地缓存
        • attempts: 实际尝试次数
        • durationMs: 总耗时（毫秒）
        • cachedAt: 缓存写入时间戳
      • reject:
        • 取消：name 为 AbortError
        • 超时：name 为 TimeoutError
        • HTTP 非重试错误：name 为 HTTPError，附 status
        • 解析/校验错误：附带 code（如 INVALID_PAYLOAD/INVALID_ID 等）
        • 重试耗尽：code 为 RETRY_EXHAUSTED
    • abort(): 取消整个任务（相当于调用内部的 AbortController.abort）

使用示例

// 假设：用户进入“个人中心”路由时触发
function onEnterProfilePage() {
  const token = getAuthTokenSomehow(); // 由你的应用获取
  if (!token) {
    console.warn('No token; skip profile fetch.');
    return;
  }

  const { promise, abort } = window.startProfileFetch({
    token,
    url: '/api/profile?with=settings',
    timeoutMs: 5000,
    retries: 3,
    onProgress: (p) => {
      // 可用于 UI 显示进度、诊断日志（注意不要打印 token）
      // console.log('[profile progress]', p);
      if (p.phase === 'retry') {
        // 可通知用户正在重试
      }
    },
  });

  promise
    .then((res) => {
      // 使用 profile 数据
      // console.log('profile loaded:', res.data);
      renderProfile(res.data);
    })
    .catch((err) => {
      if (err.name === 'AbortError') {
        // 用户离开页面或主动取消
        // console.log('Profile fetch aborted.');
        return;
      }
      // 其它错误：可提示用户或记录日志
      console.error('Profile fetch failed:', err);
      showToast('加载个人资料失败，请稍后重试');
    });

  // 若用户在数据未到达前离开页面，可取消任务：
  // onRouteLeave(() => abort());
}

// 若同会话内多次进入个人中心，startProfileFetch 会直接返回缓存结果，或复用在途任务

注意事项

• 安全性

  • 不在日志或错误对象中暴露令牌；本实现未输出 token 到控制台。
  • 使用 Authorization: Bearer 头时，确保页面采用 HTTPS。

• 超时与取消

  • 每次网络尝试均有独立的 5000ms 超时，不会影响重试逻辑；
  • 调用 abort() 或外部 signal.abort() 会取消整个任务（包括后续重试）。

• 重试策略

  • 仅对超时、网络错误、状态码 408/429/5xx 进行重试；
  • JSON 解析与字段校验错误、4xx（除 408/429）视为不可重试；
  • 指数退避带随机抖动，最大等待约 2s + 抖动。

• 会话与缓存

  • 仅在成功获取并校验通过后，才会将结果写入 sessionStorage，并标记本会话“已完成”；
  • 本会话内再次调用会直接返回缓存数据，不再访问网络；
  • 如需跨会话持久化，可改为 localStorage，但需考虑过期机制。

• 诊断与调试

  • 通过 onProgress 可观察阶段与重试信息；
  • 若需进一步排查，在 devtools network 面板查看请求详情；
  • 如遇存储异常（隐私模式/配额），不会中断主流程，仅影响缓存。

• 可扩展性

  • 若需要 ETag/If-None-Match 等条件请求，可在 headers 中扩展；
  • 若运行在 Node.js 环境，请将存储读写与网络可用性检测抽象为适配器，并替换 fetch 实现。

• 性能与内存

  • 任务完成后会移除所有监听器并释放控制器引用，避免内存泄漏；
  • 单页面内并发去重避免重复请求，减轻网络开销。