Promise.withResolvers用于提前创建可外部决议的Promise，天然适配状态机设计：预定义状态+可控跃迁，各状态独立持有resolvers，通过resolve/reject主动推进流程，支持取消、超时与多分支跳转。
Promise.withResolvers 不是用来“干预已存在 Promise”的工具，而是用来**提前创建一个可被外部逻辑决议的 Promise 实例**。它天然适合构建状态机：每个状态转移可对应一次 resolve 或 reject，且触发时机完全由业务逻辑控制，不依赖异步回调嵌套。
状态机设计核心思路
把整个工作流抽象为一组**预定义状态 + 可控跃迁条件**。每个状态节点返回一个 Promise（由 withResolvers 创建），后续状态通过调用其 resolve/reject 主动推进，而非等待固定异步事件。
- 每个状态独立持有自己的 { promise, resolve, reject }，互不干扰
- resolve 传入的是下一状态的标识或数据，reject 表示流程中断或错误终止
- 外部可随时调用 resolve("cancel") 或 reject(new AbortError()) 强制退出当前阶段
- 消费者只 await 最顶层的 promise，内部状态流转对上层透明
典型三态工作流示例：初始化 → 运行 → 完成/失败
以下是一个带手动取消、超时和错误注入能力的轮询状态机：
const createWorkflow = () => {
// 阶段1：初始化（同步准备）
const init = Promise.withResolvers();
// 阶段2：运行中（可轮询、可中断）
const run = Promise.withResolvers();
// 阶段3：最终结果（只读出口）
const done = Promise.withResolvers();
// 初始化完成后，自动进入运行态
init.promise.then(() => {
// 模拟初始化成功，启动轮询逻辑
let attempts = 0;
const poll = async () => {
if (attempts >= 3) return run.reject(new Error("init failed"));
try {
const res = await fetch("/api/ready");
const data = await res.json();
if (data.status === "ready") {
run.resolve(data);
} else {
attempts++;
setTimeout(poll, 500);
}
} catch (e) {
run.reject(e);
}
};
poll();
}).catch(done.reject);
// 运行态决议后，进入完成态
run.promise.then(result => done.resolve({ status: "success", data: result }))
.catch(err => done.resolve({ status: "error", error: err }));
// 对外暴露可控接口
return {
promise: done.promise,
start: () => init.resolve(), // 启动工作流
cancel: () => run.reject(new AbortError("canceled")),
forceSuccess: (data) => run.resolve(data),
timeout: (ms) => setTimeout(() => run.reject(new Error(`timeout ${ms}ms`)), ms)
};
};
// 使用方式
const wf = createWorkflow();
wf.start();
wf.timeout(5000); // 5秒未就绪则失败
wf.promise.then(console.log); // { status: "success", data: ... }
如何支持多分支状态跳转
当状态机需要根据响应内容选择不同路径（如“重试”、“降级”、“跳过”）时，不要在 resolve 中传原始值，而应传结构化指令对象：
- resolve({ next: "retry", delay: 1000 })
- resolve({ next: "fallback", config: { useCache: true } })
- resolve({ next: "done", result: "ok" })
每个状态节点监听自身 promise，解析指令后递归调用对应分支函数，形成清晰的状态图。这种方式比嵌套 .then 更易维护，也避免了 Promise 链断裂后无法捕获中间 reject 的问题。
关键注意事项
Promise.withResolvers 创建的 resolve/reject 是纯函数，调用即生效，不捕获异常——这意味着你必须自己处理调用过程中的错误，否则会抛到全局。
- 重复调用 resolve 或 reject 会被忽略，不会报错，但状态不会再变
- 已决议的 promise 无法被再次决议，所以状态机每步只能推进一次
- 若需兼容旧环境，fallback 实现必须确保 executor 立即执行，且 resolve/reject 绑定正确（不能延迟赋值）
它不是魔法，而是把原本散落在各处的手动 Promise 控制权，收束成一组语义明确、作用域干净的函数。
