Koa 使用

安装

Koa 当前需要 node 0.11.x 并开启 –harmony(或– harmony-generators), 因为他依赖于 ES6 的 generator 特性
node --harmony my-koa-app.js

应用

Koa 应用是一个包含中间件 generator 方法数组的对象. 当请求到来时, 这些方法会以 stack-slice 的顺序执行.

Koa 的一大设计理念是, 通过其他底层中间件层提供高级”语法糖”, 而不是 Koa, 大大提高了框架的互操作性和健壮性, 并让中间件开发变得有趣.

简单例子

var koa = require("koa");
var app = koa();
app.use(function*(){
  this.body = "Hello World";
});
app.listen(3000);
`</pre>

**注**: 与普通 function 不同, generator function 以 function* 的形式声明.

### 编写级联代码

koa 中间件以一种更加传统的方式级联.

以往的 Node 开发中, 级联是通过回调实现的, 用户友好度上有欠缺

Koa 借助 generator 实现了中间件架构

Koa 的执行代码的形式不再是简单的将控制权依次移交给一个又一个方法直到结束, 而是像一个回形针, 用户请求中间件, 遇到 yield next 关键字的时候, 会被传递给下游中间件(downstream), 在 yield next 捕获不到 downstream 的时候, 逆序返回执行代码(upstream)(yield next 后面的代码)

<pre>`var koa = require("koa");
var app = koa();

// x-response-time

app.use(function* (next){
  var start = new Date;
  yield next;
  var ms = new Date - start;
  this.set("X-Response-Time", ms+"ms");
})

// logger
app.use(function* (next){
  var start = new Date;
  yield next;
  var ms = new Date - start;
  console.log("%s %s - %s", this.method, this.url, ms)
});

// response
app.use(function* (){
  this.body = "Hello World";
});

app.listen(3000);
`</pre>

### 应用配置

应用配置是 app 实例的属性, 目前支持以下配置:
- app.name 应用名
- app.env 执行环境, 默认是`NODE_ENV`或者`development`字符串
- app.proxy, 当该属性为 true 时, `proxy header` 参数会被添加到信任列表中

### app.listen(...)

一个 Koa 应用跟 HTTP Server 不是1-to-1关系, 一个或多个 Koa应用可以被加载到一块, 组成一个更大的包含一个 HTTP server 的应用

该方法创建并返回一个 http server, 并支持传递固定参数

<pre>`var koa = require("koa")
var app = koa()
app.listen(3000)
`</pre>

方法 app.listen(...)是一个语法糖, 等价于

<pre>`var http = require("http")
var koa = require("koa")
var app = koa()
http.createServer(app.callback()).listen(3000)
`</pre>

这意味着可以在多个端口使用同一个 app

<pre>`http.createServer(app.callback()).listen(3000)
http.createServer(app.callback()).listen(3001)
`</pre>

### app.callback()

返回一个回调方法能用于 http.createServer()来处理请求, 也可以将这个回调函数挂载到 Connect/Express 应用上

### app.use(function)

将给定的 function 当做中间件加载到应用中

### app.keys=

设置 Cookie 签名密钥

### 错误处理

除非应用执行环境(NODE_ENV)被配置为"test", Koa 都会将所有错误信息输出到 stderr, 如果想自定义错误处理逻辑, 可以定义一个"错误事件"来坚挺 Koa App 中的错误:

<pre>`app.on("error",function(err){
  log.error("server error", err);
})
`</pre>

当 req/res 周期中出现任何错误且无法响应客户端时, koa 会把 Context(上下文)实例作为第二个参数传递给 error 事件:

<pre>`app.on("error", function(err, ctx){
  log.error("server error", err, ctx)
})
`</pre>

### 上下文

Koa 的 Context 把 node 的 request 和 response 对象封装在一个单独对象, 并提供许多开发 web 应用和 APIs 有用的方法. 那些 HTTP Server 开发中使用非常频繁操作, 直接在 Koa 里实现, 而不是放在更高层次的框架, 这样中间件就不需要重复实现这些通用的功能.

每个请求会创建自己的 Context 实例, 在中间件中作为 receiver 引用, 或通过 this 标示引用:

<pre>`app.use(function* (){
  this; // is the Context
  this.request; // is a koa Request
  this.response; // is a koa Response
})

Context 的许多访问器和方法直接委托为他们的 ctx.request 或 ctx.response 的等价方法, 用于访问方便, 是完全相同的, 比如 ctx.type 和 ctx.length 委托与 response 对象, ctx.path 和 ctx.method 委托与 request.