一个不正确的 TypeScript 类型定义引发的血案

Mongoose 的 TypeScript 类型定义并不完全正确！

昨天晚上在 bgs 研究了（或者说调试了）XGS 写的 nodejs 服务器项目。他在用 koa 作为服务器，mongodb 作为数据存储，写一个不知道什么项目（似乎名为「写作者平台」/ “Write’s Platform”）。反正当时还处于很初级的阶段，只有两个路由，一个 get，一个 post，后者是用来向 mongodb 提交一篇文章的。在测试过程中，他发现了一个问题——他在保存文章的回调中更改了响应的内容（如下），但是实际测试得到的响应内容却是 koa 默认的 OK。

router.post('/path', (ctx, next) => {
    const article = new Article( /* something */ );
    article.save((err, article) => {
      if (err){
        ctx.body = err;
      } else {
        ctx.body = "success";
      }
    });
})

起初我发现，他的代码中，router.post('/path', (ctx, next) => { /* body */ });的/* body */这段中并没有返回 next()，这应该会导致异步的回调没有被阻塞。

接着我想，可能又是 koa 的版本搞混了什么的，因为 koa v2，koa router 什么的版本管理都很混乱，长期处于虽然大家都想使用最新版，但是默认的却一直是旧版的情况。后来又出现了 koa 是新版，router 是旧版的情况，曾经我为别人解决过这个问题。

但是这次却不是。并且把返回 promise 切换为使用 async/await之后（如下），情况依然没有好转。

router.post('/path', (ctx, next) => {
    const article = new Article( /* something */ );
    return article.save((err, saved) => {
      if (err){
        ctx.body = err;
      } else {
        console.log(saved);
        ctx.body = "success";
      }
      // or `return next();` here.
    }).then((thing) => {
        console.log(thing);
        return next();
    });
})

（过程中我们发现这个传给回调的 thing居然是undefined，这是个伏笔）

渐渐地我被各种函数的签名（比如究竟应该返回一个什么，是 next() 还是一个 promise，而 next 的类型又是什么？）搞得烦躁起来。于是我提议使用 TypeScript 来辅助检查。

我们开始怀疑 article.save这个函数。因为在 koa 官方（仅有）的、涉及到等待异步动作的 router 代码样例里，完全类似的代码是可以工作的：

router.get(
  '/users/:id',
  function (ctx, next) {
    return User.findOne(ctx.params.id).then(function(user) {
      ctx.user = user;
      return next();

    });
  },
  function (ctx) {
    console.log(ctx.user);
    // => { id: 17, name: "Alex" }
  }
);

于是我们着重检查了 mongoose 的 TypeScript 类型定义文件。这个 article是Article的实例，而Article实际上是 mongoose 动态构造出来的一个类（应该是通过了某种元编程技术）。在类型定义中是这么反映的：

interface Model<T extends Document> extends NodeJS.EventEmitter, ModelProperties {
    new(doc?: Object): T;
    /* other things */
}

而 article 就是那个<T extends Document>，而 Document的save方法是这么写的：

    /**
     * Saves this document.
     * @param options options optional options
     * @param options.safe overrides schema's safe option
     * @param options.validateBeforeSave set to false to save without validating.
     * @param fn optional callback
     */
    save(options?: SaveOptions, fn?: (err: any, product: this, numAffected: number) => void): Promise<this>;
    save(fn?: (err: any, product: this, numAffected: number) => void): Promise<this>;

（取自 npm install @types/mongoose的结果，不知为何与 DefinitelyTyped 上的有所不同。）看到这，特别是Promise<this>，我就确信了，这个函数没有问题。可是上面返回的thing又确乎是一个undefined，难道是我们的使用姿势有问题？

万般无奈之中，TypeScript 也不靠谱之际，我们只能诉诸源码了。鉴于 mongoose 的代码风格，直接搜索 .prototype.save就能找到。它实际上是在这里，但是看到这里让人更崩溃了：

Model.prototype.save = function(options, fn) {
  if (typeof options === 'function') {
    fn = options;
    options = undefined;
  }

  if (!options) {
    options = {};
  }

  if (fn) {
    fn = this.constructor.$wrapCallback(fn);
  }

  return this.$__save(options, fn);
};

它返回的是this.$__save的结果，但这个函数并没有返回值！日志显示，这里的this就是这个article实例（一个Document）。然而线索到这里似乎断了。怎么能凭空从一个没有返回值的函数返回一个 promise 呢？

我们又想到了一招：查看调用栈。但是 node 的调试器在这时却不好使了。我们只能用原始粗暴的console.trace手动搞出调用栈。虽然没有直接的线索，这个调用栈给了我们一些提示——save并不是直接调用的，而是经过了某种hook的封装。

这时，我想到了直接console.log(article.save)，它居然是一个wrappedPointCut出来的结果！再在代码里搜索wrappedPointCut就非常接近真相了。关键的代码在这里：

model.prototype[pointCut] = (function(_newName) {
      return function wrappedPointCut() {
        var Promise = PromiseProvider.get();

        var _this = this;
        /* something omitted for simplicity */
        var promise = new Promise.ES6(function(resolve, reject) {
          args.push(function(error) {
            if (error) {
              /* something omitted for simplicity */
              reject(error);
              return;
            }
            $results = Array.prototype.slice.call(arguments, 1);
            resolve.apply(promise, $results);
          });
          _this[_newName].apply(_this, args);
        });
        if (fn) {
          /* something omitted for simplicity */
          return promise.then(
            function() {
              process.nextTick(function() {
                fn.apply(null, [null].concat($results));
              });
            },
            function(error) {
              process.nextTick(function() {
                fn(error);
              });
            });
        }
        return promise;
      };
    })(newName);

注意到如果没有fn，那么会在第 33 行返回第 7 行定义的 promise，如果有fn，就会直接在第 21 行返回接续之前的 promise 的另一个 promise，这个接续（.then()）里面利用了fn处理了结果，却没有返回。也就是说，这时候的返回值是Promise<undefined>而不是Promise<this>——我们被这样的 TypeScript 类型定义坑惨了！如果它一开始就告诉我们会这样，那该多好呀，就像这样：

    save(options: SaveOptions, fn: (err: any, product: this, numAffected: number) => void): Promise<undefined>;
    save(fn: (err: any, product: this, numAffected: number) => void): Promise<undefined>;
    save(options?: SaveOptions): Promise<this>;
    save(): Promise<this>;

2017 年 5 月 4 日