Koa2开发详解（自官网）

摘要：通过杠杆生成器可以让你引导回调函数，极大的提升错误处理。这是因为原先很难让用户有好的使用的回调函数。返回一个回调函数，相当于方法，来出了请求。使的有效期到期。检查请求缓存是否刷新，或者内容是否发生改变。

次世代nodejs 的 web框架

koa是由Express幕后团队打造的，目的是更小，更快，更稳定的web应用和apis。通过杠杆生成器（leveraging generators)Koa可以让你引导（ditch）回调函数，极大的提升错误处理。Koa核心不集成任何的中间件，其本身提供的优雅的功能套件就能够写出既快又nice的服务器。

Koa需要node7.6.0或更高的版本，因为需要async function支持。
你可以使用自己的版本管理器很快的安装一个支持的版本。

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

想要在较低版本的node中使用async函数，我们建议使用babel。

require("babel-core/register")
//然后在加载应用的主代码，这个必须在babel后面
const app = require("./app")

为了编译和转化async functions你需要在最后的压缩版本中使用"transform-async-to-generator"或者transform-async-to-module-method插件。例如，在你的.babelrc文件中，进行如下设置。

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

你也可以使用stage-3 persent来代替。

一个Koa应用是一个对象，其包含一个数组，数组有很多函数组成的中间件，这些函数集合起来等待请求，并且执行时是按照类栈的方式。koa和很多其他中间件系统相似，你也许是用过Ruby的Rack,Connect等。然而一个设计的决定行因素是提供高等级"sugar"，与此同时低等级中间件层。因此提升了交互性，鲁棒性（软件设计术语，即稳定性）并且使得编写中间件更加的带劲！

这包括一些常用任务的方法——例如链接协调，缓存，代理支持，别用等。尽管提供了大量的有用的方法，但是koa仍然保持了一个较小的体积，因为没有绑定中间件。

怎么能偶少得了一个hello world应用。

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

app.use(ctx => {
    ctx.body = "hello world";
})

app.listen(3000)

koa 的串联中间件使用了一个比较传统的方式，跟你通常用的工具很像。这是因为原先很难让用户有好的使用node的回调函数。然而使用异步函数我们能偶“真正得”是有中间件。相较于连接的实现，这个更容易提供一些列函数/功能来控制，在最后返回便可。koa调用"downstream",控制流返回"upstream".

下面的例子返回“hello world”，然而最开始请求先通过x-response-time和logging中间件来记录请求的开始。然后通过返回的中间件产出控制。当一个中间件执行next()函数，来延迟和传递控制给下一个声明的中间件。然后直到没有中间件需要执行downstream了，栈将会松开然后每个中间件复原去展现自己的“upstream”行为。

应用设置即在实例app上的属性。当前支持如下：

app.env 默认是NODE_ENV或者“development”。

app.proxy 当设置为true时，porxy头部将被信任。

app.subdomainOffset 设置.subdomains的偏移量。替代[2]。

app.listen(...)
一个Koa应用不是一对一的呈现一个htpp服务器。一个或者多个应用也许被添加到一块形成大的应用对应一个http服务器。

app.listen(...)方法是如下的一个语法糖。

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

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

app.callback()
返回一个回调函数，相当于http.createServer()方法，来出了请求。

你也可以使用这个方法在你的Connect/Express应用中添加koa应用。

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}来使用。

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

app.context
app.context是ctx的来源。你可以使用app.context添加额外的属性到ctx。这对于创建跨越整个app应用的属性或者方法来说是有用的，而且性能更好，在依赖上也跟简单，可以考虑做一个anti-pattern。

例子，从ctx添加一个数据库引用。

add.context.db = db()

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

注意:

通过getter和setter以及Object.difineProperty()设置的属性，你只能在app.context使用Object.defineProperty()来编辑他们。（不推荐）

使用父级的ctx和设置来添加当前的应用。这样添加的app就能使用到那些中间件。

除非设置app.silent是true，不然所有的出无输出都是标准输出。默认的错误输出不会处理像是err.sttus是404或者err.expose是true。为了自定义错误输出例如日志，你可以添加错误事件监听。

app.on("error", err =>
  log.error("server error", err)
);

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

app.on("error", (err, ctx) =>
  log.error("server error", err, ctx)
);

如果有错误发生, 并且还能响应客户端(即没有数据被写入到 socket), Koa 会返回 500 "Internal Server Error". 这两种情况都会触发 app-level 的 error 事件, 用于 logging.

