这个章节我们要来探讨 JavaScript 在 ES6 之后添加的 Promise。究竟它是如何解决以往用回呼函数来开发 JavaScript 程序所造成的问题呢?

先来回顾一下上一章用回呼函数的方式所撰写的文件处理程序,如下:

import fs = require("fs");
import path = require("path");

const INPUT_PATH = "input";
const OUTPUT_FOLDER = "folder";
const OUTPUT_NAME = "output";

fs.stat(INPUT_PATH, (err, stats) => {
    if (err) {
        console.error(err);
        return;
    }

    console.log(stats);

    fs.mkdir(OUTPUT_FOLDER, { recursive: true }, (err) => {
        if (err) {
            console.error(err);
            return;
        }

        const outputPath = path.join(OUTPUT_FOLDER, OUTPUT_NAME);

        fs.copyFile(INPUT_PATH, outputPath, (err) => {
            if (err) {
                console.error(err);
                return;
            }

            fs.unlink(INPUT_PATH, (err) => {
                if (err) {
                    console.error(err);
                }

                console.log("Done!");
            });
        });
    });
});

由于 Node.js 的 fs 模块提供的 stat、mkdir、copyFile 和 unlink 函数都是异步的文件处理 API,因此我们需要在回呼函数中确认 API 的运行结果,且同样要在回呼函数中再去调用下一个文件处理的 API。写到后来我们的程序叙述区块就会愈写愈多层、愈来愈难看,也愈来愈难维护。

Promise

为了解决上述的回呼函数代码写到后来会变得难以撰写、也难以阅读的问题,在 ES6 之后,添加了 Promise 对象。这个 Promise 对象可以用来将异步的 API 改成「看起来同步」的用法。

Promise 的基本用法

Promise 对象的最基本用法如下:

const promise = new Promise((resolve, reject) => {
    ...
});

利用 new 关键字可以产生 Promise 的对象实体。构造器的部份可以传入一个回呼函数作为参数,这个函数有两个参数,第一个为 resolve,第二个为 reject。当 Promise 对象被创建的时候,就会去同步运行这个回呼函数。举例来说:

process.nextTick(() => {
    console.log('nextTick');
});

const promise = new Promise((resolve, reject) => {
    console.log('promise');
});

以上程序会输出:

promise
nextTick

resolve 参数其实是一个函数,这个函数可以传入一个参数,作为回传的「正确值」。reject 参数也是一个函数,这个函数可以传入一个参数,作为回传的「错误值」,或者称「错误原因」。举例来说:

import fs = require("fs");

const INPUT_PATH = "input";

const promise = new Promise((resolve, reject) => {
    fs.stat(INPUT_PATH, (err, stats) => {
        if (err) {
            return reject(err);
        }

        resolve(stats);
    });
});

以上程序,在 JavaScript 线程进入事件循环之前,就会先去调用传入 Promise 构造器的回呼函数,在这个函数中,我们去调用了 Node.js 的 fs 模块提供的 stat 函数,这个是会异步运行的函数,所以我们还要在它的第二个参数传给它一个回呼函数,作为 stat「运行完毕」的事件触发后要运行的函数。一旦 stat「运行完毕」的事件被触发,这个事件就会被保存在事件循环第四阶段(poll 阶段)的队列中。

JavaScript 线程运行到事件循环的第四阶段时,就会去运行传入 stat 函数的回呼函数。一开始会先去判断回呼函数的 err 参数是否不是 undefined、null、false、0 或 NaN,如果不是的话表示 stat 函数在处理过程中有错误发生,此时将 err 作为参数来调用 reject 函数,便可以将这个「错误原因」给「回传」出来。reject 函数(和 resolve 函数)本身并没有回传值(void),所以为了不让 stat 的回呼函数在调用 reject 函数后继续运行下去,程序第 8 行的部份还用了 return 关键字来直接让回呼函数回传 undefined。

