JavaScript Promise API 详解

Promise 是 JavaScript 中用于异步编程的核心对象，它代表一个异步操作的最终完成（或失败）及其结果值。

基本用法

const promise = new Promise((resolve, reject) => {
  // 异步操作
  if (/* 操作成功 */) {
    resolve(value); // 成功时调用
  } else {
    reject(error); // 失败时调用
  }
});

Promise 实例方法

1. then()

• 用于添加 Promise 状态变为 fulfilled 或 rejected 时的回调函数
• 返回一个新的 Promise

promise.then(
  value => { /* 成功处理 */ },
  error => { /* 失败处理 */ }
);

2. catch()

• 用于处理 Promise 被拒绝的情况
• 相当于 .then(null, rejectionHandler)

promise.catch(error => {
  console.error('Error:', error);
});

3. finally()

• 无论 Promise 最终状态如何都会执行
• 不接收任何参数，无法知道 Promise 是成功还是失败

promise.finally(() => {
  // 清理工作
});

Promise 静态方法

1. Promise.resolve()

• 返回一个 resolved 状态的 Promise

Promise.resolve('success');
// 等同于
new Promise(resolve => resolve('success'));

2. Promise.reject()

• 返回一个 rejected 状态的 Promise

Promise.reject(new Error('failure'));
// 等同于
new Promise((resolve, reject) => reject(new Error('failure')));

3. Promise.all()

• 接收一个 Promise 数组，当所有 Promise 都成功时返回结果数组
• 如果有一个失败，立即 reject

Promise.all([promise1, promise2, promise3])
  .then(values => {
    console.log(values); // [result1, result2, result3]
  })
  .catch(error => {
    console.error(error); // 任一失败
  });

4. Promise.allSettled()

• 等待所有 Promise 完成（无论成功或失败）
• 返回一个对象数组，每个对象描述每个 Promise 的结果

Promise.allSettled([promise1, promise2])
  .then(results => {
    results.forEach(result => {
      if (result.status === 'fulfilled') {
        console.log('成功:', result.value);
      } else {
        console.log('失败:', result.reason);
      }
    });
  });

5. Promise.race()

• 返回第一个 settled（无论成功或失败）的 Promise 的结果

Promise.race([promise1, promise2])
  .then(value => {
    console.log('第一个完成的值:', value);
  })
  .catch(error => {
    console.error('第一个错误:', error);
  });

6. Promise.any()

• 返回第一个 fulfilled 的 Promise 的结果
• 如果所有 Promise 都 rejected，则返回 AggregateError

Promise.any([promise1, promise2])
  .then(value => {
    console.log('第一个成功的值:', value);
  })
  .catch(errors => {
    console.error('所有Promise都失败了:', errors);
  });

Promise 链式调用

doSomething()
  .then(result => doSomethingElse(result))
  .then(newResult => doThirdThing(newResult))
  .then(finalResult => {
    console.log('最终结果:', finalResult);
  })
  .catch(failureCallback);

注意事项

1. Promise 的状态一旦改变就不可逆（pending → fulfilled 或 pending → rejected）
2. 如果未设置错误处理程序，Promise 中的错误可能会被静默忽略
3. Promise 的回调是异步执行的（微任务队列）
4. 在构造函数中抛出错误会自动 reject

Promise 是现代 JavaScript 异步编程的基础，也是 async/await 语法的基础。