Koa

koa

次世代nodejs 的 web框架

简介

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

环境(Context)

一个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=

请求 Request

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

API

• 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
  返回子域数组。