如果 stat 函数的运行过程正常,就用 resolve 函数把 stats 参数所保存的结果给「回传」出来。

也就是说,如果 stat 函数的运行过程正常,promise 常数的值就是 stats 参数的值吗?

当然不是!这边的 promise 常数的值在 JavaScript 进入事件循环之前就决定好了,它就是一个 Promise 对象实体。

所以我们究竟要怎么取得 resolve 函数或是 reject 函数「回传」出来的值?这就要靠 Promise 对象实体提供的 then 和 catch 方法啦!

如下:

import fs = require("fs");

const INPUT_PATH = "input";

const promise = new Promise((resolve, reject) => {
    fs.stat(INPUT_PATH, (err, stats) => {
        if (err) {
            return reject(err);
        }

        resolve(stats);
    });
});

promise
    .then((stats) => {
        console.log(stats);
    })
    .catch((err) => {
        console.error(err);
    });

以上程序,利用 Promise 对象实体(promise)的 then 方法,可以让 resolve 函数被调用的时候,去创建一个微任务,这个微任务要运行的函数即为传入 then 方法第一个参数的函数。promise 的 catch 方法,可以让 reject 函数被调用的时候,去创建一个微任务,这个微任务要运行的函数即为传入 catch 方法第一个参数的函数。

这边要注意的是,then 和 catch 方法都会产生出新的 Promise 对象实体,所以如果要将它们分开调用的话,要记得用一个常数或变量来保存回传值。例如:

const p1 = promise.then((stats) => {
    console.log(stats);
});

const p2 = p1.catch((err) => {
    console.error(err);
});

不要写成以下这样:

promise.then((stats) => {
    console.log(stats);
});

promise.catch((err) => {
    console.error(err);
});

then 方法可以被调用多次,且可以被置于 catch 方法之后。第一个的 then 方法如果是以 resolve 函数来触发的话,其回呼函数的第一个参数即为传入 resolve 函数作为第一个参数的值。但如果是 reject 函数被运行,且 catch 方法之后有使用 then 方法,则这个 then 方法也会被触发,其回呼函数第一个参数的值此时会为 catch 方法的回呼函数的回传值。

例如:

promise
    .catch((err) => {
        console.error(err);
        return err;
    })
    .then((statsOrErr) => {
        console.log(statsOrErr);
    });

以上程序,then 方法的回呼函数的第一个参数的值可能是 promise 回传的「正确值」或是「错误值」。

同样地,如果 then 方法后又有 then 方法,则后者的回呼函数的第一个参数的值,为前者的回呼函数所回传的值。

例如:

promise
    .then((stats) => {
        console.log(stats);
        return true;
    })
    .catch((err) => {
        console.error(err);
        return false;
    })
    .then((status) => {
        console.log(status);
    });

以上程序,最后一个 then 方法的回呼函数有可能会在主控台输出 true(如果 promise 是回传正确值)或是 false(如果 promise 是回传错误值)。在 then 方法或是 catch 方法之后触发的 then 方法,会产生新的微任务。

then 方法其实也可以传入两个回呼函数,第一个就是原本的回呼函数,第二个是用来传入原本要传入 catch 方法的回呼函数,也就是说这时就不需要用 catch 方法了。例如:

promise
    .then((stats) => {
        console.log(stats);
        return true;
    }, (err) => {
        console.error(err);
        return false;
    })
    .then((status) => {
        console.log(status);
    });

以上写法和原本使用 catch 方法的写法的逻辑并不一样,只不过目前还体现不出来,稍后会再提到。

若 then 方法和 catch 方法的回呼函数是回传 Promise 对象实体,则它们之后的 then 方法的回呼函数的第一个参数即为该 Promise 对象实体的「正确值」。在这种情况下,也可以加入更多 catch 方法来接收 Promise 对象实体的「错误值」。当然,也还是可以只使用一个 catch 方法来处理这些 Promise 对象实体的「错误值」,只要将该 catch 方法放在所有的 then 方法后面来调用即可。

