Node.js躬行记（19）——KOA源码分析（上）

　　本次分析的KOA版本是2.13.1，它非常轻量，诸如路由、模板等功能默认都不提供，需要自己引入相关的中间件。

　　源码的目录结构比较简单，主要分为3部分，__tests__，lib和docs，从名称中就可以了解到。

　　__tests__是单元测试，lib是核心代码，docs是文档。在lib目录中只有4个文件。

├── __tests__ ------------------------ 单元测试├── docs ----------------------------- 文档├── lib ------------------------------ 源码目录│   ├── application.js --------------- 运行│   ├── context.js ------------------- 上下文│   ├── request.js ------------------- 请求│   ├── response.js ------------------ 响应

　　阅读源码除了能学到不经常使用的概念之外，还能学到各种软件开发思路，见识到各种类型的第三方库，对于提升自己的日常编码很有帮助。

一、package.json

　　在package.json文件中，可以看到KOA的入口是 application.js。

"main": "lib/application.js",

　　在devDependencies中，依赖的是ESLint和单元测试库。

　　在dependencies中，好几个都是与通信有关的库，还有几个工具库，具体包括：

• accepts：为给定的 req 创建一个新的 Accepts 对象。
• cache-content-type：与 mime-types 的 contentType 方法相同，但缓存了结果。
• content-disposition：创建和解析 HTTP Content-Disposition 头。
• content-type：根据 RFC 7231 创建和解析 HTTP Content-Type 头。
• cookies：一个用于获取和设置 HTTP(S) cookie 的 node.js 模块。
• debug：一个模仿 Node.js 核心调试技术的小型 JavaScript 调试实用程序。
• delegates：创建一个委托实例，让一个对象可以直接访问其属性对象的属性和方法（在下一篇中会详细说明）。
• destroy：销毁一个流，确保流被销毁，处理不同的 API 和 Node.js 错误。
• encodeurl：将 URL 编码为百分比编码形式，不包括已编码的序列。
• escape-html：将特殊字符转换成HTML实体。例如 foo & bar =》foo & bar。
• fresh：HTTP 响应新鲜度测试。
• http-assert：状态码断言，像 Koa 中的 ctx.throw() 一样，但是有一个守卫。
• http-errors：为 Express、Koa、Connect 等创建 HTTP 错误。
• koa-compose：组合给定的中间件，KOA的插件。
• on-finished：当 HTTP 请求关闭、完成或出错时执行回调。
• only：指定属性白名单，然后只返回这几个属性。
• parseurl：解析给定请求对象的 URL（req.url 属性）并返回结果，结果与 url.parse 相同。在 req.url 不变的同一个 req 上多次调用此函数将返回一个缓存的解析对象。
• statuses：返回已知 HTTP 状态代码的状态消息字符串。
• type-is：检查请求的内容类型是否是 content-type 中的一种类型。
• vary：将给定的头字段添加到 res 的 Vary 响应头中。

二、application.js

　　application.js是KOA的入口文件，在此文件中，会引入lib目录的另外3个文件，以及多个依赖库。

const debug = require('debug')('koa:application')const onFinished = require('on-finished')const response = require('./response')const compose = require('koa-compose')const context = require('./context')const request = require('./request')const statuses = require('statuses')const Emitter = require('events')const util = require('util')const Stream = require('stream')const http = require('http')const only = require('only')const { HttpError } = require('http-errors')

　　在下面的代码中，去掉了大部分的方法体，只留下了方法名和注释。其中Application继承自Emitter，这样就能监听和触发自定义事件了。

