Koa

Koa -- 基于 Node.js 平台的下一代 web 开发框架

简介

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

安装

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

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

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

使用 Babel 实现 Async 方法

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

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

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

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

{
  "plugins": ["transform-async-to-generator"]
}

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

应用程序

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

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

必修的 hello world 应用:

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

app.use(async ctx => {
  ctx.body = 'Hello World';
});

app.listen(3000);

级联

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

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

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

// logger

app.use(async (ctx, next) => {
  await next();
  const rt = ctx.response.get('X-Response-Time');
  console.log(`${ctx.method} ${ctx.url} - ${rt}`);
});

// x-response-time

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

// response

app.use(async ctx => {
  ctx.body = 'Hello World';
});

app.listen(3000);

设置

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

app.listen(...)

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

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

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

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

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

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

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

const http = require('http');
const https = require('https');
const Koa = require('koa');
const app = new Koa();
http.createServer(app.callback()).listen(3000);
https.createServer(app.callback()).listen(3001);

app.callback()

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

app.use(function)

将给定的中间件方法添加到此应用程序。参阅 Middleware 获取更多信息.

app.keys=

设置签名的 Cookie 密钥。

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

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

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

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

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

app.context

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

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

app.context.db = db();

app.use(async ctx => {
  console.log(ctx.db);
});

注意:

错误处理

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

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

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

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

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

上下文(Context)

Koa Context 将 node 的 requestresponse 对象封装到单个对象中,为编写 Web 应用程序和 API 提供了许多有用的方法。 这些操作在 HTTP 服务器开发中频繁使用,它们被添加到此级别而不是更高级别的框架,这将强制中间件重新实现此通用功能。

_每个_ 请求都将创建一个 Context,并在中间件中作为接收器引用,或者 ctx 标识符,如以下代码片段所示:

app.use(async ctx => {
  ctx; // 这是 Context
  ctx.request; // 这是 koa Request
  ctx.response; // 这是 koa Response
});

为方便起见许多上下文的访问器和方法直接委托给它们的 ctx.requestctx.response ,不然的话它们是相同的。 例如 ctx.typectx.length 委托给 response 对象,ctx.pathctx.method 委托给 request

API

Context 具体方法和访问器.

ctx.req

Node 的 request 对象.

ctx.res

Node 的 response 对象.

绕过 Koa 的 response 处理是 不被支持的. 应避免使用以下 node 属性:

ctx.request

koa 的 Request 对象.

ctx.response

koa 的 Response 对象.

ctx.state

推荐的命名空间,用于通过中间件传递信息和你的前端视图。

ctx.state.user = await User.find(id);

ctx.app

应用程序实例引用

ctx.cookies.get(name, [options])

通过 options 获取 cookie name:

koa 使用 cookies 模块,其中只需传递参数。

ctx.cookies.set(name, value, [options])

通过 options 设置 cookie namevalue :

koa 使用传递简单参数的 cookies 模块。

ctx.throw([status], [msg], [properties])

Helper 方法抛出一个 .status 属性默认为 500 的错误,这将允许 Koa 做出适当地响应。

允许以下组合:

ctx.throw(400);
ctx.throw(400, 'name required');
ctx.throw(400, 'name required', { user: user });

例如 ctx.throw(400, 'name required') 等效于:

const err = new Error('name required');
err.status = 400;
err.expose = true;
throw err;

请注意,这些是用户级错误,并用 err.expose 标记,这意味着消息适用于客户端响应,这通常不是错误消息的内容,因为您不想泄漏故障详细信息。

你可以根据需要将 properties 对象传递到错误中,对于装载上传给请求者的机器友好的错误是有用的。这用于修饰其人机友好型错误并向上游的请求者报告非常有用。

ctx.throw(401, 'access_denied', { user: user });

koa 使用 http-errors 来创建错误。

ctx.assert(value, [status], [msg], [properties])

!value 时,Helper 方法抛出类似于 .throw() 的错误。这与 node 的 assert() 方法类似.

ctx.assert(ctx.state.user, 401, 'User not found. Please login!');

koa 使用 http-assert 作为断言。

ctx.respond

为了绕过 Koa 的内置 response 处理,你可以显式设置 ctx.respond = false;。 如果您想要写入原始的 res 对象而不是让 Koa 处理你的 response,请使用此参数。

请注意,Koa _不_ 支持使用此功能。这可能会破坏 Koa 中间件和 Koa 本身的预期功能。使用这个属性被认为是一个 hack,只是便于那些希望在 Koa 中使用传统的 fn(req, res) 功能和中间件的人。

Request 别名

以下访问器和 Request 别名等效:

Response 别名

以下访问器和 Response 别名等效:

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

503 first byte timeout

Error 503 first byte timeout

first byte timeout

Guru Mediation:

Details: cache-dca17723-DCA 1534148160 1810374104


Varnish cache server

响应(Response)

Koa Response 对象是在 node 的 vanilla 响应对象之上的抽象,提供了诸多对 HTTP 服务器开发有用的功能。

API

response.header

响应标头对象。

