Koa 框架

Koa是一个类似于Express的Web开发框架,开发人员也是同一组人,但是使用了Generator函数,进行了架构的重新设计。也就是说,Koa的原理和内部结构很像Express,但是语法和内部结构进行了升级。

官方faq有这样一个问题:”为什么koa不是Express 4.0?“,回答是这样的:”Koa与Express有很大差异,整个设计都是不同的,所以如果将Express 3.0按照这种写法升级到4.0,就意味着重写整个程序。所以,我们觉得创造一个新的库,是更合适的做法。“

Koa应用

一个Koa应用就是一个对象,包含了一个middleware数组,这个数组由一组Generator函数组成。这些函数负责对HTTP请求进行各种加工,比如生成缓存、指定代理、请求重定向等等。

var koa = require('koa');
var app = koa();

app.use(function *(){
  this.body = 'Hello World';
});

app.listen(3000);

上面代码中,变量app就是一个Koa应用。它监听3000端口,返回一个内容为Hello World的网页。

app.use方法用于向middleware数组添加Generator函数。

listen方法指定监听端口,并启动当前应用。它实际上等同于下面的代码。

var http = require('http');
var koa = require('koa');
var app = koa();
http.createServer(app.callback()).listen(3000);

中间件

Koa的中间件很像Express的中间件,也是对HTTP请求进行处理的函数,但是必须是一个Generator函数。而且,Koa的中间件是一个级联式(Cascading)的结构,也就是说,属于是层层调用,第一个中间件调用第二个中间件,第二个调用第三个,以此类推。上游的中间件必须等到下游的中间件返回结果,才会继续执行,这点很像递归。

中间件通过当前应用的use方法注册。

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

上面代码中,app.use方法的参数就是中间件,它是一个Generator函数,最大的特征就是function命令与参数之间,必须有一个星号。Generator函数的参数next,表示下一个中间件。

Generator函数内部使用yield命令,将程序的执行权转交给下一个中间件,即yield next,要等到下一个中间件返回结果,才会继续往下执行。上面代码中,Generator函数体内部,第一行赋值语句首先执行,开始计时,第二行yield语句将执行权交给下一个中间件,当前中间件就暂停执行。等到后面的中间件全部执行完成,执行权就回到原来暂停的地方,继续往下执行,这时才会执行第三行,计算这个过程一共花了多少时间,第四行将这个时间打印出来。

下面是一个两个中间件级联的例子。

app.use(function *() {
  this.body = "header\n";
  yield saveResults.call(this);
  this.body += "footer\n";
});

function *saveResults() {
  this.body += "Results Saved!\n";
}

上面代码中,第一个中间件调用第二个中间件saveResults,它们都向this.body写入内容。最后,this.body的输出如下。

header
Results Saved!
footer

只要有一个中间件缺少yield next语句,后面的中间件都不会执行,这一点要引起注意。

app.use(function *(next){
  console.log('>> one');
  yield next;
  console.log('<< one');
});

app.use(function *(next){
  console.log('>> two');
  this.body = 'two';
  console.log('<< two');
});

app.use(function *(next){
  console.log('>> three');
  yield next;
  console.log('<< three');
});

上面代码中,因为第二个中间件少了yield next语句,第三个中间件并不会执行。

如果想跳过一个中间件,可以直接在该中间件的第一行语句写上return yield next

app.use(function* (next) {
  if (skip) return yield next;
})

由于Koa要求中间件唯一的参数就是next,导致如果要传入其他参数,必须另外写一个返回Generator函数的函数。

function logger(format) {
  return function *(next){
    var str = format
      .replace(':method', this.method)
      .replace(':url', this.url);

    console.log(str);

    yield next;
  }
}

app.use(logger(':method :url'));

上面代码中,真正的中间件是logger函数的返回值,而logger函数是可以接受参数的。

多个中间件的合并

由于中间件的参数统一为next(意为下一个中间件),因此可以使用.call(this, next),将多个中间件进行合并。

function *random(next) {
  if ('/random' == this.path) {
    this.body = Math.floor(Math.random()*10);
  } else {
    yield next;
  }
};

function *backwards(next) {
  if ('/backwards' == this.path) {
    this.body = 'sdrawkcab';
  } else {
    yield next;
  }
}

function *pi(next) {
  if ('/pi' == this.path) {
    this.body = String(Math.PI);
  } else {
    yield next;
  }
}

function *all(next) {
  yield random.call(this, backwards.call(this, pi.call(this, next)));
}

