如何为JS库实现同步异步双API？解决await已决议Promise的异步问题

一、为什么await已决议Promise仍会推入事件队列？ #

这是ECMAScript规范明确规定的行为：无论await后面的Promise是否已经决议，await之后的代码都会被包装成一个微任务，加入到事件队列中延迟执行。

这么设计的核心目的是保证await行为的一致性——不管你等待的是一个立即决议的Promise，还是一个需要等待异步操作的Promise，后续代码的执行时机都是异步的（微任务阶段），避免出现“有时候同步、有时候异步”的混乱逻辑，防止开发者因为状态差异写出依赖执行顺序的脆弱代码。

举个直观的例子：

async function test() {
  console.log(1);
  await Promise.resolve();
  console.log(3);
}
test();
console.log(2);
// 输出顺序：1 → 2 → 3

哪怕await的是已决议的Promise，console.log(3)也会被放到微任务队列，等当前同步代码执行完才会运行。

二、更优实现方案 #

要同时满足「使用者可通过Promise控制执行时机」和「传入已决议Promise/普通值时同步执行」的需求，且避免调用时强制使用await，可以通过区分参数类型+同步检测Promise状态的方式实现，具体代码如下：

1. 封装同步解析工具函数 #

这个函数可以同步获取已决议Promise的结果，对未决议Promise则返回原Promise等待：

function resolveSyncOrAsync(input) {
  if (!(input instanceof Promise)) {
    // 普通值直接返回同步结果
    return { isSync: true, value: input };
  }

  let result;
  let isResolved = false;
  // 同步绑定回调，已决议的Promise会立即执行回调
  input.then(
    val => {
      result = { isSync: true, value: val };
      isResolved = true;
    },
    err => {
      result = { isSync: true, error: err };
      isResolved = true;
    }
  );

  if (isResolved) {
    // 已决议，返回同步结果
    return result;
  } else {
    // 未决议，返回异步处理的Promise
    return {
      isSync: false,
      promise: input.then(val => ({ isSync: true, value: val }))
    };
  }
}

2. 修改库函数实现 #

利用上面的工具函数，实现同步/异步逻辑的分支处理：

export function processName(nameOrPromise) {
  const resolution = resolveSyncOrAsync(nameOrPromise);

  if (resolution.isSync) {
    if (resolution.error) {
      throw resolution.error;
    }
    // 同步执行核心逻辑
    console.log(`Hello ${resolution.value}!`);
  } else {
    // 异步等待Promise决议后执行
    resolution.promise.then(res => {
      console.log(`Hello ${res.value}!`);
    }).catch(err => {
      console.error(err);
    });
  }
}

使用示例 #

• 传入普通值/已决议Promise：同步输出

processName("Alice");
processName(Promise.resolve("Peter"));
console.log("Done processing!");
// 输出顺序：Hello Alice! → Hello Peter! → Done processing!

• 传入未决议Promise：等待决议后执行

let resolveName;
const namePromise = new Promise(resolve => {
  resolveName = resolve;
});
processName(namePromise);
console.log("Waiting for name...");
// 输出：Waiting for name...
// 调用resolveName后输出：Hello Bob!
resolveName("Bob");

这个方案既保留了使用者通过Promise控制执行时机的能力，又解决了已决议Promise导致的异步执行问题，同时不需要使用者强制await调用。

内容的提问来源于stack exchange，提问作者Peppe L-G