一个Koa环境（实例）封装了node原生的请求和返回对象到一个多带带的对象中，这个多带带的对象提供了许多使用的方法，能够编写web应用和API。这些HTTP服务器开发中经常用到的操作被添加到当前等级，而不是高等级。他将强制中间件重新实现这些常用的功能。

一个环境Context在每次请求时被创建，并且被引用至中间件作为接收器，或者定义成this。如下所示。

app.use(function *(){
    this;//这里是koa环境context
    this.request;//是一个koa请求
    this.response;//是一个koa返回
})

很多context环境访问器和方法只是ctx.requestkoa请求或者ctx.responsekoa返回的代理，主要是为了方便。例如ctx.type和ctx.length代表response返回对象，ctx.paht和ctx.methos代表请求。

API 接口。
环境（Context）定义的方法和访问器。

ctx.req Node的request对象。

ctx.res Node的response对象。
绕开使用koa的response处理是不支持的。避免使用下面的node属性。

res.statusCode

res.writeHead()

res.write()

res.end()

ctx.request 一个Koa的request对象。

ctx.response 一个Koa的response对象。

ctx.state
推荐的通过中间件传递信息给前端view（显示）的命名空间。

ctx.app 应用实例的引用。

ctx.cookies.get(name,[options])
通过options获得cookie名字。

signed 要求cookie已经签名。
koa使用cookie模块，这里只是传入选项即可。

ctx.coolies.set(name,value,[options])
使用options设置name的值value。

signed 签名cookie的值。

expires 使cookie的有效期到期。

path cookie路径，默认/。

domain cookie域

secure 保护coolie

httpOnly 服务器端cookie，默认值true。
通过设置options来使用cookie模块。

ctx.throw([msg],[status],[properties])
处理抛出错误的辅助方法，默认.status的值为500时抛出，koa在返回的信息中适当处理。限免的组合也是可疑的。

this.throw(403);

this.throw("name require", 400);

this.throw(400,"name require");

this.throw("something exploded");

例如：this.throw("name require", 400)等于

var err = new Error("name require");
err.status = 400;
throw err;

注意这些是用户自定义的错误，使用err.expose发出。因此只适合某些客户端的反馈。这些错误不同于内置的错误信息提醒，因为错误的详细信息不会泄露。

你也许传递一个properties选项对象，他和原来的错误信息进行了整合，对于人性化体验很有帮助，它报告个给请求者一个回溯流（upsteam）。

this.throw(401,"access_denied",{user:user});
this.throw("access_denied",{user:user});

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

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

跑出错误辅助方法，类似`.throw()`，当`!value`是类似node的`assert()`方法。

this.assert(this.sate.user,401,"User not found, Please login!");

koa使用http-assert实现断言(assertions)

ctx.response
通过绕开koa内置的返回处理(response handling)，你可以明确的设置this.response = false;如果你想使用原生的res对象处理而不是koa的response处理，那么就使用它。

注意那种用法koa不支持。这也许会打断koa中间件本来的功能，或者koa也被打断。使用这个属性最好考虑一下hack，这是使用传统的fn(req,res)方法和koa中间件的唯一方便的方法。

请求别名Request aliases
下面的访问起和Request别名相等。

ctx.header

ctx.headers

ctx.method

ctx.method=

ctx.url

ctx.url=

ctx.originalUrl

ctx.origin

ctx.href

ctx.path

ctx.query

ctx.query=

ctx.querystring

ctx.querystring=

ctx.host

ctx.hostname

ctx.fresh

ctx.stale

ctx.socket

ctx.protocol

ctx.secure

ctx.ip

ctx.ips

ctx.subdomains

ctx.is()

ctx.accepts()

ctx.acceptsEncodings()

ctx.acceptsCharsets()

ctx.acceptsLanguages()

ctx.get()

返回别名Response aliases
下面的访问起和返回别名相等

ctx.body

ctx.body=

ctx.status

ctx.status=

ctx.message

ctx.message=

ctx.length=

ctx.length

ctx.type

ctx.type=

ctx.handerSent

ctx.redirect()

ctx.attachment()

ctx.set()

ctx.append()

ctx.remove()

ctx.lastModified=

ctx.etag=

一个koa请求Request对象是个建立在node请求request之上的抽象。提供了一些额外的功能，这对每个http服务器开发者来说非常有用。

request.header

Request header 对象

request.headers