app.use(all);

上面代码中,中间件all内部,就是依次调用random、backwards、pi,后一个中间件就是前一个中间件的参数。

Koa内部使用koa-compose模块,进行同样的操作,下面是它的源码。

function compose(middleware){
  return function *(next){
    if (!next) next = noop();

    var i = middleware.length;

    while (i--) {
      next = middleware[i].call(this, next);
    }

    yield *next;
  }
}

function *noop(){}

上面代码中,middleware是中间件数组。前一个中间件的参数是后一个中间件,依次类推。如果最后一个中间件没有next参数,则传入一个空函数。

路由

可以通过this.path属性,判断用户请求的路径,从而起到路由作用。

app.use(function* (next) {
  if (this.path === '/') {
    this.body = 'we are at home!';
  }
})

// 等同于

app.use(function* (next) {
  if (this.path !== '/') return yield next;
  this.body = 'we are at home!';
})

下面是多路径的例子。

let koa = require('koa')

let app = koa()

// normal route
app.use(function* (next) {
  if (this.path !== '/') {
    return yield next
  }

  this.body = 'hello world'
});

// /404 route
app.use(function* (next) {
  if (this.path !== '/404') {
    return yield next;
  }

  this.body = 'page not found'
});

// /500 route
app.use(function* (next) {
  if (this.path !== '/500') {
    return yield next;
  }

  this.body = 'internal server error'
});

app.listen(8080)

上面代码中,每一个中间件负责一个路径,如果路径不符合,就传递给下一个中间件。

复杂的路由需要安装koa-router插件。

var app = require('koa')();
var Router = require('koa-router');

var myRouter = new Router();

myRouter.get('/', function *(next) {
  this.response.body = 'Hello World!';
});

app.use(myRouter.routes());

app.listen(3000);

上面代码对根路径设置路由。

Koa-router实例提供一系列动词方法,即一种HTTP动词对应一种方法。典型的动词方法有以下五种。

  • router.get()
  • router.post()
  • router.put()
  • router.del()
  • router.patch()

这些动词方法可以接受两个参数,第一个是路径模式,第二个是对应的控制器方法(中间件),定义用户请求该路径时服务器行为。

router.get('/', function *(next) {
  this.body = 'Hello World!';
});

上面代码中,router.get方法的第一个参数是根路径,第二个参数是对应的函数方法。

注意,路径匹配的时候,不会把查询字符串考虑在内。比如,/index?param=xyz匹配路径/index

有些路径模式比较复杂,Koa-router允许为路径模式起别名。起名时,别名要添加为动词方法的第一个参数,这时动词方法变成接受三个参数。

router.get('user', '/users/:id', function *(next) {
 // ...
});

上面代码中,路径模式\users\:id的名字就是user。路径的名称,可以用来引用对应的具体路径,比如url方法可以根据路径名称,结合给定的参数,生成具体的路径。

router.url('user', 3);
// => "/users/3"

router.url('user', { id: 3 });
// => "/users/3"

上面代码中,user就是路径模式的名称,对应具体路径/users/:id。url方法的第二个参数3,表示给定id的值是3,因此最后生成的路径是/users/3

Koa-router允许为路径统一添加前缀。

var router = new Router({
  prefix: '/users'
});

router.get('/', ...); // 等同于"/users"
router.get('/:id', ...); // 等同于"/users/:id"

路径的参数通过this.params属性获取,该属性返回一个对象,所有路径参数都是该对象的成员。

// 访问 /programming/how-to-node
router.get('/:category/:title', function *(next) {
  console.log(this.params);
  // => { category: 'programming', title: 'how-to-node' }
});

param方法可以针对命名参数,设置验证条件。

router
  .get('/users/:user', function *(next) {
    this.body = this.user;
  })
  .param('user', function *(id, next) {
    var users = [ '0号用户', '1号用户', '2号用户'];
    this.user = users[id];
    if (!this.user) return this.status = 404;
    yield next;
  })

上面代码中,如果/users/:user的参数user对应的不是有效用户(比如访问/users/3),param方法注册的中间件会查到,就会返回404错误。

redirect方法会将某个路径的请求,重定向到另一个路径,并返回301状态码。

router.redirect('/login', 'sign-in');

// 等同于
router.all('/login', function *() {
  this.redirect('/sign-in');
  this.status = 301;
});

redirect方法的第一个参数是请求来源,第二个参数是目的地,两者都可以用路径模式的别名代替。

