====== 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 {
return new Promise((resolve) => {
setTimeout(() => resolve(), ms);
});
}
function fetchUserName(id: number): Promise {
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 {
return Promise.resolve({ id, name: '张三' });
}
function getOrders(userId: number): Promise {
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(task: Promise, ms: number): Promise {
const timeout = new Promise((_, 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'' 处抛出。
* 因此用 ''await'' 时错误要用 ''try / catch'' 捕获(见 [[typescript:什么是try_catch]]),而不是 ''.catch''。
async function loadOrderId(id: number): Promise {
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'' 就是**成功值的类型**;失败值(reject 的原因)在标准库中没有类型参数,通常当作 ''unknown'' 处理,用 ''instanceof Error'' 或类型守卫收窄。
const p: Promise = Promise.resolve(1);
// 可调用的 Promise:类型是函数,返回值是 Promise
type AsyncHandler = () => Promise;
// 注意不要写成 Promise>,async 函数已被自动展平
async function ok(): Promise {
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**。
===== 思维导图 =====
```mdk height=520 color=#2563eb
# 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
- 串行当并发
```