/** * 继承自 Emitter.prototype */module.exports = class Application extends Emitter {  constructor (options) { }  /**   * 简写：   *    http.createServer(app.callback()).listen(...)   */  listen (...args) { }  /**   * JSON格式化   */  toJSON () { return only(this, ['subdomainOffset', 'proxy', 'env']) }  /**   * Inspect implementation.   */  inspect () { return this.toJSON() }  /**   * 使用给定的中间件 fn   */  use (fn) { }  /**   * 请求处理程序回调，用于本机 http 服务器   */  callback () { }  /**   * 在回调中处理请求   */  handleRequest (ctx, fnMiddleware) { }  /**   * 初始化一个新的上下文   */  createContext (req, res) { }  /**   * 默认错误处理程序   */  onerror (err) { }  /**   * 帮助 TS 用户遵守 CommonJS、ESM、bundler mismatch   * @see https://github.com/koajs/koa/issues/1513   */  static get default () { return Application }}/** * 响应助手 */function respond (ctx) { }/** * 使库的消费者可以使用 HttpError，这样消费者就不会直接依赖于 `http-errors` */module.exports.HttpError = HttpError

　　在看过源码后，再来阅读一段简单的demo，在初始化KOA实例后，调用了Application的 use() 和 listen() 两个方法。

const Koa = require("koa");const app = new Koa();app.use(async (ctx, next) => {  ctx.body = "hello，KOA";});app.listen(3000);

1）构造函数

　　在构造函数中，会声明各种参数，包括代理信息、环境变量等。

　　其中Object.create()用于创建一个新对象，带着指定的原型对象和属性。