context对象

中间件当中的this表示上下文对象context,代表一次HTTP请求和回应,即一次访问/回应的所有信息,都可以从上下文对象获得。context对象封装了request和response对象,并且提供了一些辅助方法。每次HTTP请求,就会创建一个新的context对象。

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对应于ctx.response.type和ctx.response.length,ctx.path和ctx.method对应于ctx.request.path和ctx.request.method。

context对象的全局属性。

  • request:指向Request对象
  • response:指向Response对象
  • req:指向Node的request对象
  • req:指向Node的response对象
  • app:指向App对象
  • state:用于在中间件传递信息。
this.state.user = yield User.find(id);

上面代码中,user属性存放在this.state对象上面,可以被另一个中间件读取。

context对象的全局方法。

  • throw():抛出错误,直接决定了HTTP回应的状态码。
  • assert():如果一个表达式为false,则抛出一个错误。
this.throw(403);
this.throw('name required', 400);
this.throw('something exploded');

this.throw(400, 'name required');
// 等同于
var err = new Error('name required');
err.status = 400;
throw err;

assert方法的例子。

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

// 例子
this.assert(this.user, 401, 'User not found. Please login!');

以下模块解析POST请求的数据。

var parse = require('co-body');

// in Koa handler
var body = yield parse(this);

错误处理机制

Koa提供内置的错误处理机制,任何中间件抛出的错误都会被捕捉到,引发向客户端返回一个500错误,而不会导致进程停止,因此也就不需要forever这样的模块重启进程。

app.use(function *() {
  throw new Error();
});

上面代码中,中间件内部抛出一个错误,并不会导致Koa应用挂掉。Koa内置的错误处理机制,会捕捉到这个错误。

当然,也可以额外部署自己的错误处理机制。

app.use(function *() {
  try {
    yield saveResults();
  } catch (err) {
    this.throw(400, '数据无效');
  }
});

上面代码自行部署了try...catch代码块,一旦产生错误,就用this.throw方法抛出。该方法可以将指定的状态码和错误信息,返回给客户端。

对于未捕获错误,可以设置error事件的监听函数。

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

error事件的监听函数还可以接受上下文对象,作为第二个参数。

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

如果一个错误没有被捕获,koa会向客户端返回一个500错误“Internal Server Error”。

this.throw方法用于向客户端抛出一个错误。

this.throw(403);
this.throw('name required', 400);
this.throw(400, 'name required');
this.throw('something exploded');

this.throw('name required', 400)
// 等同于
var err = new Error('name required');
err.status = 400;
throw err;

this.throw方法的两个参数,一个是错误码,另一个是报错信息。如果省略状态码,默认是500错误。

this.assert方法用于在中间件之中断言,用法类似于Node的assert模块。

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

上面代码中,如果this.user属性不存在,会抛出一个401错误。

由于中间件是层级式调用,所以可以把try { yield next }当成第一个中间件。

app.use(function *(next) {
  try {
    yield next;
  } catch (err) {
    this.status = err.status || 500;
    this.body = err.message;
    this.app.emit('error', err, this);
  }
});

app.use(function *(next) {
  throw new Error('some error');
})

cookie的读取和设置。

this.cookies.get('view');
this.cookies.set('view', n);

get和set方法都可以接受第三个参数,表示配置参数。其中的signed参数,用于指定cookie是否加密。如果指定加密的话,必须用app.keys指定加密短语。

app.keys = ['secret1', 'secret2'];
this.cookies.set('name', '张三', { signed: true });

this.cookie的配置对象的属性如下。

  • signed:cookie是否加密。
  • expires:cookie何时过期
  • path:cookie的路径,默认是“/”。
  • domain:cookie的域名。
  • secure:cookie是否只有https请求下才发送。
  • httpOnly:是否只有服务器可以取到cookie,默认为true。

session

var session = require('koa-session');
var koa = require('koa');
var app = koa();

app.keys = ['some secret hurr'];
app.use(session(app));

app.use(function *(){
  var n = this.session.views || 0;
  this.session.views = ++n;
  this.body = n + ' views';
})

app.listen(3000);
console.log('listening on port 3000');

Request对象

Request对象表示HTTP请求。

(1)this.request.header

返回一个对象,包含所有HTTP请求的头信息。它也可以写成this.request.headers

(2)this.request.method

返回HTTP请求的方法,该属性可读写。

(3)this.request.length

