深入koa2源码

koa是当下非常流行的node框架，相比笨重的express，koa只专注于中间件模型的建立，以及请求和响应控制权的转移。本文将以koa2为例，深入源码分析框架的实现细节。 koa2的源码位于lib目录，结构非常简单和清晰，只有四个文件，如下：

根据package.json中的main字段，可以知道入口文件是lib/application.js,application.js定义了koa的构造函数以及实例拥有的方法，如下图：

构造函数

首先看一下构造函数的代码

 constructor() {
    super();
    this.proxy = false;
    this.middleware = [];
    this.subdomainOffset = 2;
    this.env = process.env.NODE_ENV || 'development';
    this.context = Object.create(context);
    this.request = Object.create(request);
    this.response = Object.create(response);
    if (util.inspect.custom) {
      this[util.inspect.custom] = this.inspect;
    }
  }
复制代码

这里定义了实例的8个属性，各自的含义如下：

use()

use方法很简单，接受一个函数作为参数，并加入middleware数组。由于koa最开始支持使用generator函数作为中间件使用，但将在3.x的版本中放弃这项支持，因此koa2中对于使用generator函数作为中间件的行为给与未来将被废弃的警告，但会将generator函数转化为async函数。返回this便于链式调用。

use(fn) {
    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!');
    if (isGeneratorFunction(fn)) {
      deprecate('Support for generators will be removed in v3. ' +
                'See the documentation for examples of how to convert old middleware ' +
                'https://github.com/koajs/koa/blob/master/docs/migration.md');
      fn = convert(fn);
    }
    debug('use %s', fn._name || fn.name || '-');
    this.middleware.push(fn);
    return this;
  }
复制代码

listen()

下面是listen方法,可以看到内部是通过原生的http模块创建服务器并监听的，请求的回调函数是callback函数的返回值。

  listen(...args) {
    debug('listen');
    const server = http.createServer(this.callback());
    return server.listen(...args);
  }
复制代码

callback()

下面是callback的代码，compose函数将中间件数组转换成执行链函数fn， compose的实现是重点，下文会分析。koa继承自Emitter,因此可以通过listenerCount属性判断监听了多少个error事件， 如果外部没有进行监听，框架将自动监听一个error事件。callback函数返回一个handleRequest函数，因此真正的请求处理回调函数是handleRequest。在handleRequest函数内部，通过createContext创建了上下文ctx，并交给koa实例的handleRequest方法去处理回调逻辑。

callback() {
    const fn = compose(this.middleware);

    if (!this.listenerCount('error')) this.on('error', this.onerror);

    const handleRequest = (req, res) => {
      const ctx = this.createContext(req, res);
      return this.handleRequest(ctx, fn);
    };

    return handleRequest;
  }
复制代码

createContext()

createContext(req, res) {
    const context = Object.create(this.context);
    const request = context.request = Object.create(this.request);
    const response = context.response = Object.create(this.response);
    context.app = request.app = response.app = this;
    context.req = request.req = response.req = req;
    context.res = request.res = response.res = res;
    request.ctx = response.ctx = context;
    request.response = response;
    response.request = request;
    context.originalUrl = request.originalUrl = req.url;
    context.state = {};
    return context;
}
复制代码

上面是createContext的代码， 从这里我们可以知道，通过ctx.req和ctx.res可以访问到node原生的请求对象和响应对象， 通过修改ctx.state可以让中间件共享状态。可以用一张图描述这个函数中定义的关系，如下：

接下来我们分析细节，this.context、this.request、this.response分别通过context、request、response三个对象的原型创建， 我们先看一下request的定义，它位于request.js文件中。

request.js

request.js定义了ctx.request的原型对象的原型对象，因此该对象的任意属性都可以通过ctx.request获取。这个对象一共有20多个属性和若干方法。其中属性多数都定义了get和set方法，截取一小部分代码如下：

module.exports = {
 get header() {
    return this.req.headers;
 },
 set header(val) {
    this.req.headers = val;
 },
 ...
}

复制代码

上面代码中定义了header属性，根据前面的关系图可知，this.req指向的是原生的req，因此ctx.request.header等于原生req的headers属性,修改ctx.request.header就是修改req的headers。request对象中所有的属性和方法列举如下：

response.js

response.js定义了ctx.response的原型对象的原型对象，因此该对象的任意属性都可以通过ctx.response获取。和request类似，response的属性多数也定义了get和set方法。response的属性和方法如下：