　　因为在同一个应用中可能会有多个KOA实例，所以为了防止相互污染，通过Object.create()的拷贝将他们不再引用同一个地址。

  constructor (options) {    super()    options = options || {} // 参数    this.proxy = options.proxy || false// 是否代码模式    this.subdomainOffset = options.subdomainOffset || 2    this.proxyIpHeader = options.proxyIpHeader || 'X-Forwarded-For' // 代理 IP 头，默认为 X-Forwarded-For    this.maxIpsCount = options.maxIpsCount || 0 // 从代理 IP 标头读取的最大 IP，默认为 0（表示无穷大）    this.env = options.env || process.env.NODE_ENV || 'development' // 环境变量    if (options.keys) this.keys = options.keys    this.middleware = []    this.context = Object.create(context) // 创建一个新的context    this.request = Object.create(request)// 创建一个新的request    this.response = Object.create(response)// 创建一个新的response    // util.inspect.custom support for node 6+    /* istanbul ignore else */    if (util.inspect.custom) {      this[util.inspect.custom] = this.inspect    }  }

2）use()

　　在KOA实例中，会维护一个中间件数组（middleware），在添加fn之前，会利用typeof判断其是否是函数类型。

  use (fn) {    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!')    this.middleware.push(fn)    return this  }

　　KOA的中间件采用的是著名的洋葱模型，后面会细说。

3）listen()

　　listen()内部直接调用http.createServer()创建一个server，监听指定端口，并且每个请求都会回调当前实例的callback()方法。

  listen (...args) {    const server = http.createServer(this.callback())    return server.listen(...args)  }

　　在callback()方法中，会调用洋葱模型的compose()函数，监听error事件（回调error()函数），最后处理请求调用handleRequest()方法。

  callback () {    // 包装所有的中间件，返回一个可执行函数，compose()是洋葱模型的实现    const fn = compose(this.middleware)    // 若未指定error事件，那么创建error事件监听器    if (!this.listenerCount('error')) {      this.on('error', this.onerror)    }    const handleRequest = (req, res) => {      // 为ctx包装Node原生的req和res，并且每个请求都是单独的ctx      const ctx = this.createContext(req, res)      // 实例的handleRequest()，并不是递归      return this.handleRequest(ctx, fn)    }    return handleRequest  }

4）compose()

　　中间件通常用于完成一些全局的特定功能，例如权限验证、错误处理、日志添加等。

　　下面是一个简单的中间件示例，用于处理500响应。

export default () => async (ctx, next) => {  try {    await next();  } catch (error) {    ctx.status = 500;    ctx.body = { error: String(error), stack: error.stack };  }};

　　compose()引用自koa-compose库，在该库中，中间件会被next()函数分成两部分，先执行next()之前的部分，在请求处理完毕后，再执行next()后面的部分。

　　下图是官方给的一张中间件执行顺序示意图。

　　

　　在下图中，每一层相当于是一个中间件，在request时，处理的是next()的前半部分，在response时，处理的是其后半部分。

　　

　　下面就是koa-compose库的所有代码，已加注释，为了便于理解，我已经将可执行的代码放到codepen中，在线调试。

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!')  }  /**  * 返回一个函数  * context就是ctx  * next()函数就是下一个中间件函数  */  return function (context, next) {    // 上一个中间件的索引    let index = -1    // 启动dispatch()函数，初始值是0    return dispatch(0)    function dispatch (i) {      // 以免在一个中间件内，调用多次next()      if (i <= index) return Promise.reject(new Error('next() called multiple times'))      index = i      // fn就是中间件函数      let fn = middleware[i]      // 中间件都已执行过一次，fn是undefined      if (i === middleware.length) fn = next      // 终止递归      if (!fn) return Promise.resolve()      try {        // fn是中间件，dispatch()就是下一个中间件的next()函数        return Promise.resolve(fn(context, dispatch.bind(null, i + 1)))      } catch (err) {        return Promise.reject(err)      }    }  }}

　　函数分为几步：

• 第一步是检查中间件数组和中间件的类型。
• 第二步是返回一个函数，参数是 ctx 和 next()，其中 next() 就是下一个中间件函数。
• 第三步是调用 dispatch(0) 启动中间件的运行，并且在一个中间件中，不允许多次调用 next() 函数。
• 第四步是递归地依次为每一个要执行的中间件传递参数，其第二个参数是下一个 dispatch() 函数。

　　递归过程中的 dispatch() 其实就是中间件中的 next() 函数。

　　Promise.resolve(fn(context, dispatch.bind(null, i + 1))) 会先运行一次中间件，然后遇到 next()，就去运行下一个中间件，递归终止后，再回溯处理中间件余下的逻辑。

5）createContext()

　　每次HTTP请求都生成一个新的context，与其他请求中的context之间相互隔离。

  createContext (req, res) {    // 每次HTTP请求都生成一个新的context    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    // 挂载Node原生的req和res    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    // 可自定义的状态，例如koa-jwt库就使用了该属性    context.state = {}    return context  }

　　context具备高内聚的特征，因为它能访问KOA提供的所有数据和方法。

　　并且还预留了一个state属性，可用于传递自定义的状态值。

6）handleRequest()

　　在 handleRequest() 函数中，会运行中间件函数，以及处理响应的不同情况。

  /**   * 在回调中处理请求   * @param {*} ctx 上下文   * @param {*} fnMiddleware 可执行的中间件函数   * @returns   */  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()函数内容比较多，包括为格式化JSON格式的body，流类型的body调用pipe()，为HEAD请求加 Content-Length 头等。

　　官方也提供了属性，来绕开上述这些处理。

function respond (ctx) {  // 允许绕过KOA的处理  if (ctx.respond === false) return  if (!ctx.writable) return  const res = ctx.res  let body = ctx.body  const code = ctx.status  // code不是已知的状态码  if (statuses.empty[code]) {    // strip headers    ctx.body = null    return res.end()  }  // HEAD请求  if (ctx.method === 'HEAD') {    // 加Content-Lengthh头    if (!res.headersSent && !ctx.response.has('Content-Length')) {      const { length } = ctx.response      if (Number.isInteger(length)) ctx.length = length    }    return res.end()  }  // status body  if (body == null) {    if (ctx.response._explicitNullBody) {      ctx.response.remove('Content-Type')      ctx.response.remove('Transfer-Encoding')      ctx.length = 0      return res.end()    }    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)  }  // 对body的三种类型采用不同的处理  if (Buffer.isBuffer(body)) return res.end(body)  if (typeof body === 'string') return res.end(body)  if (body instanceof Stream) return body.pipe(res)  // JSON格式的body  body = JSON.stringify(body)  if (!res.headersSent) {    ctx.length = Buffer.byteLength(body)  }  res.end(body)}

 

 

参考资料：

koa源码解析

高质量 - Koa 源码解析

超级详细的koa源码解析