返回HTTP请求的Content-Length属性,取不到值,则返回undefined。

(4)this.request.path

返回HTTP请求的路径,该属性可读写。

(5)this.request.href

返回HTTP请求的完整路径,包括协议、端口和url。

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

(6)this.request.querystring

返回HTTP请求的查询字符串,不含问号。该属性可读写。

(7)this.request.search

返回HTTP请求的查询字符串,含问号。该属性可读写。

(8)this.request.host

返回HTTP请求的主机(含端口号)。

(9)this.request.hostname

返回HTTP的主机名(不含端口号)。

(10)this.request.type

返回HTTP请求的Content-Type属性。

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

(11)this.request.charset

返回HTTP请求的字符集。

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

(12)this.request.query

返回一个对象,包含了HTTP请求的查询字符串。如果没有查询字符串,则返回一个空对象。该属性可读写。

比如,查询字符串color=blue&size=small,会得到以下的对象。

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

(13)this.request.fresh

返回一个布尔值,表示缓存是否代表了最新内容。通常与If-None-Match、ETag、If-Modified-Since、Last-Modified等缓存头,配合使用。

this.response.set('ETag', '123');

// 检查客户端请求的内容是否有变化
if (this.request.fresh) {
  this.response.status = 304;
  return;
}

// 否则就表示客户端的内容陈旧了,
// 需要取出新内容
this.response.body = yield db.find('something');

(14)this.request.stale

返回this.request.fresh的相反值。

(15)this.request.protocol

返回HTTP请求的协议,https或者http。

(16)this.request.secure

返回一个布尔值,表示当前协议是否为https。

(17)this.request.ip

返回发出HTTP请求的IP地址。

(18)this.request.subdomains

返回一个数组,表示HTTP请求的子域名。该属性必须与app.subdomainOffset属性搭配使用。app.subdomainOffset属性默认为2,则域名“tobi.ferrets.example.com”返回["ferrets", "tobi"],如果app.subdomainOffset设为3,则返回["tobi"]。

(19)this.request.is(types...)

返回指定的类型字符串,表示HTTP请求的Content-Type属性是否为指定类型。

// Content-Type为 text/html; charset=utf-8
this.request.is('html'); // 'html'
this.request.is('text/html'); // 'text/html'
this.request.is('text/*', 'text/html'); // 'text/html'

// Content-Type为s application/json
this.request.is('json', 'urlencoded'); // 'json'
this.request.is('application/json'); // 'application/json'
this.request.is('html', 'application/*'); // 'application/json'

如果不满足条件,返回false;如果HTTP请求不含数据,则返回undefined。

this.is('html'); // false

它可以用于过滤HTTP请求,比如只允许请求下载图片。

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

(20)this.request.accepts(types)

检查HTTP请求的Accept属性是否可接受,如果可接受,则返回指定的媒体类型,否则返回false。

// Accept: text/html
this.request.accepts('html');
// "html"

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

// Accept: text/*, application/json
this.request.accepts('image/png');
this.request.accepts('png');
// false

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

// No Accept header
this.request.accepts('html', 'json');
// "html"
this.request.accepts('json', 'html');
// => "json"

如果accepts方法没有参数,则返回所有支持的类型(text/html,application/xhtml+xml,image/webp,application/xml,/)。

如果accepts方法的参数有多个参数,则返回最佳匹配。如果都不匹配则返回false,并向客户端抛出一个406”Not Acceptable“错误。

如果HTTP请求没有Accept字段,那么accepts方法返回它的第一个参数。

accepts方法可以根据不同Accept字段,向客户端返回不同的字段。

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

(21)this.request.acceptsEncodings(encodings)

该方法根据HTTP请求的Accept-Encoding字段,返回最佳匹配,如果没有合适的匹配,则返回false。

// Accept-Encoding: gzip
this.request.acceptsEncodings('gzip', 'deflate', 'identity');
// "gzip"
this.request.acceptsEncodings(['gzip', 'deflate', 'identity']);
// "gzip"

注意,acceptEncodings方法的参数必须包括identity(意为不编码)。

如果HTTP请求没有Accept-Encoding字段,acceptEncodings方法返回所有可以提供的编码方法。

// Accept-Encoding: gzip, deflate
this.request.acceptsEncodings();
// ["gzip", "deflate", "identity"]

如果都不匹配,acceptsEncodings方法返回false,并向客户端抛出一个406“Not Acceptable”错误。

(22)this.request.acceptsCharsets(charsets)

