Koa 源码解析

┌─────────────────────────────────────────────────┐
│                   Koa Application                │
│  ┌───────────────────────────────────────────┐  │
│  │              Middleware Stack              │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │   Middleware 1 (async)              │  │  │
│  │  │   ┌─────────────────────────────┐  │  │  │
│  │  │   │   Middleware 2 (async)      │  │  │  │
│  │  │   │   ┌─────────────────────┐  │  │  │  │
│  │  │   │   │   Middleware 3      │  │  │  │  │
│  │  │   │   │   await next()      │  │  │  │  │
│  │  │   │   └─────────────────────┘  │  │  │  │
│  │  │   └─────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────┘  │
│                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
│  │ Application │  │   Context   │  │ Request  │ │
│  │             │◄─┤   (ctx)     │◄─┤ Response │ │
│  │             │  │             │  │          │ │
│  └─────────────┘  └─────────────┘  └──────────┘ │
│         ▲                                      │
│         │                                      │
│  ┌──────┴──────┐                              │
│  │ Node.js HTTP│                              │
│  │   Server    │                              │
│  └─────────────┘                              │
└─────────────────────────────────────────────────┘

HTTP Request
    │
    ├─→ http.createServer()
    │
    ├─→ Application.callback()
    │       │
    │       ├─→ compose(middleware)
    │       │
    │       └─→ createContext(req, res)
    │
    ├─→ Middleware Execution (洋葱模型)
    │       │
    │       ├─→ Middleware 1 (before next)
    │       ├─→ Middleware 2 (before next)
    │       ├─→ Middleware N (core logic)
    │       ├─→ Middleware 2 (after next)
    │       └─→ Middleware 1 (after next)
    │
    ├─→ respond(ctx)
    │
    └─→ HTTP Response

git clone https://github.com/koajs/koa.git
cd koa
git checkout v2.13.1

koa/
├── lib/                    # 核心源码
│   ├── application.js      # 应用核心 (~400 行)
│   ├── context.js          # 上下文对象 (~300 行)
│   ├── request.js          # 请求封装 (~500 行)
│   └── response.js         # 响应封装 (~400 行)
├── test/                   # 测试文件
├── docs/                   # 文档
├── benchmarks/             # 性能基准测试
└── package.json           # 项目配置

application.js
    ├── context.js (委托机制)
    │     ├── request.js
    │     └── response.js
    ├── koa-compose (中间件组合)
    ├── koa-convert (Generator 转换)
    ├── delegates (属性委托)
    ├── http-errors (错误处理)
    └── cookies (Cookie 管理)

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200);
  res.end('hello world');
});

server.listen(4000, () => {
  console.log('server start at 4000');
});

const Koa = require('koa')
const app = new Koa()

app.listen(4000, () => {
  console.log('server is running, port is 4000')
})

// lib/application.js
module.exports = class Application extends Emitter {

  listen(...args) {
    // Debug 调试代码, 可以先忽略
    debug('listen');
    // 这里是用的 HTTP 模块创建服务
    const server = http.createServer(this.callback());
    return server.listen(...args);
  }

  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);
    };
    // 这里返回一个回调函数, 该回调函数对应 HTTP 模块中的 createServer()方法中的回调函数参数
    return handleRequest;
  }

  // 处理 request 逻辑
  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);
  }
};

// lib/application.js
module.exports = class Application extends Emitter {

  constructor(options) {
    super();
    // 省略部分代码
    this.middleware = [];
  }

  use(fn) {
    // 入参必须是函数  
    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!');

    // 目前版本是 2.x, 这里主要是兼容 1.x 版本中的 Generator 函数
    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');
      // 如果是 Generator 函数, 则将其转成 2.x 中的(ctx, next)=> {}格式
      fn = convert(fn);
    }
    debug('use %s', fn._name || fn.name || '-');
    this.middleware.push(fn);
    return this;
  }
};

// lib/application.js
const compose = require('koa-compose');

module.exports = class Application extends Emitter {
  // 省略部分代码
  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;
  }
};

// koa-compose 核心实现
module.exports = compose