例如:

promise
    .then((stats) => {
        console.log(stats);
        return new Promise((resolve) => {
            resolve(true);
        });
    })
    .catch((err) => {
        console.error(err);
        return new Promise((resolve, reject) => {
            reject(false);
        });
    })
    .then((status) => {
        console.log(status);
    })
    .catch((status) => {
        console.error(status);
    });

以上程序,若 promise 是回传「正确值」,第一个 then 方法的回呼函数就会被运行,它会回传一个新的 Promise 对象实体,这个 Promise 对象实体只会回传一个 true 作为「正确值」,此时第一个 then 方法之后的 then 方法和 catch 方法就等同于是第一个 then 方法回传的 Promise 对象实体的 then 方法和 catch 方法。

当然,若以上程序的 promise 是回传「错误值」,第一个 catch 方法的回呼函数就会被运行,它会回传一个新的 Promise 对象实体,这个 Promise 对象实体只会回传一个 false 作为「错误值」,此时第一个 catch 方法之后的 then 方法和 catch 方法就等同于是第一个 catch 方法回传的 Promise 对象实体的 then 方法和 catch 方法。

所以,以上程序,有可能会在主控台输出 true(如果 promise 是回传正确值)或是 false(如果 promise 是回传错误值)。

事实上,Promise 对象本身就有提供 resolve 和 reject 函数,可以用来简化以上程序的写法。如下:

promise
    .then((stats) => {
        console.log(stats);
        return Promise.resolve(true);
    })
    .catch((err) => {
        console.error(err);
        return Promise.reject(false);
    })
    .then((status) => {
        console.log(status);
    })
    .catch((status) => {
        console.error(status);
    });

这边要注意的是,如果我们将以上程序的 resolve 函数改成 reject,第一个 catch 方法的回呼函数就会被运行。如果我们想确保第一个 then 方法的回呼函数所回传的 Promise 对象实体不会被其之后原本是要接收 promise「错误值」的第一个 catch 方法影响的话,这时就要使用上面提到的方式,将 catch 方法拿掉,把其回呼函数传进 then 方法的第二个参数中。如下:

promise
    .then((stats) => {
        console.log(stats);
        return new Promise((resolve, reject) => {
            // simulate a correct or erroneous result
            if (Math.floor(Math.random() * 2)) {
                resolve(true);
            } else {
                reject(null);
            }
        });
    }, (err) => {
        console.error(err);
        return Promise.reject(false);
    })
    .then((status) => {
        console.log(status);
    })
    .catch((status) => {
        console.error(status);
    });

Promise 对象实体的 finally 方法可以被调用多次,通常会置于 then 方法和 catch 方法之后使用。finally 方法的第一个参数需要传入一个无参数的函数,这个函数的回传值不会影响到其它方法的回呼函数。finally 方法若置于 then 和 catch 方法前,则会被 resolve 或 reject 函数触发,产生微任务,传入 finally 方法的函数会被运行。finally 方法若置于 then 和 catch 方法后,则其函数也会在这些方法被触发之后跟着被触发。

例如:

promise
    .then((stats) => {
        console.log(stats);
    })
    .catch((err) => {
        console.error(err);
    })
    .finally(() => {
        console.log("Done!");
    });

依序运行多个 Promise 对象实体

以我们刚才写的「取得一个文件的信息,并创立一个目录,将这个文件拷贝进新的目录下,然后再把原本的文件删除」程序来举例,可用 Promise 对象改写如下:

import fs = require("fs");
import path = require("path");

const INPUT_PATH = "input";
const OUTPUT_FOLDER = "folder";
const OUTPUT_NAME = "output";

const pStat = () => new Promise((resolve, reject) => {
    fs.stat(INPUT_PATH, (err, stats) => {
        if (err) {
            return reject(err);
        }

        resolve(stats);
    });
});