该方法根据HTTP请求的Accept-Charset字段,返回最佳匹配,如果没有合适的匹配,则返回false。

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

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

如果acceptsCharsets方法没有参数,则返回所有可接受的匹配。

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

如果都不匹配,acceptsCharsets方法返回false,并向客户端抛出一个406“Not Acceptable”错误。

(23)this.request.acceptsLanguages(langs)

该方法根据HTTP请求的Accept-Language字段,返回最佳匹配,如果没有合适的匹配,则返回false。

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

如果acceptsCharsets方法没有参数,则返回所有可接受的匹配。

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

如果都不匹配,acceptsLanguages方法返回false,并向客户端抛出一个406“Not Acceptable”错误。

(24)this.request.socket

返回HTTP请求的socket。

(25)this.request.get(field)

返回HTTP请求指定的字段。

Response对象

Response对象表示HTTP回应。

(1)this.response.header

返回HTTP回应的头信息。

(2)this.response.socket

返回HTTP回应的socket。

(3)this.response.status

返回HTTP回应的状态码。默认情况下,该属性没有值。该属性可读写,设置时等于一个整数。

(4)this.response.message

返回HTTP回应的状态信息。该属性与this.response.message是配对的。该属性可读写。

(5)this.response.length

返回HTTP回应的Content-Length字段。该属性可读写,如果没有设置它的值,koa会自动从this.request.body推断。

(6)this.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(表示没有信息体)

如果this.response.status没设置,Koa会自动将其设为200或204。

(7)this.response.get(field)

返回HTTP回应的指定字段。

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

注意,get方法的参数是区分大小写的。

(8)this.response.set()

设置HTTP回应的指定字段。

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

set方法也可以接受一个对象作为参数,同时为多个字段指定值。

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

(9)this.response.remove(field)

移除HTTP回应的指定字段。

(10)this.response.type

返回HTTP回应的Content-Type字段,不包括“charset”参数的部分。

var ct = this.reponse.type;
// "image/png"

该属性是可写的。

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

设置type属性的时候,如果没有提供charset参数,Koa会判断是否自动设置。如果this.response.type设为html,charset默认设为utf-8;但如果this.response.type设为text/html,就不会提供charset的默认值。

(10)this.response.is(types...)

该方法类似于this.request.is(),用于检查HTTP回应的类型是否为支持的类型。

它可以在中间件中起到处理不同格式内容的作用。

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

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

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

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

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

上面代码是一个中间件,如果输出的内容类型为HTML,就会进行最小化处理。

(11)this.response.redirect(url, [alt])

该方法执行302跳转到指定网址。

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

如果redirect方法的第一个参数是back,将重定向到HTTP请求的Referrer字段指定的网址,如果没有该字段,则重定向到第二个参数或“/”网址。

如果想修改302状态码,或者修改body文字,可以采用下面的写法。

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

(12)this.response.attachment([filename])

该方法将HTTP回应的Content-Disposition字段,设为“attachment”,提示浏览器下载指定文件。

(13)this.response.headerSent

该方法返回一个布尔值,检查是否HTTP回应已经发出。

(14)this.response.lastModified

该属性以Date对象的形式,返回HTTP回应的Last-Modified字段(如果该字段存在)。该属性可写。

this.response.lastModified = new Date();

(15)this.response.etag

该属性设置HTTP回应的ETag字段。

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

注意,不能用该属性读取ETag字段。

(16)this.response.vary(field)

该方法将参数添加到HTTP回应的Vary字段。

CSRF攻击

CSRF攻击是指用户的session被劫持,用来冒充用户的攻击。

koa-csrf插件用来防止CSRF攻击。原理是在session之中写入一个秘密的token,用户每次使用POST方法提交数据的时候,必须含有这个token,否则就会抛出错误。

var koa = require('koa');
var session = require('koa-session');
var csrf = require('koa-csrf');
var route = require('koa-route');

var app = module.exports = koa();

app.keys = ['session key', 'csrf example'];
app.use(session(app));

app.use(csrf());

app.use(route.get('/token', token));
app.use(route.post('/post', post));

function* token () {
  this.body = this.csrf;
}

function* post() {
  this.body = {ok: true};
}

app.listen(3000);

POST请求含有token,可以是以下几种方式之一,koa-csrf插件就能获得token。

  • 表单的_csrf字段
  • 查询字符串的_csrf字段
  • HTTP请求头信息的x-csrf-token字段
  • HTTP请求头信息的x-xsrf-token字段