request和response中每个属性get和set的定义以及方法的实现多数比较简单直观，如果对每个进行单独分析会导致篇幅过长，而且这些不是理解koa运行机制的核心所在，因此本文只罗列属性和方法的用途，这些大部分也可以在koa的官方文档中找到。关心细节的朋友可以直接阅读request.js和response.js这两个文件,如果你熟悉http协议，相信这些代码对你并没有障碍。接下来我们的重点是context.js。

context.js

context.js定义了ctx的原型对象的原型对象, 因此这个对象中所有属性都可以通过ctx访问到。context.js中除了定义[util.inspect.custom]这个不是很重要的属性外,只直接定义了一个属性cookies，也定义了几个方法，这里分别进行介绍：

cookies

  get cookies() {
    if (!this[COOKIES]) {
      this[COOKIES] = new Cookies(this.req, this.res, {
        keys: this.app.keys,
        secure: this.request.secure
      });
    }
    return this[COOKIES];
  },

  set cookies(_cookies) {
    this[COOKIES] = _cookies;
  }
复制代码

上面的代码中定义了cookies属性的set和get方法。set方法很简单，COOKIES是一个Symbol类型的私有变量。需要注意的是我们一般不通过ctx.cookies来直接设置cookies，官方文档推荐使用ctx.cookies.set(name, value, options)来设置，可是这里并没有cookies.set呀，其实这里稍微一看就明白，cookies的值是this[COOKIES]，它是Cookies的一个实例，在Cookie这个npm包中是定义了实例的get和set方法的。

throw()

 throw(...args) {
    throw createError(...args);
  },
复制代码

当我们调用ctx.throw抛出一个错误时，内部是抛出了一个有状态码和信息的错误，createError的实现在http-errors这个npm包中。

onerror()

下面是onerror方法的代码,发生错误时首先会触发koa实例上的error事件来打印一个错误日志, headerSent变量表示响应头是否发送，如果响应头已经发送，或者响应处于不可写状态，将无法在响应中添加错误信息，直接退出该函数，否则需要将之前写入的响应头部信息清空。

onerror(err) {
    // 没有错误时什么也不做
    if (null == err) return;
    // err不是Error实例时，使用err创建一个Error实例
    if (!(err instanceof Error)) err = new Error(util.format('non-error thrown: %j', err));

    let headerSent = false;
    // 如果res不可写或者请求头已发出
    if (this.headerSent || !this.writable) {
      headerSent = err.headerSent = true;
    }

    // 触发koa实例app的error事件
    this.app.emit('error', err, this);

    if (headerSent) {
      return;
    }

    const { res } = this;

    // 移除所有设置过的响应头
    if (typeof res.getHeaderNames === 'function') {
      res.getHeaderNames().forEach(name => res.removeHeader(name));
    } else {
      res._headers = {}; // Node < 7.7
    }

    // 设置错误头部
    this.set(err.headers);

    // 设置错误时的Content-Type
    this.type = 'text';

    // 找不到文件错误码设为404
    if ('ENOENT' == err.code) err.status = 404;

    // 不能被识别的错误将错误码设为500
    if ('number' != typeof err.status || !statuses[err.status]) err.status = 500;

    const code = statuses[err.status];
    const msg = err.expose ? err.message : code;
    // 设置错误码
    this.status = err.status;
    this.length = Buffer.byteLength(msg);
    // 结束响应
    res.end(msg);
  },
复制代码

从上面代码中会有疑问， this.set、this.type等是哪里来的？context并没有定义这些属性。我们知道， ctx中其实是代理了很多response和resquest的属性和方法的，this.set、this.type其实就是response.set和response.type。那么koa中对象属性和方法的代理是如何实现的呢，答案是delegate,context中代码的最后就是使用delegate来代理一些本来只存在于request和response上的属性。接下来我们看一下delegete是如何实现代理的，delegete的实现代码在delegetes这个npm包中。

delegate

delegate方法本质上是一个构造函数，接受两个参数，第一个参数是代理对象，第二个参数是被代理的对象，下面是它的定义, Delegator就是delegate。可以看到，不管是否使用new关键字，该函数总是会返回一个实例。

function Delegator(proto, target) {
  if (!(this instanceof Delegator)) return new Delegator(proto, target);
  this.proto = proto;
  this.target = target;
  this.methods = [];
  this.getters = [];
  this.setters = [];
  this.fluents = [];
}
复制代码

