Skip to content

docschina/koa

 
 

Repository files navigation

Koa 中文文档

用于 nodejs 的 koa 中间件框架

gitter NPM version build status Test coverage OpenCollective Backers OpenCollective Sponsors

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

用 node.js 来实现 HTTP 的中间件框架,让 Web 应用程序和 API 可以更加愉快地编写。Koa 的中间件堆栈以类似堆栈的方式流动,允许您执行下游操作,然后过滤并操纵上游的响应。

几乎所有 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 function
  • common function

以下是每个不同功能记录器的中间件示例:

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 是一个请求的上下文,
// 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 仍然可以直接被访问,因为 ContextServerResponse 上的 req 属性可以直接作为 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 应用程序对象。

应用对象是 Koa 与 node 的 http 服务器和处理中间件注册的接口,从 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

作者

查看 作者.

社区

职位公告

寻找职业进阶?

支持者

Support us with a monthly donation and help us continue our activities.

赞助商

Become a sponsor and get your logo on our README on Github with a link to your site.

授权

MIT

翻译

GitHub @DemoPark Repo koa-docs-Zh-CN

Packages

No packages published

Languages

  • JavaScript 99.6%
  • Other 0.4%