Promise 是什么
Promise 是 JavaScript 中表示「一个异步操作的最终结果」的对象。 它把「将来才会拿到的值」包装成一个可以等待、可以链式处理的对象,让异步代码像同步代码一样从上往下书写,避免层层嵌套的回调地狱(callback hell)。
一句话:Promise 是结果的占位符——现在还没有值,但未来一定会以「成功」或「失败」两种方式之一给出答复,并且只答复一次。
三种状态
| 状态 | 含义 | 如何进入 |
|---|---|---|
pending(待定) | 初始状态,结果还没出来 | 新建 Promise 时 |
fulfilled(已兑现) | 成功,携带一个结果值 | 调用 resolve(value) |
rejected(已拒绝) | 失败,携带一个原因(通常是 Error) | 调用 reject(reason),或执行器内抛错 |
两条铁律:
- 状态只能改变一次。一旦从
pending落到fulfilled或rejected,就永久固定,之后再调用resolve/reject都不会生效。 - 状态不可逆。成功不会变失败,失败也不会变成功。
创建一个 Promise
new Promise(executor) 接收一个执行器函数,执行器会立即同步执行,其中拿到 resolve 和 reject 两个参数:
function delay(ms: number): Promise<void> {
return new Promise<void>((resolve) => {
setTimeout(() => resolve(), ms);
});
}
function fetchUserName(id: number): Promise<string> {
return new Promise((resolve, reject) => {
setTimeout(() => {
if (id > 0) {
resolve('用户' + id); // 成功,结果向下传递
} else {
reject(new Error('无效的用户 ID')); // 失败
}
}, 100);
});
}
平时更常见的做法是直接返回别人给的 Promise(例如 fetch、数据库驱动、SDK 的异步方法),只有包装回调风格的旧 API 时才需要自己 new Promise。
消费结果:then / catch / finally
.then(onFulfilled, onRejected):成功走第一个回调,失败走第二个(一般省略第二个,统一交给catch)。.catch(onRejected):捕获链上任意位置的失败,等价于.then(undefined, onRejected)。.finally(onFinally):无论成功失败都会执行,常用于清理(关闭 loading、释放连接)。回调不接收参数,返回值不影响后续结果(除非它抛出异常)。
fetchUserName(1)
.then((name) => console.log('成功:', name))
.catch((err) => console.error('失败:', err.message))
.finally(() => console.log('结束,关闭 loading'));
链式调用:then 的返回值决定下一步
这是 Promise 最关键的机制:
- 回调返回普通值 → 下一个
.then收到这个值; - 回调返回另一个 Promise → 会等它完成,再把结果传给下一个
.then(自动「解包」,不会出现 Promise 套 Promise); - 回调抛出异常 → 跳过后续所有
then,直达最近的catch。
interface User {
id: number;
name: string;
}
function getUser(id: number): Promise<User> {
return Promise.resolve({ id, name: '张三' });
}
function getOrders(userId: number): Promise<string[]> {
return Promise.resolve(['A1', 'A2']);
}
getUser(1)
.then((user) => getOrders(user.id)) // 返回 Promise,链会等它
.then((orders) => {
if (orders.length === 0) throw new Error('没有订单'); // 主动抛出,走 catch
return orders[0]; // 返回普通值,继续向下传
})
.then((orderId) => console.log('订单号', orderId))
.catch((err: Error) => console.error(err.message));
忘记 return 是最常见的 bug:若箭头函数体用了大括号却只调用不返回,下一个 .then 收到的是 undefined,而且整条链也不会等待请求完成。错误写法形如 .then(user => { getOrders(user.id); }) (大括号里没有 return),正确写法是 .then(user => getOrders(user.id)) 。
静态方法对照
| 方法 | 作用 | 结果 |
|---|---|---|
Promise.resolve(v) | 把值包装成成功的 Promise | 单个值 |
Promise.reject(e) | 直接创建一个失败的 Promise | 失败原因 |
Promise.all(list) | 全部成功才成功,任一失败立即失败 | 结果数组(顺序与输入一致) |
Promise.allSettled(list) | 等全部结束,无论成败 | {status, value/reason} 数组 |
Promise.race(list) | 第一个结束的(无论成败) | 那个值或原因 |
Promise.any(list) | 第一个成功的,全部失败才失败 | 那个值(AggregateError) |
// 并发执行,全部成功才继续;任一失败直接进 catch
const [user, orders] = await Promise.all([getUser(1), getOrders(1)]);
// 允许部分失败,逐条检查结果
const results = await Promise.allSettled([getUser(1), getOrders(-1)]);
// 超时控制:让「超时」与「真实请求」赛跑
function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {
const timeout = new Promise<never>((_, reject) =>
setTimeout(() => reject(new Error('请求超时')), ms)
);
return Promise.race([task, timeout]);
}
注意 Promise.all 是并发而不是顺序:需要按依赖顺序执行时,必须用 then 链或用 await 一条条写。
和 async / await 的关系
async / await 是 Promise 的语法糖,底层仍然是 Promise:
async函数一定返回 Promise;返回普通值会自动包成Promise.resolve(值)。await遇到 Promise 会等待其落定:成功则拿到值,失败则以抛异常的方式从await处抛出。
async function loadOrderId(id: number): Promise<string | null> {
try {
const user = await getUser(id);
const orders = await getOrders(user.id); // 串行:需要上一步结果
return orders[0] ?? null;
} catch (err) {
console.error((err as Error).message);
return null;
}
}
// 无依赖关系的任务应该并发,而不是串行 await
async function loadBoth(id: number) {
const [user, orders] = await Promise.all([getUser(id), getOrders(id)]);
return { user, orders };
}
TypeScript 中的类型
Promise<T> 的类型参数 T 就是成功值的类型;失败值(reject 的原因)在标准库中没有类型参数,通常当作 unknown 处理,用 instanceof Error 或类型守卫收窄。
const p: Promise<number> = Promise.resolve(1);
// 可调用的 Promise:类型是函数,返回值是 Promise
type AsyncHandler = () => Promise<void>;
// 注意不要写成 Promise<Promise<T>>,async 函数已被自动展平
async function ok(): Promise<string> {
return 'ok';
}
常见坑
- 忘了 return:链不等待,后续拿到
undefined。 - 在
forEach里写 async:forEach不会等待回调,循环立刻结束。改用for…of+await,或Promise.all(list.map(…))。 - 未处理的 rejection:没有
catch的失败 Promise 会触发unhandledrejection,在 Node 中可能导致进程退出。 - 多余的 new Promise 包装:已有 Promise 时直接
return它,不要套一层。 - 在
then里继续写回调风格:容易丢错误,尽量统一成 Promise 风格。 - 把串行当并发:连续
await是串行,无依赖时用Promise.all并行更快。
一句话小结
Promise = 异步结果的状态容器 + 可链式传递的错误通道。记住三点:状态只变一次、then 的返回值决定下一步、失败沿链传播直到被 catch。
思维导图
# Promise ## 是什么 - 异步结果的占位符 - 解决回调地狱 - 状态只能改变一次 ## 三种状态 - pending 待定 - fulfilled 已兑现 - rejected 已拒绝 ## 创建 - new Promise(executor) - 执行器同步执行 - resolve / reject ## 消费 - then 处理成功 - catch 处理失败 - finally 收尾清理 ## 链式调用 - 返回普通值继续传 - 返回 Promise 自动等待 - 抛异常跳到 catch - 忘记 return 拿到 undefined ## 静态方法 - all 全部成功 - allSettled 等全部结束 - race 第一个结束 - any 第一个成功 ## async await - async 必返回 Promise - await 等待落定 - 错误用 try catch - 无依赖改用 Promise.all ## 常见坑 - forEach 里写 async - 未处理 rejection - 串行当并发