Requests header 对象,别名`request.header`。

request.method

request.method

request.method=

设置request method，实现中间件很有用，例如`methodoverride()`。

request.length

返回request Content-lenght值是数字或者undefined。

request.url

返回rquest URL

request.url=

设置rquest URL，重写url时有用。

request.originalUrl

返回request 原始 URL

request.orgin

得到URL的域，包括协议和host（主机号）。

this.request.origin
//=>http://example.com

request.href

返回全部request URL,包括协议，主机号，和url。

this.request.href
//=>http://example.com/foo/bar?q=1

request.path

返回路径名（pathname）。

request.path=

设置请求路径名字，保存查询参数

rquest.querystring

得到原始的查询参数，不包含`?`。

request.querystring=

设置原始的查询参数。

request.search

得到原始的查询字符，带`?`。

request.search=

设置原始的查询字符。

rquest.host

得到主机号（hostname:port）当呈现时。支持`X-Forwarded-Host`当`app.proxy`是true，否则是常用的`host`。

request.hostname

当有时返回hostname，支持`X-Frowarded-Host`当`app.proxy`是true，否则是常用的。

request.type

返回request的`Content-type`，无效的一些参数，如`charset`。

var ct = this.request.type.
//=>"image/png"

request.charset

当有时返回request的charset，或者`undefined`。

this.request.charset
//=>"utf-8"

request.query

返回解析过的查询字符query-string，如果没有则返回一个空对象。注意，这个getter不支持嵌套的解析nested parsing。例如：`color=blue&size=small`。

{
    color:"blue",
    size:"small"
}

request.query=
设置查询字符query-string到给定的对象。注意给设置setter不支持嵌套对象。

this.query = {next:"/login"};

request.fresh

检查请求缓存是否“刷新fresh”，或者内容是否发生改变。这个方法是为了`if-None-Match`和`if-Modified-Since`以及`last-modified`之间的缓存沟通。他必须能够引用到更改之后的返回头部response headers

//freshness check requeire stats 20x or 304
this.status = 200;
this.set("ETag","123");

//cache is ok
if(this.fresh) {
    this.status = 304;
    return;
}

//cache is stale
//fetch new data
shis.body = yield db.find("something");

request.stale

与`request.fresh`相反

request.protocol

返回请求协议，`https`或者`http`。支持`X-Forwarded-Proto`当`app.proxy`是true。

request.secure

`this.protocol == "https"`的速记，用以检查一个求情能否通过安全传输层。

request.ip

请求的远程地址。支持`X-Forwarded-For`当`app.proxy`为true。

request.ips

当有`X-Forwarded-For`并且`app.proxy`可用，那么返回这些的ip的一个数组。
从回溯upstream——>downstream预定，当上述不可用则返回一个空数组。

request.subdomains

返回子域数组。
子域是在主域之前的部分，由点`.`分开。默认情况下，应用的主域都被假设成倒数的那两个。可以通过`app.subdomainOffset`来改变。
例如，如果域是`tobi.ferrest.example.com`，并且`app.subdomainOffset`没有设置，那么这个子域是["ferrets","tobi"]。如果设置`app.subdomainOffset`为3，那么子域是["tobi"]。

request.is(type...)

检查接下来的请求是否包含`Content-Type`头部内容，它包含任何的mime类型。如果这里没有请求体，返回undefined。如果没有内容类型，或者匹配失败，返回false。其他的直接返回内容类型（mime）。

//Contetn-type:text/html;charset=utf-8
this.is("html");//=>"html"
this.is("text/html");//=>"text/html"
this.is("text/*", "test/html");//=>"test/html"

//when Content-type is application/json
this.is("json","urlencoded");//=>"json"
this.is("application/json",);//=>"application/json"
this.is("html","application/*",);//=>"application/json"

this.is("html");//=>false

例子：你只想只有图片能够发送到路由

if(this.is("image/*")) {
    //process
}else{
    this.throw(415,"image only!");
}

内容协商 Content Negotiation
koa请求request包含有用的内容写上工具，由accepts和negotaitor支持实现，这些工具是：

request accepts(types)

rquest acceptsEncoding(types)

rquest acceptsCharsets(charsets)

rquest acceptsLanguages(langs)
如果没有提供类型，那么所有可接受的类型将被返回。

如果提供了多个类型，最优匹配奖杯返回。如果没有匹配到，返回false，并且你应该发送406 "Not Acceptable"返回response给客户端。

