Koa 2.x 中文文档

此项目同步自 koajs / koa 项目中的 docs. 除特殊情况, 将保持每月一次的同步频率.

Koa 通过 node.js 实现了一个十分具有表现力的 HTTP 中间件框架,力求让 Web 应用开发和 API 使用更加地愉快。Koa 的中间件之间按照编码顺序在栈内依次执行,允许您执行操作并向下传递请求(downstream),之后过滤并逆序返回响应(upstream)。

几乎所有 HTTP 服务器通用的方法都被直接集成到 Koa 大约570行源码的代码库中。其中包括内容协商,节点不一致性的规范化,重定向等等操作。

Koa没有捆绑任何中间件。

安装

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

$ npm install koa

Hello koa

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

// 响应
app.use(ctx => {
  ctx.body = 'Hello Koa';
});

app.listen(3000);

入门

中间件

Koa 是一个中间件框架,可以采用两种不同的方法来实现中间件:

以下是使用两种不同方法实现一个日志中间件的示例:

async functions (node v7.6+)

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

Common function

// 中间件通常带有两个参数 (ctx, next), ctx 是一个请求的上下文(context),
// next 是调用执行下游中间件的函数. 在代码执行完成后通过 then 方法返回一个 Promise.

app.use((ctx, next) => {
  const start = Date.now();
  return next().then(() => {
    const ms = Date.now() - start;
    console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
  });
});

Koa v1.x 中间件签名

中间件签名在 v1.x 和 v2.x 之间已经被更改. 旧的签名已经被弃用.

旧的签名中间件支持将在 v3 中删除

请参阅 迁移指南 获取有关从 v1.x 升级并使用 v2.x 中间件的更多信息。

上下文, 请求和响应

每个中间件都接收一个 Koa 的 Context 对象,该对象封装了一个传入的 http 消息,并对该消息进行了相应的响应。 ctx 通常用作上下文对象的参数名称。

app.use(async (ctx, next) => { await next(); });

Koa 提供了一个 Request 对象作为 Contextrequest 属性。 Koa的 Request 对象提供了用于处理 http 请求的方法,该请求委托给 node http 模块的IncomingMessage

这是一个检查请求客户端 xml 支持的示例。

app.use(async (ctx, next) => {
  ctx.assert(ctx.request.accepts('xml'), 406);
  // 相当于:
  // if (!ctx.request.accepts('xml')) ctx.throw(406);
  await next();
});

Koa提供了一个 Response 对象作为 Contextresponse 属性。 Koa的 Response 对象提供了用于处理 http 响应的方法,该响应委托给 ServerResponse

Koa 对 Node 的请求和响应对象进行委托而不是扩展它们。这种模式提供了更清晰的接口,并减少了不同中间件与 Node 本身之间的冲突,并为流处理提供了更好的支持。 IncomingMessage 仍然可以作为 Context 上的 req 属性被直接访问,并且ServerResponse也可以作为Context 上的 res 属性被直接访问。

这里是一个使用 Koa 的 Response 对象将文件作为响应体流式传输的示例。

app.use(async (ctx, next) => {
  await next();
  ctx.response.type = 'xml';
  ctx.response.body = fs.createReadStream('really_large.xml');
});

Context 对象还提供了其 requestresponse 方法的快捷方式。在前面的例子中,可以使用 ctx.type 而不是 ctx.request.type,而 ctx.accepts 可以用来代替 ctx.request.accepts

关于 Request, ResponseContext 更多详细信息, 参阅 请求 API 参考, 响应 API 参考上下文 API 参考.

Koa 应用程序

在执行 new Koa() 时创建的对象被称为 Koa 应用对象。

应用对象是带有 node http 服务的 Koa 接口,它可以处理中间件的注册,将http请求分发到中间件,进行默认错误处理,以及对上下文,请求和响应对象进行配置。

了解有关应用程序对象的更多信息请到 应用 API 参考.

文档

Babel 配置

如果你正在使用的不是 node v7.6+, 我们推荐你用 babel-preset-env 配置 babel :

$ npm install babel-register babel-preset-env --save

在你入口文件配置 babel-register:

require('babel-register');

还有你的 .babelrc 配置:

{
  "presets": [
    ["env", {
      "targets": {
        "node": true
      }
    }]
  ]
}

故障排除

在 Koa 指南中查阅 故障排除指南调试 Koa.

运行测试

$ npm test