function compose (middleware) {
  // 入参必须是数组
  if (!Array.isArray(middleware)) throw new TypeError('Middleware stack must be an array!')

  // 数组中的每一项, 必须是函数, 其实就是注册的中间件回调函数 (ctx. next) => {}
  for (const fn of middleware) {
    if (typeof fn !== 'function') throw new TypeError('Middleware must be composed of functions!')
  }

  // 返回闭包, 由此可知在 koa this.callback 中的函数后续一定会使用这个闭包传入过滤后的上下文
  return function (context, next) {
    // 最后回调 middleware 
    // 初始化中间件函数数组执行的下标值
    let index = -1
    // 返回递归执行的 Promise.resolve 去执行整个中间件数组, 从第一个开始
    return dispatch(0)
    function dispatch (i) {
      // 校验上次执行的下标索引不能大于本次执行的传入下标i, 如果大于, 可能是下个中间件执行了多次导致的
      if (i <= index) return Promise.reject(new Error('next() called multiple times'))

      index = i

      // 获取当前的中间件函数
      let fn = middleware[i]

      // 如果当前执行下标等于中间件长度, 表示已经执行完毕了, 返回 Promise.resolve() 即可
      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)
      }
    }
  }
}

const Koa = require('koa');
const app = new Koa();

app.use((ctx, next) => {
  // 输出请求中的路径
  console.log(ctx.req.url);
  console.log(ctx.request.req.url);
  console.log(ctx.response.req.url);
  console.log(ctx.url);
  console.log(ctx.request.url);

  // 设置状态码和响应内容
  ctx.response.status = 200;
  ctx.body = 'Hello World';
});

app.listen(4000, () => {
  console.log('server is running, port is 4000')
})

// lib/application.js
module.exports = class Application extends Emitter {

  constructor(options) {
    super();
    // 省略部分代码

    // 3 个属性, 通过 Ojbect.create()方法分别继承 context、request、response
    this.context = Object.create(context);
    this.request = Object.create(request);
    this.response = Object.create(response);
  }

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

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

    const handleRequest = (req, res) => {
      // 这里创建了ctx对象
      const ctx = this.createContext(req, res);
      return this.handleRequest(ctx, fn);
    };

    return handleRequest;
  }

  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 中
    context.app = request.app = response.app = this;

    // 将 request 事件的 http.IncomingMessage 类挂载到 context.req 中
    context.req = request.req = response.req = req;
 
    // 将 request 事件的 http.ServerResponse 类挂载到 context.res 中
    context.res = request.res = response.res = res;

    // 互相挂载, 方便用户在 Koa 中通过 ctx 获取需要的信息
    request.ctx = response.ctx = context;
    request.response = response;
    response.request = request;
    context.originalUrl = request.originalUrl = req.url;
    context.state = {};
    return context;
  }
};

handleRequest(ctx, fnMiddleware) {
  const res = ctx.res;
  res.statusCode = 404;
  // 错误处理, 执行上下文中的 onerror() 方法
  const onerror = err => ctx.onerror(err);
  // 处理返回结果
  const handleResponse = () => respond(ctx);
  // 为 res 对象添加错误处理响应, 当 res 响应结束时, 执行上下文中的 onerror 函数
  onFinished(res, onerror);
  // 执行中间件数组中的所有函数, 在结束时调用 respond()函数
  return fnMiddleware(ctx).then(handleResponse).catch(onerror);
}

function respond(ctx) {
  // 允许跳过 Koa
  if (false === ctx.respond) return;

  // writable 是原生的 response 对象的可写入属性, 检查是否是可写流
  if (!ctx.writable) return;

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

  // 忽略 body。如果响应的 statusCode 是 body 为空的类型, 例如 204、205、304, 将 body 置为 null
  if (statuses.empty[code]) {
    ctx.body = null;
    return res.end();
  }

  if ('HEAD' === ctx.method) {
    // headersSent 属性是 Node 原生的 response 对象上的, 用于检查 HTTP 响应头是否已经被发送
    // 如果头未被发送, 并且响应头没有 Content-Length 属性, 那么添加 length 头
    if (!res.headersSent && !ctx.response.has('Content-Length')) {
      const { length } = ctx.response;
      if (Number.isInteger(length)) ctx.length = length;
    }
    return res.end();
  }

  // 如果 body 为 null
  if (null == body) {
    // 如果 response 对象上有 _explicitNullBody 属性。移除 Content-Type 和 Transfer-Encoding 响应头, 并返回结果
    if (ctx.response._explicitNullBody) {
      ctx.response.remove('Content-Type');
      ctx.response.remove('Transfer-Encoding');
      return res.end();
    }
    // 如果 HTTP 为 2+ 版本, 设置 body 为对应 HTTP 状态码; 否则先设置 body 为 ctx.message, 不存在时再设置为状态码
    if (ctx.req.httpVersionMajor >= 2) {
      body = String(code);
    } else {
      body = ctx.message || String(code);
    }
    // 如果 res.headersSent 不为真, 直接设置返回类型 ctx.type 为 text, ctx.length 为 Buffer.byteLength(body)
    if (!res.headersSent) {
      ctx.type = 'text';
      ctx.length = Buffer.byteLength(body);
    }
    return res.end(body);
  }

  // body 为 Buffer 或 String 时, 结束请求返回结果
  if (Buffer.isBuffer(body)) return res.end(body);
  if ('string' === typeof body) return res.end(body);

  // body 为 Stream 时, 开启管道 body.pipe(res)
  if (body instanceof Stream) return body.pipe(res);

  // body 为 JSON 类型时, 使用 JSON.stringify(body)转为字符串,并设置 ctx.length 后返回结果
  body = JSON.stringify(body);
  if (!res.headersSent) {
    ctx.length = Buffer.byteLength(body);
  }
  res.end(body);
}