在可以接受任何类型的地方丢失了accept头部。第一个匹配到的将被返回。因此提供科技收的类型是很重要的。

request.accepts(types)

检查给定的类型是否是可接受的。当为true则返回最佳匹配，否则false。类型`type`的值也许是一个或者多个mime类型字符，例如"application/json",扩展名是"josn"，或者一个数组`["josn","html","text/plain"]`。

//Accept:text/html
this.accepts("html")
//=>"html"

//Accept:text/*, application/json
this.accepts("html")
//=>"html"
this.accepts("json", "text")
//=>"json"
this.accepts("application/json")
//=>"application/json"

//Accept.text/*, application/json
this.accepts("image/png")
this.accepts("png")
//=>false

//Accept:text/*,q=.5, application/json
this.accepts(["html", "json"])
this.accepts("html", "json")
//=>json

//No Accepts header
this.accpts("html", "json")
//=>html
this.accepts("json","html")
//=> json

你也许调用this.accepts()很多次，或者使用switch语句。

switch(this.accepts("json", "html", "text")) {
    case "json": bareak;
    case "html": bareak;
    case "text": bareak;
    default: this.throw(406, "json , html or text only");
}

request.acceptsEncodings(encodings)

检查编码`encodings`是否可接受，true时返回最优匹配，否则返回false。
注意，你应该包含一个`indentity`作为编码`encodings`之一。

//Accept-Encoding:gzip
this.acceptsEncodings("gzip", "deflate", "identify");
//=>gzip

this.acceptsEncodings(["gzip", "deflate", "identify"])
//=>gzip

当没有参数时，所有可接受的编码作为数组元素返回

//Accept-Encoding:gzip, deflate
this.acceptsEncodings();
//=>["gzip","deflate","identify"]

注意如果用户明确发送identify为identify,q=0。虽然这是个特殊例子，你仍然需要处理这个情况，当方法返回false时。

request.acceptsCharsets(charsets)

检查charset是否可接受，为true时返回最优匹配，否则返回false。

//Accept-Charset:utf-8, iso-8859-1;q=0.2,utf-7;q=0.5

this.acceptsCharsets("utf-8","utf-7")
//=>utf-8

this.acceptsCharsets(["utf-7","utf-8"]);
//=>utf-8

如果没有参数是则返回所有可接受的编码到一个数组。

//Accept-Charset:utf-8,iso-8859-1;q=0.2,utf-7;q=0.5
this.acceptsCharsets();
//=>["utf-8","utf-7","iso-8859-7"]

request.acceptLanguages(langs)

检查langs是否可接受，如果为true则返回最有匹配，否则返回false。

//Accept-Language:en;q=0.8,es,pt
this.acceptsLanguages("es","en");
//=>"es"

this.acceptsLanguages(["en","es"]);
//=>"es"

当没有传入参数则返回所有的语言。

//Accept-Language:en;q=0.8, es,pt
this.acceptsLanguages();
//=>["es", "pt", "en"]

request.idempotent

价差请求是否idempotent(幂等)

request.socket

返回请求的socket

request.get(field)

返回请求头header

一个koa返回Response对象是个建立在node请求request之上的抽象。提供了一些额外的功能，这对每个http服务器开发者来说非常有用。

response.header
返回header对象

response。headers
返回header对象。response.header的别名

response.status
返回response的状态，默认情况下response.status没有默认值，而res.statusCode的默认值是200。

response.status =
通过数字设置状态值

100 "continue"继续

101 "switch protocols"换协议

102 "processing"处理中

200 "ok" ok

201 "created"已创建

202 "accepted" 已接受

203 "non-authoritative information"无作者信息

204 "no content" 无内容

205 "reset content" 重置内容

206 "partial content" 部分内容

207 "multi-status" 多状态

300 "multiple choices" 多选择

301 "moved permanently" 移动到永久

302 "moved temporarily" 移动到暂时

303 "see other" 看其他

304 "not modified" 没有改动

305 "use proxy" 使用代理

307 "temporary redirect" 暂时改向

400 "bad request" 坏请求

401 "unauthorized" 未经授权

402 "payment required" 要求付款

403 "forbidden" 禁止

404 "not found" 没有发现

405 "method not allowed" 方法不允许

406 "not acceptable" 不接受

407 "proxy authentication required" 要求代理授权

408 "request time-out" 请求超时

409 "conflict" 冲突

410 "gone" 消失

411 "length required" 要求长度

