安装

Koa 依赖 node v7.6.0 或 ES2015及更高版本和 async 方法支持.

你可以使用自己喜欢的版本管理器快速安装支持的 node 版本:

  1. $ nvm install 7
  2. $ npm i koa
  3. $ node my-koa-app.js

使用 Babel 实现 Async 方法

要在 node < 7.6 版本的 Koa 中使用 async 方法, 我们推荐使用 babel’s require hook.

  1. require('babel-register');
  2. // 应用的其余 require 需要被放到 hook 后面
  3. const app = require('./app');

要解析和编译 async 方法, 你至少应该有 transform-async-to-generatortransform-async-to-module-method 插件.

例如, 在你的 .babelrc 文件中, 你应该有:

  1. {
  2. "plugins": ["transform-async-to-generator"]
  3. }

你也可以用 env preset 的 target 参数 "node": "current" 替代.

应用程序

Koa 应用程序是一个包含一组中间件函数的对象,它是按照类似堆栈的方式组织和执行的。 Koa 类似于你可能遇到过的许多其他中间件系统,例如 Ruby 的 Rack ,Connect 等,然而,一个关键的设计点是在其低级中间件层中提供高级“语法糖”。 这提高了互操作性,稳健性,并使书写中间件更加愉快。

这包括诸如内容协商,缓存清理,代理支持和重定向等常见任务的方法。 尽管提供了相当多的有用的方法 Koa 仍保持了一个很小的体积,因为没有捆绑中间件。

必修的 hello world 应用:

  1. const Koa = require('koa');
  2. const app = new Koa();
  3. app.use(async ctx => {
  4. ctx.body = 'Hello World';
  5. });
  6. app.listen(3000);

级联

Koa 中间件以更传统的方式级联,您可能习惯使用类似的工具 - 之前难以让用户友好地使用 node 的回调。然而,使用 async 功能,我们可以实现 “真实” 的中间件。对比 Connect 的实现,通过一系列功能直接传递控制,直到一个返回,Koa 调用“下游”,然后控制流回“上游”。

下面以 “Hello World” 的响应作为示例,当请求开始时首先请求流通过 x-response-timelogging 中间件,然后继续移交控制给 response 中间件。当一个中间件调用 next() 则该函数暂停并将控制传递给定义的下一个中间件。当在下游没有更多的中间件执行后,堆栈将展开并且每个中间件恢复执行其上游行为。

  1. const Koa = require('koa');
  2. const app = new Koa();
  3. // logger
  4. app.use(async (ctx, next) => {
  5. await next();
  6. const rt = ctx.response.get('X-Response-Time');
  7. console.log(`${ctx.method} ${ctx.url} - ${rt}`);
  8. });
  9. // x-response-time
  10. app.use(async (ctx, next) => {
  11. const start = Date.now();
  12. await next();
  13. const ms = Date.now() - start;
  14. ctx.set('X-Response-Time', `${ms}ms`);
  15. });
  16. // response
  17. app.use(async ctx => {
  18. ctx.body = 'Hello World';
  19. });
  20. app.listen(3000);

设置

应用程序设置是 app 实例上的属性,目前支持如下:

  • app.env 默认是 NODE_ENV 或 “development”
  • app.keys 签名的 cookie 密钥数组
  • app.proxy 当真正的代理头字段将被信任时
  • 忽略 .subdomainsapp.subdomainOffset 偏移量,默认为 2
  • app.proxyIpHeader 代理 ip 消息头, 默认为 X-Forwarded-For
  • app.maxIpsCount 从代理 ip 消息头读取的最大 ips, 默认为 0 (代表无限)

您可以将设置传递给构造函数:

  1. const Koa = require('koa');
  2. const app = new Koa({ proxy: true });

或动态的:

  1. const Koa = require('koa');
  2. const app = new Koa();
  3. app.proxy = true;

app.listen(…)

Koa 应用程序不是 HTTP 服务器的1对1展现。 可以将一个或多个 Koa 应用程序安装在一起以形成具有单个HTTP服务器的更大应用程序。

创建并返回 HTTP 服务器,将给定的参数传递给 Server#listen()。这些内容都记录在 nodejs.org.

以下是一个无作用的 Koa 应用程序被绑定到 3000 端口:

  1. const Koa = require('koa');
  2. const app = new Koa();
  3. app.listen(3000);

这里的 app.listen(...) 方法只是以下方法的语法糖:

  1. const http = require('http');
  2. const Koa = require('koa');
  3. const app = new Koa();
  4. http.createServer(app.callback()).listen(3000);

这意味着您可以将同一个应用程序同时作为 HTTP 和 HTTPS 或多个地址:

  1. const http = require('http');
  2. const https = require('https');
  3. const Koa = require('koa');
  4. const app = new Koa();
  5. http.createServer(app.callback()).listen(3000);
  6. https.createServer(app.callback()).listen(3001);

app.callback()

返回适用于 http.createServer() 方法的回调函数来处理请求。你也可以使用此回调函数将 koa 应用程序挂载到 Connect/Express 应用程序中。

app.use(function)

将给定的中间件方法添加到此应用程序。app.use() 返回 this, 因此可以链式表达.

  1. app.use(someMiddleware)
  2. app.use(someOtherMiddleware)
  3. app.listen(3000)

它等同于

  1. app.use(someMiddleware)
  2. .use(someOtherMiddleware)
  3. .listen(3000)

参阅 Middleware 获取更多信息.

app.keys=

设置签名的 Cookie 密钥。

这些被传递给 KeyGrip,但是你也可以传递你自己的 KeyGrip 实例。

例如,以下是可以接受的:

  1. app.keys = ['im a newer secret', 'i like turtle'];
  2. app.keys = new KeyGrip(['im a newer secret', 'i like turtle'], 'sha256');

这些密钥可以倒换,并在使用 { signed: true } 参数签名 Cookie 时使用。

  1. ctx.cookies.set('name', 'tobi', { signed: true });

app.context

app.context 是从其创建 ctx 的原型。您可以通过编辑 app.contextctx 添加其他属性。这对于将 ctx 添加到整个应用程序中使用的属性或方法非常有用,这可能会更加有效(不需要中间件)和/或 更简单(更少的 require()),而更多地依赖于ctx,这可以被认为是一种反模式。

例如,要从 ctx 添加对数据库的引用:

  1. app.context.db = db();
  2. app.use(async ctx => {
  3. console.log(ctx.db);
  4. });

注意:

  • ctx 上的许多属性都是使用 gettersetterObject.defineProperty() 定义的。你只能通过在 app.context 上使用 Object.defineProperty() 来编辑这些属性(不推荐)。查阅 https://github.com/koajs/koa/issues/652.
  • 安装的应用程序目前使用其父级的 ctx 和设置。 因此,安装的应用程序只是一组中间件。

错误处理

默认情况下,将所有错误输出到 stderr,除非 app.silenttrue。 当 err.status404err.exposetrue 时默认错误处理程序也不会输出错误。 要执行自定义错误处理逻辑,如集中式日志记录,您可以添加一个 “error” 事件侦听器:

  1. app.on('error', err => {
  2. log.error('server error', err)
  3. });

如果 req/res 期间出现错误,并且 无法 响应客户端,Context实例仍然被传递:

  1. app.on('error', (err, ctx) => {
  2. log.error('server error', err, ctx)
  3. });

当发生错误 并且 仍然可以响应客户端时,也没有数据被写入 socket 中,Koa 将用一个 500 “内部服务器错误” 进行适当的响应。在任一情况下,为了记录目的,都会发出应用级 “错误”。