callback() {
  const fn = compose(this.middleware);
  // 如果 application 中监听 error 事件的个数大于0, 则用自己的异常监听
  // 否则, 执行 Koa 默认的异常监听逻辑
  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;
}

onerror(err) {
  const isNativeError = Object.prototype.toString.call(err) === '[object Error]' || err instanceof Error;
  // 如果不是 NativeError, 则直接抛出异常
  if (!isNativeError) throw new TypeError(util.format('non-error thrown: %j', err));
  // err 状态码为 404 或 err.expose为true时, 不输出错误
  if (404 === err.status || err.expose) return;
  if (this.silent) return;

  // 直接输出错误栈到控制台
  const msg = err.stack || err.toString();
  console.error(`\n${msg.replace(/^/gm, '  ')}\n`);
}

const Koa = require('koa');
const app = new Koa();

app.use(async (ctx, next) => {
  setTimeout(() => {
    throw Error('这里出错了！')
  }, 1000)
  ctx.body= 'hello world';
});

app.listen(4000, () => {
  console.log('server is running, port is 4000')
})

process.on('uncaughtException', (error) => {
  console.log(error)
})

var delegate = require('delegates');

var obj = {};
obj.request = {
  name: 'xiaoye',
  age: 29,
  sex: 'man',
  say: function(){
    console.log('hello koa!');
  }
};

// 将obj.request的相关属性委托到obj上, 使调用更加简便
delegate(obj, 'request')
  .method('say')
  .getter('name')
  .setter('nickname')
  .access('age');

obj.say(); // hello koa!
obj.nickname = 'SKHon';
console.log('nickname: ', obj.request.nickname) // SKHon
console.log('现在年龄: ',obj.age) // 29
obj.age = 30;
console.log('明年年龄: ',obj.age) // 30

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.prototype.method = function(name){
  var proto = this.proto;
  var target = this.target;
  // 存入 methods 数组
  this.methods.push(name);

  // 以闭包的方式, 将对 proto 方法的调用转为对 this[target] 上相关方法的调用。apply 改变 this 的指向为 this[target]
  proto[name] = function(){
    return this[target][name].apply(this[target], arguments);
  };

  // 返回 delegator 实例对象, 从而实现链式调用
  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); // 将属性名称存入对应类型的数组

  // 利用__defineGetter__设置proto的getter
  // 使得访问proto[name]获取的是proto[target][name]的值
  proto.__defineGetter__(name, function(){
    return this[target][name];
  });
  // 返回 delegator 实例, 实现链式调用
  return this;
};

Delegator.prototype.setter = function(name){
  var proto = this.proto;
  var target = this.target;
  this.setters.push(name); // 将属性名称存入对应类型的数组

  // 利用__defineSetter__设置proto的setter
  // 实现给proto[name]赋值时, 实际改变的是proto[target][name]的值
  proto.__defineSetter__(name, function(val){
    return this[target][name] = val;
  });
  return this;
};

delegate(proto, 'response')
  .method('attachment')
  .method('redirect')
  .method('remove')
  .method('vary')
  .method('has')
  .method('set')
  .method('append')
  .method('flushHeaders')
  .access('status')
  .access('message')
  .access('body')
  .access('length')
  .access('type')
  .access('lastModified')
  .access('etag')
  .getter('headerSent')
  .getter('writable');

