Koa2 —（1）

1、Koa2 简介

  Koa 应用是一个包含一系列中间件 async/await 函数的对象。这些中间件函数基于 request 请求以一个类似于栈的结构组成并依次执行。Koa 的核心设计思路是为中间层提供高级语法糖封装，以增强其相互性和健壮性，并使编写中间件变得相当有趣。
  Koa 包含了像 content-negotiation（内容协商）、cache-freshness（缓存刷新）、proxy support（代理支持）和redirection（重定向）等常用的任务方法。与提供庞大函数支持不同，Koa 只包含很小一部分，因为 Koa 并不绑定任何中间件。

特性：

• 只提供封装好的 HTTP 上下文、请求、响应、以及基于 async/await 的中间件容器。
• 利用 async/await 来处理传统回调嵌套问题和代替 Koa1 的 Generator ，但需要在 node 版本为 7.6+。
• 中间件只支持 async/await 封装的，如果要使用 Generator 中间件，则需要通过中间件 koa-convert 封装后才可使用。

2、基本用法

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

app.use(async (ctx, next) => {
  ctx.response.body = 'Hello world';
});
app.listen(3000);

如上，通过 require 或者 import 加载 koa 模块，然后新建 koa 是实例对象，通过实例对象的 listen 即可监听 HTTP 端口。

（1）app.listen(…)
  app.listen() 方法用于绑定监听端口。
  Koa 应用并非是一个 一对一 表征关系的 HTTP 服务器。一个或多个 Koa 应用可以被挂载到一起组成一个包含单一 HTTP 服务器的大型应用群。

app.listen(3000)
相当于
var http = require('http');
http.createServer(app.callback()).listen(3000);

这意味着可以同时支持 HTTP 和 HTTPS，或者在多个端口监听同一个应用。

http.creatServer(app.callback()).listen(3001);
http.creatServer(app.callback()).listen(3000);

（2）app.callback()
  返回一个适合 http.creatServer() 方法的回调函数用来处理。

（3）app.use(function)
  为应用添加指定的中间件。

（4）app.keys=
  设置签名 Cookie 密钥，该密钥会传递给 KeyGrip。

（5）错误处理
  默认情况下 Koa 会将所有错误信息输出到 stderr，除非 NODE_ENV 是 “test”。为了实现自定义错误处理逻辑，应该添加 error 事件监听。

app.on('error',(err, ctx) => {
    console.error("server error", err, ctx)
})

  如果错误发生在 请求/响应 环节，并且其不能够响应客户端时，Context 实例也会被传到 error 事件监听器的回调函数里。
  当发生错误但仍能响应客户端时（比如没有数据写到 socket中），Koa 会返回一个 500 错误。
  无论哪种情况，Koa 都会生成一个应用级别的错误信息，以便实现日记记录等目的。

3、Context 对象

  Koa 提供一个 Context 对象，表示一次对话的上下文（包括 HTTP 请求和 HTTP 回复）。通过加工这个对象，就可以控制返回给用户的内容。

Context 对象的全局属性：

• request： 指向 Request 对象
• response： 指向 response 对象
• req：指向 Node 的 request 对象
• res：指向 Node 的response 对象
• app：指向 App 对象
• state：用于在中间件传递消息

Context 对象的全局方法

• throw()：抛出错误，直接决定了 HTTP 回应的状态码
• assert()：如果一个表达式为 false ，则抛出一个错误，该方法用于在中间件之间断言。

throw() 方法可接受两个参数，一个是错误码，一个是报错信息。如果省略状态码，默认是 500 错误。

