【outdated】Koa源码解读

2020-02-25 — 2 min read

写在前面

看了那么多文章，是时候也来回馈一下掘金这个让我等小白获益匪浅的社区了(●'◡'●)，这篇文章主要面对的是在阅读网上其他讲解 Koa2 源码文章后仍有疑惑的同学，因为我也花了两天的时间来彻底搞清它的源码机制，所以这算是刚出新手村就来回馈了~

这篇文章可能显得有些啰嗦，因为大部分文章的作者是有一定开发经验的带哥，所以有些新手向的东西直接一笔带过，这也正是为什么网上有那么多讲解好文我还要再写一篇（而且我就是个还没毕业的弟弟）：我把你们的坑踩了，你们就可以把省下来的时间做些更有意义的事情，~~比如把 react 的源码看了~~。

文章目录

文中所使用的 Koa 版本为2.11.0，新鲜的！
带注释的热乎源代码已经上传至GitHub
如果需要更好的阅读体验，可以移步俺的博客

写在前面
文章目录
四大护法
new 一个 Koa()，发生了什么？
好兄弟，我给你看个宝贝！
这个‘洋葱’切起来咋会让人笑呢(/▽＼)
错误处理，妥妥的！
总结

四大护法

Koa 的源码分为以下四个部分，

application.js，主干部分，在这里进行了中间件合并、上下文封装、处理请求&响应、错误监听等操作。
context.js，上下文封装的逻辑，deligate 库就是在这里进行代理属性。
request.js，封装ctx.request的逻辑，注意，ctx.req才是 Node 原生属性，后面会讲。
response.js, ctx.response，同上。

new 一个 Koa()，发生了什么？

1import Koa from "koa";
2import chalk from "chalk";
3
4const app = new Koa();
5
6app.listen(2333, () => {
7  console.log(chalk.green("http://localhost:2333"));
8});

这几行代码你可能写的次数比我多得多，但你是否想过启动一个这么简单的服务的过程里，Koa 为我们做了什么？

既然是实例化，那就肯定有类的存在，还少不了构造函数插一脚，我们就从源码中的类里逮几个重要人物出来先说说，如果你此前没有阅读过此类框架源码，可以顺便了解下它们的内部都做了什么。我个人觉得这篇文章很适合作为第一次读源码的同学。

1// Application类内部
2
3constructor(options) {
4    super();
5    options = options || {};
6  }
7
8 listen(...args) {
9    debug('listen');
10    const server = http.createServer(this.callback());
11    return server.listen(...args);
12  }

上面的代码我相信你读起来肯定没有问题，app 实例的 listen 方法内部还是使用了 node 原生的 listen，因此传参也不变。

1const server = http.createServer(this.callback());