delegate(proto, 'request')
  .method('acceptsLanguages')
  .method('acceptsEncodings')
  .method('acceptsCharsets')
  .method('accepts')
  .method('get')
  .method('is')
  .access('querystring')
  .access('idempotent')
  .access('socket')
  .access('search')
  .access('method')
  .access('query')
  .access('path')
  .access('url')
  .access('accept')
  .getter('origin')
  .getter('href')
  .getter('subdomains')
  .getter('protocol')
  .getter('host')
  .getter('hostname')
  .getter('URL')
  .getter('header')
  .getter('headers')
  .getter('secure')
  .getter('stale')
  .getter('fresh')
  .getter('ips')
  .getter('ip');

const Koa = require('koa');
const app = new Koa();

app.use( async (ctx, next) => {
  // 获取 Cookies 方法：ctx.cookies.get('koa-cookie')
  ctx.cookies.set('koa-cookie', '456', {
    maxAge: 1000
  });

  ctx.body= 'hello world';
});

app.listen(4000, () => {
  console.log('server is running, port is 4000')
})

// 省略部分代码
const Cookies = require('cookies');
const proto = module.exports = {
  // 省略部分代码
  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;
  }
}

get header() {
  return this.req.headers;
},

set header(val) {
  this.req.headers = val;
},

get headers() {
  return this.req.headers;
},

set headers(val) {
  this.req.headers = val;
},

// status - 响应状态码
get status() {
  return this.res.statusCode;
},

set status(code) {
  if (this.headerSent) return;
  this._explicitStatus = true;
  this.res.statusCode = code;
  this.res.statusMessage = statuses[code];
},

// body - 响应体
get body() {
  return this._body;
},

set body(val) {
  this._body = val;
  // 根据 val 类型自动设置 Content-Length
},

// type - Content-Type
get type() {
  const type = this.get('Content-Type');
  if (!type) return '';
  return type.split(';')[0];
},

set type(type) {
  this.set('Content-Type', getType(type) || type);
}

// String
ctx.body = 'Hello World'

// Buffer
ctx.body = Buffer.from('Hello')

// Stream
ctx.body = fs.createReadStream('./file.txt')

// JSON Object
ctx.body = { message: 'Success' }

// null
ctx.body = null

请求进入
    │
    ├─→ dispatch(0)
    │     │
    │     ├─→ middleware[0](ctx,%20dispatch.bind(null,%201))
    │     │     │
    │     │     ├─→ before next()
    │     │     │
    │     │     ├─→ await next() → dispatch(1)
    │     │     │     │
    │     │     │     ├─→ middleware[1](ctx,%20dispatch.bind(null,%202))
    │     │     │     │     │
    │     │     │     │     ├─→ before next()
    │     │     │     │     │
    │     │     │     │     ├─→ await next() → dispatch(2)
    │     │     │     │     │     │
    │     │     │     │     │     └─→ middleware[2](ctx,%20dispatch.bind(null,%203))
    │     │     │     │     │           │
    │     │     │     │     │           └─→ dispatch(3) → Promise.resolve()
    │     │     │     │     │
    │     │     │     │     └─→ after next()
    │     │     │     │
    │     │     │     └─→ after next()
    │     │     │
    │     │     └─→ after next()
    │     │
    │     └─→ Promise.resolve()
    │
    └─→ respond(ctx)

const Koa = require('koa')
const app = new Koa()

app.use(async (ctx, next) => {
  console.log('1. 中间件 1 - 请求')
  await next()
  console.log('6. 中间件 1 - 响应')
})

app.use(async (ctx, next) => {
  console.log('2. 中间件 2 - 请求')
  await next()
  console.log('5. 中间件 2 - 响应')
})

app.use(async (ctx) => {
  console.log('3. 中间件 3 - 处理')
  ctx.body = 'Hello Koa'
  console.log('4. 中间件 3 - 结束')
})

// 执行顺序: 1 → 2 → 3 → 4 → 5 → 6

// compose 内部的错误处理
try {
  return Promise.resolve(fn(context, dispatch.bind(null, i + 1)))
} catch (err) {
  return Promise.reject(err)
}

// Application 的错误捕获
return fnMiddleware(ctx).then(handleResponse).catch(onerror)

// ❌ 不推荐：多个单独的中间件
app.use(async (ctx, next) => {
  ctx.set('X-Custom-1', 'value1')
  await next()
})