const pMkdir = () => new Promise((resolve, reject) => {
    fs.mkdir(OUTPUT_FOLDER, { recursive: true }, (err) => {
        if (err) {
            return reject(err);
        }

        resolve();
    });
});

const pCopyFile = () => new Promise((resolve, reject) => {
    const outputPath = path.join(OUTPUT_FOLDER, OUTPUT_NAME);

    fs.copyFile(INPUT_PATH, outputPath, (err) => {
        if (err) {
            return reject(err);
        }

        resolve();
    });
});

const pUnlink = () => new Promise((resolve, reject) => {
    fs.unlink(INPUT_PATH, (err) => {
        if (err) {
            return reject(err);
        }

        resolve();
    });
});

pStat()
    .then((stats) => {
        console.log(stats);

        return pMkdir();
    })
    .then(() => {
        return pCopyFile();
    })
    .then(() => {
        return pUnlink();
    })
    .then(() => {
        console.log("Done!");
    })
    .catch((err) => {
        console.error(err);
    });

虽然以上程序写起来还是挺麻烦的,但看起来比较像是同步的程序,变得更容易阅读了!

一次运行多个 Promise 对象实体并同步取得结果

利用 Promise 对象自身提供的 all 方法,可以传入一个 Promise 对象实体数组作为参数,将它们组合成一个 Promise 对象实体。这些数组中的 Promise 对象实体会被异步运行,它们回传的「正确值」会被存入一个数组中的相应位置,最终当它们全都运行完时可以透过 then 方法传入回呼函数来取得这些「正确值」的数组。当这些 Promise 对象实体中有一个回传「错误值」时,可以透过 catch 方法传入回呼函数来取得这个「错误值」。

举例来说:

const p1 = new Promise((resolve) => {
    setTimeout(() => {
        resolve("one");
    }, 1000);
});

const p2 = new Promise((resolve) => {
    setTimeout(() => {
        resolve("two");
    }, 2000);
});

const p3 = new Promise((resolve) => {
    setTimeout(() => {
        resolve("three");
    }, 3000);
});

const p4 = new Promise((resolve, reject) => {
    reject("reject");
});

Promise.all([p1, p2, p3]).then((values) => {
    console.log(values);
}, (err) => {
    console.log(err);
});

以上程序会输出:

[ 'one', 'two', 'three' ]

若将 p4 常数也加进数组中,则只会输出:

reject

Promise 对象实体的类型

Promise 有一个泛型参数,其所代表的类型即为传入其 resolve 函数的值的类型。

举例来说:

const promise = new Promise((resolve) => {
    resolve("Hello");
});

以上这个 Promise 对象实体的类型因为没有明确指定泛型参数所代表的类型,所以会被 TypeScript 编译器当成 Promise<unknown>。换句话说,我们必须在 Promise 对象实体的 then 方法的回呼函数中使用 as 关键字来将第一个参数强制转型,才能「正常」使用这个 Promise 对象实体回传的「正确值」。

例如:

const promise = new Promise((resolve) => {
    resolve("Hello");
});

promise.then((value) => {
    const s = value as string;

    console.log(s.length);
});

为了更有效地利用 TypeScript 的类型检查机制,我们最好在每次创建 Promise 的对象实体时都去指定其泛型参数代表的类型。如下:

const promise = new Promise<string>((resolve) => {
    resolve("Hello");
});

以上这个 Promise 对象实体的类型为 Promise<string>。如此一来,在使用 then 方法的时候,回呼函数的第一个参数就是 string 类型了。如下:

const promise = new Promise<string>((resolve) => {
    resolve("Hello");
});

promise.then((value) => {
    console.log(value.length);

    const n: number = value; // compilation error
});

下一个章节要来继续介绍 JavaScript 的「async / await」语法。

下一章:用「async / await」语法摆脱难以阅读的异步程序。