412 "precondition failed" 预处理失败

413 "request entity too large" 请求量太大

414 "request-uri too large" 请求同意资源太大

415 "unsupported media type" 不支持的媒体类型

416 "requested range not satisfiable" 不满足请求范围

417 "expectation failed" 不是期望值

418 "i"m a teapot" 我是个茶壶？？？

422 "unprocessable entity" 错误实体

423 "locked" 已锁定

424 "failed dependency" 依赖错误

425 "unordered collection" 未预定集合

426 "upgrade required" 要求更新

428 "precondition required" 要求前提

429 "too many requests" 过多请求

431 "request header fields too large" 请求头的域太大

500 "internal server error" 服务器内部错误

501 "not implemented" 没有实现

502 "bad gateway" 网关错误

503 "service unavailable" 不可服务

504 "gateway time-out" 网关超时

505 "http version not supported" http版本不支持

506 "variant also negotiates" 多样协商

507 "insufficient storage" 存储不足

509 "bandwidth limit exceeded" 超过带宽

510 "not extended" 扩展错误

511 "network authentication required" 要求网路授权证明
注意：不要担心要记太多东西，你可以随时查看。

response.message
得到返回状态的信息。默认情况下，response.message是和response.status匹配的。

response.message=
设置返回状态信息。

response.length=
设置内容的长度

response.length
返回内容的长度，或者计算出的this.body的大小。值为数字。或者undifined

response.body
得到response的body。

response.body=
设置返回体(response.body)为如下之一：

String written

Buffer written

Stream piped

Object json-stringified

null no content response

String
Content-type是text/html或者text/plain，charset是utf-8.Content-length也需要设置。
Buffer
Content-type是application/octet-stream,Content-length也要设置。
Stream
Content-type是application/octet-stream.
Object
Content-type是application/json.

response.get(field)
得到response头部的field的值，不区分大小写。

var etag = this.get("ETag");

response.set(field, value)

设置response头部field的值。

this.set("Cache-control", "no-cache");

response.append(field, value)

给头部添加额为的域和值。

this.append("Link", "");

response.set(fields)

使用对象设置头部的fields

this.set({
    "Etag":"1234",
    "Last-modified":date
});

response.remove(field)

移除头部的某个域。

resposne.type

返回Content-type的类型，没有其他参数——如‘charset’。

var ct = this.type;
//=>image/png

response.type

通过名字或者扩展名设置Content-type

this.type = "text/plain;charset=utf-8";
this.type = "image/png";
this.type=".png";
this.type="png";

注意，每个字符编码charset都是为你选的最合适的，例如response.type="html"，那么默认的字符编码是utf-8,然而明确定义一个完整的类型，如response.type="text/html"，将不会有指定的字符编码。

response.is(type...)

很类似于`this.request.is()`。检查response的类型是否是被支持的类型。这在创建那些对返回进行操作的中间件是非常有用。

示例：这是一个压缩html返回response的中间件，除了stream不被压缩。

var minify = require("html-minifier");

app.use(function *minifyHtml(next){
    yield next;

    if(!this.response.is("html")) return;

    var body = this.body;
    if(!body||body.pipe) return;

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

response.redirect(url, [alt])

把[302]状态码重导向至`url`。
字符串`back`是一个特殊的例子，提供了引用这支持，当引用者不存在或者`/`没有使用。

this.redirect("back");
this.redirect("back","/index.html");
this.redirect("login");
this.redirect("http://google.com");

为了改变默认的状态302,只需在这个状态吗出现之前或者出现之后进行重导向即可。为了改变body，在其调用之后进行重定向。

this.status = 301;
this.redirect("/cart");
this.body = "Redirecting to shopping cart";

response.attachment([filename])

设置`Content-disposition`为"attachment"为客户端发出下载的信号。
文件的名字是可以指定的。

response.headerSent

检查返回头response header是否早已发送。查看客户端是否通知错误信号非常有用。

response.lastModified

返回`Last-Modified`最后修改头部的数据（如果存在）。

response.LastModified=

设置`Last-Modified`头部为一个合适的UTC（国际标准时间）字符串。你也可以设置其为一个日期或者日期字符串。

this.response.lastModified = new Date();

response.etag=

设置ETag到一个返回中，包括外面的双引号。注意，这里没有相应的response.etag的getter。

this.response.etag = crypto.createHash("md5"),update(this.body).digest("hex");

response.vary(field)
激活field。