ctx.throw(400);
ctx.throw('err');
ctx.throw('err',400);
ctx.throw(400,'err);
// 等同于 
var err = new Error('err');
srr.status = 400;
throw err; 

ctx.assert(this.user, 401, 'user not found.');
如果 this.user 不存在将抛出一个 401 错误。

4、Request 对象

  Request 对象表示 HTTP 请求

• request.header： 返回一个对象，包含所有 HTTP 请求的头部信息。它也可以写成 request.headers
• request.method：返回 HTTP 请求的方法，该属性可读写
• request.length：返回 HTTP 请求的 Content-Length，取不到值则返回 undefined
• request.path：返回 HTTP 请求的路径，该属性可读性
• request.url：返回 HTTP 请求的路径，该属性可读性
• request.href：返回 HTTP 请求的完整路径，包括协议、端口和 URL
• request.querystring：返回 HTTP 请求的查询字符串，不包含问号。该属性可读性
• request.search：返回请求查询字符串，含问号，该属性可读写
• request.host：返回 HTTP 请求的主机（含端口号）
• request.hostname：返回 HTTP 请求的主机（不含端口号）
• request.type：返回 HTTP 请求的 Content-Type 属性
• request.charset：返回 HTTP 请求的字符集
• request.query：返回一个对象，包含了 HTTP 请求的查询字符集。如果没有查询字符集，则返回一个空对象。该属性可读写
• request.fresh：返回一个布尔值，表示缓存是否代表了最新内容。通常与 if-None-Match、ETag、if-Modified-Since、Last-Modified 等缓存头配合使用
• request.stale： 返回 request.fresh 的相反值
• request.protocol：返回 HTTP 请求的协议，https 或 http
• request.secure：返回一个布尔值，表示当前协议是否为 https
• request.ip：返回发出 HTTP 请求的 IP 地址
• request.subdomains：返回一个数组，表示 HTTP 请求的子域名
• request.is(types…)：返回指定的类型字符串，表示 HTTP 请求的 Content-type 属性是否为指定类型（满足条件则返回字符串，如果不满足返回false，如果 HTTP 请求不含数据，则返回 undefined）可用于过滤请求
• request.accepts(types)：检查 HTTP 请求的 Accept 属性是否可接受，如果可接受，则返回指定的媒体类型，否则返回 false。如果 accepts 方法没有参数，则返回所有支持的类型
• request.acceptsEncodings(encodings)：根据 HTTP 请求的 Accept-Encoding 字段，返回最佳匹配，如果没有合适的匹配，则返回 false
• request.acceptsCharsets：根据 HTTP 请求的 Accept-Charset 字段，返回最佳匹配，如果没有合适的匹配，则返回 false
• request.acceptsLanguages(langs)：根据 HTTP 请求的 Accept-Language 字段，返回最佳匹配，如果没有合适的，则返回 false
• request.socket：返回 HTTP 请求的 socket
• request.get(field)：返回 HTTP 请求指定的字段

5、Response 对象

• response.header：返回 HTTP 响应的头部信息
• response.socket：返回 HTTP 响应的 socket
• response.status：返回 HTTP 响应的状态码。默认情况下，该属性没有值。该属性可读写，设置是等于一个整数
• response.message：返回 HTTP 响应的状态信息。该属性与 response.status 是配对的。该属性可读写
• response.body：返回 HTTP 响应的信息体，该属性可读写，它的值可能有以下类型：
  
  • 字符串：Content-Type 字段默认为 text/html 或 text/plain，字符集默认为 utf-8， Content-Length 字段同时设定
  • 二进制 Buffer：Content-type 字段默认为 application/octet-stream，Content-Length 字段同时设定
  • Stream：Content-type 字段默认为 application/octet-stream
  • JSON 对象：Content-type 字段默认为 application/json
  • null（表示没有信息体）
• response.get(field)：返回 HTTP 响应的指定字段，（参数区分大小写）
• response.set()：设置 HTTP 响应的指定字段
• response.remove(field)：移除 HTTP 响应的指定字段
• response.type：返回 HTTP 响应的 Content-type 字段，不包括 charset 参数的部分，该属性可读写
• response.is(types…)：该方法类似于 request.is() ，用于检查 HTTP 响应的类型是否为支持的类型
• response.redorect(url,[alt])：该方法执行 302 跳转到指定网址，如果该方法的第一参数是 back ，将重定向到 HTTP 请求的 Referrer 字段指定的网址，如果没有该字段，则重定向到第二个参数或“/”网址
• response.headerSent：返回一个布尔值，检查是否 HTTP 响应已发出
• response.attachment([filename])：该方法将HTTP回应的Content-Disposition字段，设为“attachment”，提示浏览器下载指定文件
• response.lastModified：该属性以Date对象的形式，返回HTTP回应的Last-Modified字段（如果该字段存在）。该属性可写。
• response.etag：该属性设置响应的 ETag 字段，注意不能用该属性读取 ETag 字段
• response.vary(field)：该方法将参数添加到 HTTP 响应的 Vary 字段