app.use(async (ctx, next) => {
  ctx.set('X-Custom-2', 'value2')
  await next()
})

// ✅ 推荐：合并为一个中间件
app.use(async (ctx, next) => {
  ctx.set('X-Custom-1', 'value1')
  ctx.set('X-Custom-2', 'value2')
  await next()
})

// ❌ 不推荐：串行执行
app.use(async (ctx) => {
  const user = await getUser(ctx.params.id)
  const posts = await getPosts(user.id)
  const comments = await getComments(posts[0].id)
  ctx.body = { user, posts, comments }
})

// ✅ 推荐：并行执行
app.use(async (ctx) => {
  const userId = ctx.params.id
  const [user, posts] = await Promise.all([
    getUser(userId),
    getPosts(userId)
  ])
  ctx.body = { user, posts }
})

// 静态资源缓存
app.use(serve('./public', {
  maxage: 365 * 24 * 60 * 60 * 1000,  // 1 年
  gzip: true,
  brotli: true
}))

// API 响应缓存
app.use(async (ctx, next) => {
  await next()
  
  if (ctx.status === 200 && ctx.method === 'GET') {
    ctx.set('Cache-Control', 'public, max-age=3600')
  }
})

const compress = require('koa-compress')

app.use(compress({
  threshold: 1024,  // 超过 1KB 才压缩
  gzip: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  }
}))

// 避免大对象存储在 ctx.state
app.use(async (ctx, next) => {
  // ❌ 不推荐
  ctx.state.bigData = await getBigData()
  
  // ✅ 推荐：只存储必要信息
  ctx.state.userId = ctx.params.id
  await next()
  // 处理完后清理
  ctx.state = null
})

// Application.handleRequest 源码
handleRequest(ctx, fnMiddleware) {
  const res = ctx.res;
  res.statusCode = 404;  // 默认 404
  // ...
}

// 确保在中间件中设置 ctx.body
app.use(async (ctx) => {
  ctx.body = 'Hello World'  // 设置 body 后状态码自动变为 200
})

// koa-compose 实现
return Promise.resolve(fn(context, dispatch.bind(null, i + 1)))

app.use(async (ctx, next) => {
  // 等待下游中间件完成
  await next()
  
  // 响应阶段的处理
  ctx.set('X-Response-Time', Date.now() - start)
})

// ❌ 无法捕获定时器中的错误
app.use(async (ctx, next) => {
  setTimeout(() => {
    throw new Error('Error!')  // 进程崩溃
  }, 1000)
  await next()
})

// ✅ 方式 1：使用 try/catch
app.use(async (ctx, next) => {
  try {
    await someAsyncOperation()
    await next()
  } catch (err) {
    ctx.status = 500
    ctx.body = { error: err.message }
  }
})

// ✅ 方式 2：全局错误处理
app.on('error', (err, ctx) => {
  console.error('Server Error:', err)
})

// ✅ 方式 3：进程级别的错误捕获
process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err)
  process.exit(1)
})

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason)
})

// String
ctx.body = 'Hello World'
// Content-Type: text/plain; charset=utf-8

// Buffer
ctx.body = Buffer.from('Hello')
// 直接发送二进制数据

// Stream
ctx.body = fs.createReadStream('./file.txt')
// 流式传输

// Object (JSON)
ctx.body = { message: 'Success' }
// Content-Type: application/json; charset=utf-8

// null
ctx.body = null
// 根据状态码决定响应内容

// 中间件队列
middleware = [fn1, fn2, fn3]

// 执行顺序（递归调用）
fn1(ctx, () => fn2(ctx, () => fn3(ctx, () => Promise.resolve())))

// 实际执行
fn1 before next
  fn2 before next
    fn3 execute
  fn2 after next
fn1 after next

// 时序图
请求 → fn1 → fn2 → fn3 → fn2 → fn1 → 响应

// 使用 @koa/router
const Router = require('@koa/router')
const router = new Router()

router.get('/users', (ctx) => {
  ctx.body = 'Users'
})

app.use(router.routes())

const request = require('supertest')
const Koa = require('koa')

describe('Logger Middleware', () => {
  let app
  
  beforeEach(() => {
    app = new Koa()
    app.use(logger())
    app.use((ctx) => {
      ctx.body = 'test'
    })
  })
  
  it('should log request', async () => {
    const consoleSpy = jest.spyOn(console, 'log')
    
    await request(app.callback())
      .get('/')
      .expect(200)
    
    expect(consoleSpy).toHaveBeenCalled()
  })
})

