跳到主要内容

Koa 是一个全新的 web 框架,由 Express 幕后的原班人马打造,致力于成为 web 应用和 API 开发领域中的一个更小、更富有表现力、更健壮的基石。 通过使用异步函数,Koa 帮你丢弃回调函数,并有力地增强错误处理能力。 Koa 并没有捆绑任何中间件,而是提供了一套优雅的方法,帮助您快速而愉快地编写服务端应用程序。

安装

Koa 需要 node v12.17.0 或更高版本,以满足对 ES2015 和异步函数的支持。

$ npm install koa

Hello koa

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

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

app.listen(3000);

入门

  • Kick-Off-Koa - 通过一系列自身指引的讲解介绍了 Koa。
  • 指南 - 直接去看文档吧。

中间件

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 是一个请求的上下文(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.response.type,而 ctx.accepts 可以用来代替 ctx.request.accepts

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

Koa 应用程序

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

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

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

文档

故障排除

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