提问！这里的createServer方法原本的入参是啥？
(；′⌒`) 其实我也忘了，还是去翻了 @types/node 才知道...

1// 还有一种重载不考虑哈，因为koa中没用到
2function createServer(requestListener?: RequestListener): Server;
3
4type RequestListener = (req: IncomingMessage, res: ServerResponse) => void;

上面这段代码看不懂也没事，我翻译一下，createServer原本的入参是一个请求监听器（回调函数），这个回调函数的入参是 req、res。

然后我们来看 Koa 传递给它的this.callback()是个啥：

1callback() {
2    const fn = compose(this.middleware);
3
4    const handleRequest = (req, res) => {
5      const ctx = this.createContext(req, res);
6      return this.handleRequest(ctx, fn);
7    };
8
9    return handleRequest;
10  }
11
12handleRequest(ctx, fnMiddleware) {
13    const res = ctx.res;
14    const onerror = err => ctx.onerror(err);
15    // 处理响应
16    const handleResponse = () => respond(ctx);
17    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
18  }

剧透：compose 即为中间件合并方法，最后得到的 fn 就是合并后的中间件。createContext 方法是负责为 ctx 添加属性的，这里都可以先不管。

注意这里的 handleRequest 与 this.handleRequest 不同，但就是绕个弯的事~

从上面的逻辑我们可以看到，在 callback 中我们拿到了 node 原生的 req、res 对象，通过 createContext 方法处理后把其中的属性挂载到 ctx 上，然后再通过 this.handleRequest 方法过一下，在 this.handleRequest 里，我们已经获得了初步的 ctx，这还没完，我们还要把它在中间件的人群里挨一遍毒打，然后如果都 resolve 了就可以调用 handleResponse 送它去见客户端了~

到这里相信你们已经有了一个大致的逻辑，在你实例化 koa 并使用它启动一个服务的过程中，koa 为你做了这些事

根据你的选项/参数调用 node 的内置方法。
处理原生 node 的 req、res。
根据中间件处理 ctx，和上面的 req、res 挂载到 ctx 上。（原生 req 挂载为 ctx.request）
全局错误监听，这里还没讲，请见下文~

好兄弟，我给你看个宝贝！

这一节我们来看看 koa 是如何封装 ctx 属性的：

1const response = require('./response');
2const context = require('./context');
3const request = require('./request');
4
5
6// 类内部
7constructor(options) {
8    super();
9    options = options || {};
10    this.middleware = [];
11    this.context = Object.create(context);
12    this.request = Object.create(request);
13    this.response = Object.create(response);
14  }
15
16createContext(req, res) {
17    const context = Object.create(this.context);
18    const request = context.request = Object.create(this.request);
19    const response = context.response = Object.create(this.response);
20
21    // 眼花缭乱1
22    context.app = request.app = response.app = this;
23    context.req = request.req = response.req = req;
24    context.res = request.res = response.res = res;
25    request.ctx = response.ctx = context;
26
27    // 眼花缭乱2
28    request.response = response;
29    response.request = request;
30
31    context.originalUrl = request.originalUrl = req.url;
32
33    context.state = {};
34    return context;
35  }

这一大串略显诡异的代码可能会让你想揪我衣领，冷静点...，其实这部分代码没有什么难度，也不太需要你完全掌握这一个个=号才能读懂 koa 的核心逻辑。

首先，我们导入了已经经过处理的 context、request、response，然后以其作为原型扩展了三个同名变量，这么做的好处就是我们可以在这三个变量上为所欲为，但不会影响到原型对象。

然后通过眼花缭乱 1，我们确保在 context、request、response 上的 app（实例，就是那个 this）、req、res 指向相同，还记得吧，req 和 res 是原生 node 的对象。

然后我们就可以变着花样取值了，ctx.req.url/ctx.request.req.url/ctx.response.req.url...，它们最终都指向ctx.url，这也是我们最常使用的方式（思考，为什么都指向 ctx.url？）

眼花缭乱 2 操作同样类似，但是要稍微注意下 context.state={}，这是 koa 官方推荐的命名空间，使用方式一般是在多个中间件之间共享数据（虽然我一般直接 ctx 点出来...）

然后我们来看看，context.js 中的主要逻辑

1const proto = (module.exports = {
2  toJSON() {
3    return {
4      request: this.request.toJSON(),
5      response: this.response.toJSON(),
6      app: this.app.toJSON(),
7      originalUrl: this.originalUrl,
8      req: "<original node req>",
9      res: "<original node res>",
10      socket: "<original node socket>",
11    };
12  },
13  get cookies() {
14    // ...
15  },
16
17  set cookies(_cookies) {
18    // ...
19  },
20});
21
22delegate(proto, "response").method("attachment");
23// ...
24
25/**
26 * Request delegation.
27 */
28
29delegate(proto, "request").access("url");
30// ...

toJSON 方法，可能有些同学不知道这是干啥的呃，我就顺便提一下，在你调用 JSON.stringify()时实际上就调用了这个方法。koa 这里重写了这个方法，使得你可以获取当前 ctx 的内容。
cookies 的存取器，不做赘述。
delegate，暂时只讲一下作用，使得 ctx 对象能够代理原生 req、res 的部分属性/方法，proto即为 aplication.js 中 this.context 的原型对象，如果不记得了可以返回去看一下这一步。this.context = Object.create(context);

现在我们可以知道为什么ctx.req.url/ctx.request.req.url/ctx.response.req.url都指向ctx.url了，当 ctx 上找不到属性，就会去 context（作为它的原型的那家伙）上找，

1delegate(proto, "request").access("url");
2// ...

使用这段代码，我们最终可以通过托管获取到原生 request 上的属性。

这一步我们了解了 context.js 是如何初步处理 ctx 对象的，但还有几个问题，koa 封装的 request 和 response 呢？ctx.req.url 和 ctx.reqeust.req.url 是如何指向 ctx.url 的？

我们接着来看 resuest.js，冷静下，很快的...

再次掏出这段代码来：

1constructor(options) {
2    super();
3    options = options || {};
4    this.middleware = [];
5    this.context = Object.create(context);
6    this.request = Object.create(request);
7    this.response = Object.create(response);
8  }
9
10createContext(req, res) {
11    const context = Object.create(this.context);
12    const request = context.request = Object.create(this.request);
13    const response = context.response = Object.create(this.response);
14
15    context.app = request.app = response.app = this;
16    context.req = request.req = response.req = req;
17    context.res = request.res = response.res = res;
18    request.ctx = response.ctx = context;
19
20    request.response = response;
21    response.request = request;
22
23    context.originalUrl = request.originalUrl = req.url;
24
25    context.state = {};
26    return context;
27  }

既然 resquest 是引入的，那自然要去看看源文件

1get header() {
2    return this.req.headers;
3  },
4
5  set header(val) {
6    this.req.headers = val;
7  },
8
9  get headers() {
10    return this.req.headers;
11  },
12
13  set headers(val) {
14    this.req.headers = val;
15  },
16
17  get url() {
18    // this即为ctx this.req即为原生req
19    return this.req.url;
20  },
21
22  set url(val) {
23    this.req.url = val;
24  },

是的，这里面就是一堆存取器...，也就是说，ctx.request.url就可以了，不需要再ctx.request.req.url，因为它的内部会自动代理到原生 req 上，就相当于 ctx.request 中有了这个属性。

~~ctx 到这里就处理完毕了~~，当然不，我们还要走一轮中间件呢。

这个‘洋葱’切起来咋会让人笑呢(/▽＼)

接下来就到了 Koa2 最精彩的部分了，洋葱模型其实不难理解（但是你让我实现的话我不行...），看这样一段代码：

1app.use(async (ctx, next) => {
2  console.log("middleware-1-start");
3  await next();
4  console.log(ctx.state.someProp);
5  console.log("middleware-1-end");
6});
7
8app.use(async (ctx, next) => {
9  console.log("middleware-2-start");
10  ctx.state.someProp = "Get 2";
11  await next();
12  console.log("middleware-2-end");
13});

输出结果是

1middleware-1-start
2middleware-2-start
3middleware-2-end
4Get 2
5middleware-1-end

要想理解 Koa 的洋葱模型，其实只需要知道 控制权移交 和 共享数据。

控制权移交，中间件一号开开心心的执行到 next，就委屈的把控制权移交给二号，二号高傲的开始执行，也碰到了 next，但是这个 next 直接 resolve（因为是最后一个中间件，具体请看后文分析），因此它可以继续做剩下的事情，在完成后再把控制权还给一号，一号再可怜兮兮的做自己的事情。思考，是怎么做到自己的事情做完后归还控制权的？
共享数据，在这里二号中间件为 ctx.state 上挂载了一个新的属性，在它交还控制权后一号中间件能拿到这个属性。

我们直接来看源码中的实现

1use(fn) {
2    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!');
3    if (isGeneratorFunction(fn)) {
4      deprecate('Support for generators will be removed in v3. ' +
5                'See the documentation for examples of how to convert old middleware ' +
6                'https://github.com/koajs/koa/blob/master/docs/migration.md');
7      fn = convert(fn);
8    }
9    this.middleware.push(fn);
10    return this;
11  }

convert()方法能够将 generator 函数转为中间件可用的函数结构。

1declare function convert(
2  mw: (context: Context, next: Next) => Generator
3): Middleware;

然后将每一次 app.use，都有一个中间件被 push 进middleware，然后在callback方法中

1callback() {
2    // 洋葱模型实现关键
3    const fn = compose(this.middleware);
4
5    const handleRequest = (req, res) => {
6      const ctx = this.createContext(req, res);
7      return this.handleRequest(ctx, fn);
8    };
9
10    return handleRequest;
11  }
12
13  handleRequest(ctx, fnMiddleware) {
14    const res = ctx.res;
15    const onerror = err => ctx.onerror(err);
16    const handleResponse = () => respond(ctx);
17    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
18  }

compose 方法将中间件合并为一个函数，并且确保 ctx 在接受所有中间件处理后才会去处理响应。

compose 方法来自于koa-compose，是我们接下来要展开来讲的重点。在这里我直接给出全部源码，你可以先试着自己琢磨一下。

1function compose(middleware) {
2  // 处理异常情况代码省略
3  return function (context, next) {
4    // last called middleware #
5    let index = -1;
6    return dispatch(0);
7
8    function dispatch(i) {
9      if (i <= index)
10        return Promise.reject(new Error("next() called multiple times"));
11      index = i;
12      let fn = middleware[i];
13      if (i === middleware.length) fn = next;
14      if (!fn) return Promise.resolve();
15      try {
16        return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
17      } catch (err) {
18        return Promise.reject(err);
19      }
20    }
21  };
22}

光是讲解逻辑多没意思，我们再回到上面的一号二号中间件的例子。

compose函数接收中间件数组，开始分发一号中间件，即 dispatch(0)。
dispatch(0)内部，此时 fn 为一号中间件，会走到 try/catch 块，尝试执行Promise.resolve(fn(context, dispatch.bind(null, i + 1)))，即一号中间件此时获得入参context、dispatch(1)。
一号中间件开始执行，遇到 next()（即 middleware2()），控制权移交，执行 dispatch(1)，此时二号中间件获得入参context、dispatch(2)。
二号中间件开始执行，执行到await next()时，再重复上述逻辑，dispatch(2)，但是这一次会停在这里：
```
1let fn = middleware[i];
2if (i === middleware.length) fn = next;
3if (!fn) return Promise.resolve();
```
fn = next，这里的 next 由于并没有值，所以会直接 return 一个立即 resolve 的 Promise。也就是说二号中间件内部的 await next()会立刻返回。
二号中间件做完自己的事后，相当于一号中间件内部的await next()返回了，因此控制权就归还给一号中间件。

是不是还挺简单的？我尽量说的很细了...

完成了中间件，我们就该来梳理一下大致请求和响应是怎么走的了。

1callback() {
2    const fn = compose(this.middleware);
3
4    const handleRequest = (req, res) => {
5      const ctx = this.createContext(req, res);
6      return this.handleRequest(ctx, fn);
7    };
8
9    return handleRequest;
10  }
11
12  handleRequest(ctx, fnMiddleware) {
13    const res = ctx.res;
14
15    res.statusCode = 404;
16    const onerror = err => ctx.onerror(err);
17    const handleResponse = () => respond(ctx);
18    onFinished(res, onerror);
19
20    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
21  }
22
23  createContext(req, res) {
24    // ...处理context
25  }

接收到请求->
createContext 初步处理上下文->
handleRequest（实例方法那个）让 ctx 经过中间件的洗礼->
过了就 handleResponse->
没过就触发错误

这次的代码多放了几个地方，你可能会觉得有点诡异:

1res.statusCode = 404;

这玩意是啥意思？

不知道你在 koa 使用初期有没有遇见过这样的问题，明明接口能跑通啊，路由里的 log 也能打出来，为啥子就是 404？通常最后你会发现，因为你忘记 koa.body 了...

这句代码的意思就是你没有设置 body 时的默认状态码，koa 内部还使用了一个 respond 函数来处理各种各样的 ctx.body。

1/ 处理流/件文 / blabla响应;
2function respond(ctx) {
3  // allow bypassing koa
4  // 允许绕过koa来进行响应
5  if (false === ctx.respond) return;
6
7  if (!ctx.writable) return;
8
9  const res = ctx.res;
10  let body = ctx.body;
11  const code = ctx.status;
12
13  // ignore body
14  if (statuses.empty[code]) {
15    // strip headers
16    ctx.body = null;
17    return res.end();
18  }
19
20  if ("HEAD" === ctx.method) {
21    if (!res.headersSent && !ctx.response.has("Content-Length")) {
22      const { length } = ctx.response;
23      if (Number.isInteger(length)) ctx.length = length;
24    }
25    return res.end();
26  }
27
28  // status body
29  if (null == body) {
30    if (ctx.req.httpVersionMajor >= 2) {
31      body = String(code);
32    } else {
33      body = ctx.message || String(code);
34    }
35    if (!res.headersSent) {
36      ctx.type = "text";
37      ctx.length = Buffer.byteLength(body);
38    }
39    return res.end(body);
40  }
41
42  // responses
43  if (Buffer.isBuffer(body)) return res.end(body);
44  if ("string" == typeof body) return res.end(body);
45  if (body instanceof Stream) return body.pipe(res);
46
47  // body: json
48  body = JSON.stringify(body);
49  if (!res.headersSent) {
50    ctx.length = Buffer.byteLength(body);
51  }
52  res.end(body);
53}

这个函数主要做了这么几件事

如果你没有设置 ctx.body，那么它就是 404；
如果你设置了值，那么就是 200；
- body 为 Buffer/string/Stream 的情况，它也会帮你处理。比如对流会使用管道。
```
1if (body instanceof Stream) return body.pipe(res);
```
- 如果是其他，那么它会转为 JSON 形式返回。

1onFinished(res, onerror);

这又是啥？

这是一个第三方 npm 包，由于上一步我们可能会处理流式数据，因此需要用到这个包在流完成/关闭/出错时执行响应回调函数。

错误处理，妥妥的！

由于开发者们通常码代码姿势千奇百怪，因此良好的错误处理机制也少不了。我们可以先看看 Koa 中哪些地方做了错误处理。

这里的错误处理不包括异常处理，如为中间件传入非函数会抛出错误的情况。

1// Application.js
2callback() {
3    if (!this.listenerCount('error')) this.on('error', this.onerror);
4    // ...
5  }
6
7  handleRequest(ctx, fnMiddleware) {
8    const onerror = err => ctx.onerror(err);
9    const handleResponse = () => respond(ctx);
10    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
11  }
12
13 onerror(err) {
14    if (!(err instanceof Error)) throw new TypeError(util.format('non-error thrown: %j', err));
15
16    if (404 == err.status || err.expose) return;
17    if (this.silent) return;
18
19    const msg = err.stack || err.toString();
20    console.error();
21    console.error(msg.replace(/^/gm, '  '));
22    console.error();
23  }
24
25// context.js
26 onerror(err) {
27    // don't do anything if there is no error.
28    // this allows you to pass `this.onerror`
29    // to node-style callbacks.
30    if (null == err) return;
31
32    if (!(err instanceof Error)) err = new Error(util.format('non-error thrown: %j', err));
33
34    let headerSent = false;
35    if (this.headerSent || !this.writable) {
36      headerSent = err.headerSent = true;
37    }
38
39    // delegate
40    this.app.emit('error', err, this);
41
42    // nothing we can do here other
43    // than delegate to the app-level
44    // handler and log.
45    if (headerSent) {
46      return;
47    }
48
49    const { res } = this;
50
51    // first unset all headers
52    /* istanbul ignore else */
53    if (typeof res.getHeaderNames === 'function') {
54      res.getHeaderNames().forEach(name => res.removeHeader(name));
55    } else {
56      res._headers = {}; // Node < 7.7
57    }
58
59    // then set those specified
60    this.set(err.headers);
61
62    // force text/plain
63    this.type = 'text';
64
65    // ENOENT support
66    if ('ENOENT' == err.code) err.status = 404;
67
68    // default to 500
69    if ('number' != typeof err.status || !statuses[err.status]) err.status = 500;
70
71    // respond
72    const code = statuses[err.status];
73    const msg = err.expose ? err.message : code;
74    this.status = err.status;
75    this.length = Buffer.byteLength(msg);
76    res.end(msg);
77  },

首先要明确一点，Application 这个类实际上继承于 EventEmitter 类。

在callback中，会新建唯一的一个错误监听器（确保 error 事件的监听器为 0 时才会新建）。

看handleRequest的部分，可以看到实际上请求过程中的错误交给了context.js中的 onerror 处理，在 context.js 的 onerror 中，this.app.emit('error', err, this)这行代码将错误移交给app-level来处理、打印信息。如果这个请求处理竟然还没结束，即实例中的 onerror 事件没有使整个进程退出，那么 context.js 的 onerror 会尝试抛出一个 500 错误。

关于错误处理，实际上我自己用的最多的还是使用最外层中间件统一捕获错误并处理。当然由于 Koa 的高度定制性，你也可以覆盖 ctx.onerror 或者直接监听 app 的 error 事件来处理错误。

总结

说实话写文章真的还挺累人的...，尤其是有的时候你感觉自己懂了但是一写才发现自己懂个 🔨。但不管怎么样好歹是不怎么灌水的写完了在掘金的第一篇文章，才疏学浅，难免会有错误，还请在 GitHub Issue 指出，感激不尽。