// Application 继承 EventEmitter
class Application extends Emitter {
  // 具有事件监听能力
  on('error', handler)
  emit('error', err)
}

// Context 通过 Object.create 继承
const ctx = Object.create(app.context)

// context.js 中使用 delegates
delegate(proto, 'response')
  .access('body')   // ctx.body → ctx.response.body
  .access('status') // ctx.status → ctx.response.status

delegate(proto, 'request')
  .access('query')  // ctx.query → ctx.request.query
  .access('path')   // ctx.path → ctx.request.path

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

// 1. 使用 debug 模块
const debug = require('debug')('koa:application')

// 启用调试
// DEBUG=koa:* node app.js

// 2. 添加日志中间件
app.use(async (ctx, next) => {
  console.log(`>>> ${ctx.method} ${ctx.url}`)
  await next()
  console.log(`<<< ${ctx.status}`)
})

// 3. 检查中间件顺序
console.log(app.middleware)

const onFinished = require('on-finished')
const response = require('./response')
const compose = require('koa-compose')
const context = require('./context')
const request = require('./request')
const Emitter = require('events')
const util = require('util')
const Stream = require('stream')
const http = require('http')
const only = require('only')

// 继承 Emitter，暴露一个 Application 类
module.exports = class Application extends Emitter {
  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
    }
  }

  // 等同于 http.createServer(app.callback()).listen(...)
  listen(...args) {
    const server = http.createServer(this.callback())
    return server.listen(...args)
  }

  // 返回 JSON 格式数据
  toJSON() {
    return only(this, ['subdomainOffset', 'proxy', 'env'])
  }

  // 把当前实例 JSON 格式化返回
  inspect() { return this.toJSON() }

  // 把中间件压入数组
  use(fn) {
    this.middleware.push(fn)
    return this
  }

  // 返回 Node 原生的 Server request 回调
  callback() {
    const fn = compose(this.middleware)
    const handleRequest = (req, res) => {
      const ctx = this.createContext(req, res)
      return this.handleRequest(ctx, fn)
    }

    return handleRequest
  }

  // 在回调中处理 request 请求对象
  handleRequest(ctx, fnMiddleware) {
    const res = ctx.res
    // 先设置一个 404 的响应码，等后面来覆盖它
    res.statusCode = 404
    const onerror = err => ctx.onerror(err)
    const handleResponse = () => respond(ctx)
    onFinished(res, onerror)
    return fnMiddleware(ctx).then(handleResponse).catch(onerror)
  }

  // 初始化一个上下文，为 req/res 建立各种引用关系，方便使用
  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
  }
}

// 响应处理的辅助函数
function respond(ctx) {
  const res = ctx.res
  let body = ctx.body
  // 此处删减了代码，如 head/空 body 等问题的处理策略等
  // 基于 Buffer/string 和 流，分别给予响应
  if (Buffer.isBuffer(body)) return res.end(body)
  if ('string' == typeof body) return res.end(body)
  if (body instanceof Stream) return body.pipe(res)

  // 最后则是以 JSON 的格式返回
  body = JSON.stringify(body)
  res.end(body)
}

const util = require('util')
const delegate = require('delegates')
const Cookies = require('cookies')

// 上下文 prototype 的原型
const proto = module.exports = {
  // 挑选上下文的内容，JSON 格式化处理后返回
  toJSON() {
    return {
      request: this.request.toJSON(),
      response: this.response.toJSON(),
      app: this.app.toJSON(),
      originalUrl: this.originalUrl,
      req: '<original node req>',
      res: '<original node res>',
      socket: '<original node socket>'
    }
  },

  // 错误捕获处理
  onerror(err) {},
  // 拿到 cookies
  get cookies() {},
  // 设置 cookies
  set cookies(_cookies) {}
}

// 对新版 Node 增加自定义 inspect 的支持
if (util.inspect.custom) {
  module.exports[util.inspect.custom] = module.exports.inspect
}

// 为响应对象绑定原型方法
delegate(proto, 'response')
  .method('attachment').method('redirect').method('remove').method('vary')
  .method('set').method('append').method('flushHeaders')
  .access('status').access('message').access('body').access('length').access('type')
  .access('lastModified').access('etag')
  .getter('headerSent').getter('writable')

