JavaScript Promise.withResolvers 如何拆分异步控制器：旧写法迁移与异常收口

做一个“等外部事件再继续”的前端流程时，Promise 的构造器写法经常把 resolve 和 reject 藏在执行器函数里。Promise.withResolvers() 把这三个对象直接返回，适合把事件回调、超时和取消逻辑拆开管理，但它不会替你处理重复结算或异常边界。

迁移的核心不是把构造器换成一个更短的 API，而是让 promise、resolve、reject 在同一控制器里明确协作，并保证外部事件只结算一次。

为什么外部事件会把 Promise 构造器写得别扭

例如弹窗要等用户点击“确认”才能继续，事件监听器和创建 Promise 的代码往往不在同一个函数里。旧写法需要先声明两个变量，再在构造器执行器里赋值：

function waitForConfirm() {
  let resolveConfirm;
  let rejectConfirm;

  const promise = new Promise((resolve, reject) => {
    resolveConfirm = resolve;
    rejectConfirm = reject;
  });

  confirmButton.addEventListener('click', () => resolveConfirm(true), { once: true });
  cancelButton.addEventListener('click', () => rejectConfirm(new Error('cancelled')), { once: true });
  return promise;
}

这段代码能工作，但控制器状态分散在局部变量和事件监听器之间。后续加入超时后，三个出口都可能触发，清理和重复结算就容易被遗漏。

Promise.withResolvers 返回的三个成员各自负责什么

新写法直接拿到 promise、resolve、reject：

function waitForConfirm() {
  const { promise, resolve, reject } = Promise.withResolvers();

  confirmButton.addEventListener('click', () => resolve(true), { once: true });
  cancelButton.addEventListener('click', () => reject(new Error('cancelled')), { once: true });
  return promise;
}

语义没有改变：resolve 让 Promise 进入完成路径，reject 让它进入失败路径，promise 仍然通过 then、catch 或 await 被消费。变化只在于它们的作用域更清楚，事件回调不必依赖构造器内部的赋值时机。

迁移时先补上一次性结算和清理

真实页面通常还有超时出口。与其让每个出口直接调用 resolve 或 reject，不如让控制器统一做结算和清理：

function waitForConfirm(timeout = 5000) {
  const { promise, resolve, reject } = Promise.withResolvers();
  let settled = false;

  const finish = (callback, value) => {
    if (settled) return;
    settled = true;
    clearTimeout(timer);
    confirmButton.removeEventListener('click', onConfirm);
    cancelButton.removeEventListener('click', onCancel);
    callback(value);
  };

  const onConfirm = () => finish(resolve, true);
  const onCancel = () => finish(reject, new Error('cancelled'));
  const timer = setTimeout(() => finish(reject, new Error('timeout')), timeout);
  confirmButton.addEventListener('click', onConfirm);
  cancelButton.addEventListener('click', onCancel);
  return promise;
}

这里的关键不是 settled 变量本身，而是所有出口都经过 finish。确认、取消和超时共享同一条收口路径，清理监听器的动作也只写一份。

兼容回退应该放在哪一层

如果目标运行环境没有 Promise.withResolvers，可以在控制器创建边界保留一个小型回退。不要在每个业务事件里重复判断：

function createResolvers() {
  if (typeof Promise.withResolvers === 'function') {
    return Promise.withResolvers();
  }

  let resolve;
  let reject;
  const promise = new Promise((resolveValue, rejectValue) => {
    resolve = resolveValue;
    reject = rejectValue;
  });
  return { promise, resolve, reject };
}

能力检测只回答“能不能创建这组对象”，并不回答“业务是否会重复调用”。因此无论走新 API 还是回退，都要复用前面的 finish 收口逻辑。

几个容易误判的边界

• 它不是可重复使用的事件总线：一个 Promise 结算后，后续事件不会产生第二个结果。
• 把 resolve 暴露给太多模块会扩大控制权，最好由一个控制器持有并负责清理。
• 回退代码需要同时保存 resolve 和 reject，只保存其中一个会让取消或超时无法收口。

相关问题

Promise.withResolvers 会改变 Promise 的异常传播吗？

不会。异常仍通过 reject 或异步回调中的错误路径进入 Promise，调用方仍应使用 catch 或 try...catch。

为什么不能让确认和超时分别直接调用结算函数？

这样会把监听器清理、重复结算和日志记录分散到多个出口，后续维护很容易漏掉一个分支。

回退工厂要不要做成全局 polyfill？

除非项目明确需要统一补齐，否则把能力检测收在业务控制器边界更容易审查，也不改变全局 Promise 对象。

采用前的最小检查

1. 确认目标运行环境支持 Promise.withResolvers，或准备好回退工厂。
2. 列出确认、取消、超时等所有出口，并让它们经过同一个 finish。
3. 检查 Promise 结算后是否移除了事件监听器，避免控制器继续持有页面节点。