response.headers

响应标头对象。别名是 response.header

response.socket

请求套接字。

response.status

获取响应状态。默认情况下,response.status 设置为 404 而不是像 node 的 res.statusCode 那样默认为 200

response.status=

通过数字代码设置响应状态:

注意: 不用太在意记住这些字符串, 如果你写错了,可以查阅这个列表随时更正.

response.message

获取响应的状态消息. 默认情况下, response.messageresponse.status 关联.

response.message=

将响应的状态消息设置为给定值。

response.length=

将响应的 Content-Length 设置为给定值。

response.length

以数字返回响应的 Content-Length,或者从ctx.body推导出来,或者undefined

response.body

获取响应主体。

response.body=

将响应体设置为以下之一:

如果 response.status 未被设置, Koa 将会自动设置状态为 200204

String

Content-Type 默认为 text/htmltext/plain, 同时默认字符集是 utf-8。Content-Length 字段也是如此。

Buffer

Content-Type 默认为 application/octet-stream, 并且 Content-Length 字段也是如此。

Stream

Content-Type 默认为 application/octet-stream

每当流被设置为响应主体时,.onerror 作为侦听器自动添加到 error 事件中以捕获任何错误。此外,每当请求关闭(甚至过早)时,流都将被销毁。如果你不想要这两个功能,请勿直接将流设为主体。例如,当将主体设置为代理中的 HTTP 流时,你可能不想要这样做,因为它会破坏底层连接。

参阅: https://github.com/koajs/koa/pull/612 获取更多信息。

以下是流错误处理的示例,而不会自动破坏流:

const PassThrough = require('stream').PassThrough;

app.use(async ctx => {
  ctx.body = someHTTPStream.on('error', ctx.onerror).pipe(PassThrough());
});

Object

Content-Type 默认为 application/json. 这包括普通的对象 { foo: 'bar' } 和数组 ['foo', 'bar']

response.get(field)

不区分大小写获取响应标头字段值 field

const etag = ctx.response.get('ETag');

response.set(field, value)

设置响应标头 fieldvalue:

ctx.set('Cache-Control', 'no-cache');

response.append(field, value)

用值 val 附加额外的标头 field

ctx.append('Link', '<http://127.0.0.1/>');

response.set(fields)

用一个对象设置多个响应标头fields:

ctx.set({
  'Etag': '1234',
  'Last-Modified': date
});

response.remove(field)

删除标头 field

response.type

获取响应 Content-Type 不含参数 "charset"。

const ct = ctx.type;
// => "image/png"

response.type=

设置响应 Content-Type 通过 mime 字符串或文件扩展名。

ctx.type = 'text/plain; charset=utf-8';
ctx.type = 'image/png';
ctx.type = '.png';
ctx.type = 'png';

注意: 在适当的情况下为你选择 charset, 比如 response.type = 'html' 将默认是 "utf-8". 如果你想覆盖 charset, 使用 ctx.set('Content-Type', 'text/html') 将响应头字段设置为直接值。

response.is(types...)

非常类似 ctx.request.is(). 检查响应类型是否是所提供的类型之一。这对于创建操纵响应的中间件特别有用。

例如, 这是一个中间件,可以削减除流之外的所有HTML响应。

const minify = require('html-minifier');

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

  if (!ctx.response.is('html')) return;

  let body = ctx.body;
  if (!body || body.pipe) return;

  if (Buffer.isBuffer(body)) body = body.toString();
  ctx.body = minify(body);
});

response.redirect(url, [alt])

执行 [302] 重定向到 url.

字符串 “back” 是特别提供Referrer支持的,当Referrer不存在时,使用 alt 或“/”。

ctx.redirect('back');
ctx.redirect('back', '/index.html');
ctx.redirect('/login');
ctx.redirect('http://google.com');

要更改 “302” 的默认状态,只需在该调用之前或之后分配状态。要变更主体请在此调用之后:

ctx.status = 301;
ctx.redirect('/cart');
ctx.body = 'Redirecting to shopping cart';

response.attachment([filename])

Content-Disposition 设置为 “附件” 以指示客户端提示下载。(可选)指定下载的 filename

response.headerSent

检查是否已经发送了一个响应头。 用于查看客户端是否可能会收到错误通知。

response.lastModified

Last-Modified 标头返回为 Date, 如果存在。

response.lastModified=

Last-Modified 标头设置为适当的 UTC 字符串。您可以将其设置为 Date 或日期字符串。

ctx.response.lastModified = new Date();

response.etag=

设置包含 " 包裹的 ETag 响应, 请注意,没有相应的 response.etag getter。

ctx.response.etag = crypto.createHash('md5').update(ctx.body).digest('hex');

response.vary(field)

field 上变化。

response.flushHeaders()

刷新任何设置的标头,并开始主体。

参与翻译

如果您希望贡献力量完善本中文文档,请前往 https://github.com/demopark/koa-docs-Zh-CN.git 仓库。

相关资源

Community links to discover third-party middleware for Koa, full runnable examples, thorough guides and more! If you have questions join us in IRC!