数据压缩

koa-compress模块可以实现数据压缩。

app.use(require('koa-compress')())
app.use(function* () {
  this.type = 'text/plain'
  this.body = fs.createReadStream('filename.txt')
})

源码解读

每一个网站就是一个app,它由lib/application定义。

function Application() {
  if (!(this instanceof Application)) return new Application;
  this.env = process.env.NODE_ENV || 'development';
  this.subdomainOffset = 2;
  this.middleware = [];
  this.context = Object.create(context);
  this.request = Object.create(request);
  this.response = Object.create(response);
}

var app = Application.prototype;

exports = module.exports = Application;

app.use()用于注册中间件,即将Generator函数放入中间件数组。

app.use = function(fn){
  if (!this.experimental) {
    // es7 async functions are allowed
    assert(fn && 'GeneratorFunction' == fn.constructor.name, 'app.use() requires a generator function');
  }
  debug('use %s', fn._name || fn.name || '-');
  this.middleware.push(fn);
  return this;
};

app.listen()就是http.createServer(app.callback()).listen(...)的缩写。

app.listen = function(){
  debug('listen');
  var server = http.createServer(this.callback());
  return server.listen.apply(server, arguments);
};

app.callback = function(){
  var mw = [respond].concat(this.middleware);
  var fn = this.experimental
    ? compose_es7(mw)
    : co.wrap(compose(mw));
  var self = this;

  if (!this.listeners('error').length) this.on('error', this.onerror);

  return function(req, res){
    res.statusCode = 404;
    var ctx = self.createContext(req, res);
    onFinished(res, ctx.onerror);
    fn.call(ctx).catch(ctx.onerror);
  }
};

上面代码中,app.callback()会返回一个函数,用来处理HTTP请求。它的第一行mw = [respond].concat(this.middleware),表示将respond函数(这也是一个Generator函数)放入this.middleware,现在mw就变成了[respond, S1, S2, S3]

compose(mw)将中间件数组转为一个层层调用的Generator函数。

function compose(middleware){
  return function *(next){
    if (!next) next = noop();

    var i = middleware.length;

    while (i--) {
      next = middleware[i].call(this, next);
    }

    yield *next;
  }
}

function *noop(){}

上面代码中,下一个generator函数总是上一个Generator函数的参数,从而保证了层层调用。

var fn = co.wrap(gen)则是将Generator函数包装成一个自动执行的函数,并且返回一个Promise。

//co package
co.wrap = function (fn) {
  return function () {
    return co.call(this, fn.apply(this, arguments));
  };
};

由于co.wrap(compose(mw))执行后,返回的是一个Promise,所以可以对其使用catch方法指定捕捉错误的回调函数fn.call(ctx).catch(ctx.onerror)

将所有的上下文变量都放进context对象。

app.createContext = function(req, res){
  var context = Object.create(this.context);
  var request = context.request = Object.create(this.request);
  var response = context.response = Object.create(this.response);
  context.app = request.app = response.app = this;
  context.req = request.req = response.req = req;
  context.res = request.res = response.res = res;
  request.ctx = response.ctx = context;
  request.response = response;
  response.request = request;
  context.onerror = context.onerror.bind(context);
  context.originalUrl = request.originalUrl = req.url;
  context.cookies = new Cookies(req, res, this.keys);
  context.accept = request.accept = accepts(req);
  context.state = {};
  return context;
};

真正处理HTTP请求的是下面这个Generator函数。

function *respond(next) {
  yield *next;

  // allow bypassing koa
  if (false === this.respond) return;

  var res = this.res;
  if (res.headersSent || !this.writable) return;

  var body = this.body;
  var code = this.status;

  // ignore body
  if (statuses.empty[code]) {
    // strip headers
    this.body = null;
    return res.end();
  }

  if ('HEAD' == this.method) {
    if (isJSON(body)) this.length = Buffer.byteLength(JSON.stringify(body));
    return res.end();
  }

  // status body
  if (null == body) {
    this.type = 'text';
    body = this.message || String(code);
    this.length = Buffer.byteLength(body);
    return res.end(body);
  }

  // responses
  if (Buffer.isBuffer(body)) return res.end(body);
  if ('string' == typeof body) return res.end(body);
  if (body instanceof Stream) return body.pipe(res);

  // body: json
  body = JSON.stringify(body);
  this.length = Buffer.byteLength(body);
  res.end(body);
}

参考链接