此外，在Delegator构造函数的原型上，定义了几个方法，koa中用到了Delegator.prototype.method、Delegator.prototype.accsess以及Delegator.prototype.getter,这些都是代理方法， 分别代理set 和get方法。下面是代码，其中get和set方法的代理主要使用了对象的__defineGetter__以及__defineSetter__方法。

Delegator.prototype.method = function(name){
  var proto = this.proto;
  var target = this.target;
  this.methods.push(name);

  proto[name] = function(){
    return this[target][name].apply(this[target], arguments);
  };

  return this;
};
Delegator.prototype.access = function(name){
  return this.getter(name).setter(name);
};
Delegator.prototype.getter = function(name){
  var proto = this.proto;
  var target = this.target;
  this.getters.push(name);

  proto.__defineGetter__(name, function(){
    return this[target][name];
  });

  return this;
};
Delegator.prototype.setter = function(name){
  var proto = this.proto;
  var target = this.target;
  this.setters.push(name);

  proto.__defineSetter__(name, function(val){
    return this[target][name] = val;
  });

  return this;
};
复制代码

到这里，关于request、response和context就聊的差不多了，接下来回到callback继续我们的重点，前面说到的compose才是koa的精华和核心所在，他的代码在koa-compose这个包中，我们来看一下：

compose

function compose (middleware) {
  if (!Array.isArray(middleware)) throw new TypeError('Middleware stack must be an array!')
  for (const fn of middleware) {
    if (typeof fn !== 'function') throw new TypeError('Middleware must be composed of functions!')
  }

  return function (context, next) {
    // last called middleware #
    let index = -1
    return dispatch(0)
    function dispatch (i) {
      if (i <= index) return Promise.reject(new Error('next() called multiple times'))
      index = i
      let fn = middleware[i]
      if (i === middleware.length) fn = next
      if (!fn) return Promise.resolve()
      try {
        return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
      } catch (err) {
        return Promise.reject(err)
      }
    }
  }
}
复制代码

函数接收一个middleware数组为参数，返回一个函数，给函数传入ctx时第一个中间件将自动执行，以后的中间件只有在手动调用next，即dispatch时才会执行。另外从代码中可以看出，中间件的执行是异步的，并且中间件执行完毕后返回的是一个Promise，每个dispatch的返回值也是一个Promise，因此我们的中间件中可以方便地使用async函数进行定义，内部使用await next()调用“下游”，然后控制流回“上游”，这是更准确也更友好的中间件模型。从下面的代码可以看到，中间件顺利执行完毕后将执行respond函数，失败后将执行ctx的onerror函数。onFinished(res, onerror)这段代码是对响应处理过程中的错误监听，即handleResponse发生的错误或自定义的响应处理中发生的错误。

  handleRequest(ctx, fnMiddleware) {
    const res = ctx.res;
    res.statusCode = 404;
    const onerror = err => ctx.onerror(err);
    const handleResponse = () => respond(ctx);
    onFinished(res, onerror);
    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
  }
复制代码

respond

respond是koa内置的响应自动处理函数，代码如下，它主要功能是判断ctx.body的类型，然后自动完成最后的响应。另外，如果在koa中需要自行处理响应，可以设置ctx.respond = false，这样内置的respond就会被忽略。

function respond(ctx) {
  // allow bypassing koa
  if (false === ctx.respond) return;

  const res = ctx.res;
  if (!ctx.writable) return;

  let body = ctx.body;
  const code = ctx.status;

  // ignore body
  if (statuses.empty[code]) {
    // strip headers
    ctx.body = null;
    return res.end();
  }

  if ('HEAD' == ctx.method) {
    if (!res.headersSent && isJSON(body)) {
      ctx.length = Buffer.byteLength(JSON.stringify(body));
    }
    return res.end();
  }

  // status body
  if (null == body) {
    if (ctx.req.httpVersionMajor >= 2) {
      body = String(code);
    } else {
      body = ctx.message || String(code);
    }
    if (!res.headersSent) {
      ctx.type = 'text';
      ctx.length = Buffer.byteLength(body);
    }
    return res.end(body);
  }

  // responses
  if (Buffer.isBuffer(body)) return res.end(body);
  if ('string' == typeof body) return res.end(body);
  if (body instanceof Stream) return body.pipe(res);

  // body: json
  body = JSON.stringify(body);
  if (!res.headersSent) {
    ctx.length = Buffer.byteLength(body);
  }
  res.end(body);
}
复制代码