// 为请求对象绑定原型方法
delegate(proto, 'request')
  .method('acceptsLanguages').method('acceptsEncodings').method('acceptsCharsets')
  .method('accepts').method('get').method('is')
  .access('querystring').access('idempotent').access('socket').access('search')
  .access('method').access('query').access('path').access('url').access('accept')
  .getter('origin').getter('href').getter('subdomains').getter('protocol').getter('host')
  .getter('hostname').getter('URL').getter('header').getter('headers').getter('secure')
  .getter('stale').getter('fresh').getter('ips').getter('ip')

┌───────────────────────────────────────────────────────────────────┐
│                        Koa 框架核心模块                            │
├─────────────┬─────────────┬─────────────┬─────────────────────────┤
│application.js│  context.js │ request.js  │    response.js         │
├─────────────┴─────────────┴─────────────┴─────────────────────────┤
│                        使用的 Node 基础能力                        │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  events  │  │   http   │  │  stream  │  │   util   │          │
│  │ (Emitter)│  │(Server)  │  │(Readable │  │(inspect) │          │
│  │          │  │          │  │/Writable)│  │          │          │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘          │
│                                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  path    │  │  buffer  │  │   fs     │  │ process  │          │
│  │(路由解析)│  │(二进制    │  │(文件流   │  │(env/     │          │
│  │          │  │ 响应)    │  │ 响应)    │  │ exit)    │          │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘          │
│                                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                        │
│  │ url      │  │ querystring│ │ crypto  │                        │
│  │(URL解析) │  │(参数解析) │  │(Cookie  │                        │
│  │          │  │          │  │ 签名)   │                        │
│  └──────────┘  └──────────┘  └──────────┘                        │
│                                                                    │
├────────────────────────────────────────────────────────────────────┤
│                     具体使用场景映射                                │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Node 模块      │  Koa 中的使用场景                                │
│  ──────────────────────────────────────────────────────────────── │
│  events         │  Application 继承 Emitter，实现错误事件监听      │
│                 │  app.on('error') / app.emit('error')             │
│  http           │  http.createServer() 创建 HTTP Server            │
│                 │  http.IncomingMessage / http.ServerResponse      │
│  stream         │  ctx.body 支持 Stream 类型响应                   │
│                 │  body.pipe(res) 流式输出                          │
│  buffer         │  Buffer.isBuffer(body) 检测二进制响应            │
│                 │  Buffer.byteLength(body) 计算响应长度            │
│  util           │  util.inspect.custom 自定义对象格式化            │
│                 │  util.format 格式化错误信息                       │
│  process        │  process.env.NODE_ENV 获取运行环境               │
│  path           │  路径解析与拼接（多在中间件和路由中使用）         │
│  url            │  req.url 解析请求 URL                            │
│  querystring    │  解析和序列化查询字符串                           │
│  crypto         │  Cookie 签名验证（通过 keys 配置）               │
│  fs             │  静态文件服务中间件中使用文件流                   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

const http = require('http')

class Koa {
  constructor() {
    this.middleware = []
  }
  
  use(fn) {
    this.middleware.push(fn)
    return this
  }
  
  listen(...args) {
    const server = http.createServer(this.callback())
    return server.listen(...args)
  }
  
  callback() {
    const fn = this.compose(this.middleware)
    
    return (req, res) => {
      const ctx = { req, res }
      fn(ctx).then(() => {
        res.end(ctx.body || 'Not Found')
      }).catch(err => {
        res.statusCode = 500
        res.end(err.message)
      })
    }
  }
  
  compose(middleware) {
    return function(context) {
      let index = -1
      
      function dispatch(i) {
        if (i <= index) return Promise.reject(new Error('next() called multiple times'))
        index = i
        
        const fn = middleware[i]
        if (!fn) return Promise.resolve()
        
        try {
          return Promise.resolve(fn(context, () => dispatch(i + 1)))
        } catch (err) {
          return Promise.reject(err)
        }
      }
      
      return dispatch(0)
    }
  }
}

// 测试
const app = new Koa()

app.use(async (ctx, next) => {
  console.log('Middleware 1 start')
  await next()
  console.log('Middleware 1 end')
})

app.use(async (ctx, next) => {
  console.log('Middleware 2 start')
  ctx.body = 'Hello Koa'
  await next()
  console.log('Middleware 2 end')
})

app.listen(3000)