🔥码云GVP开源项目 12k star Uniapp+ElementUI 功能强大 支持多语言、二开方便! 广告
Koa是一个类似于Express的Web开发框架,开发人员也是同一组人,但是使用了Generator函数,进行了架构的重新设计。也就是说,Koa的原理和内部结构很像Express,但是语法和内部结构进行了升级。 官方[faq](https://github.com/koajs/koa/blob/master/docs/faq.md#why-isnt-koa-just-express-40)有这样一个问题:”为什么koa不是Express 4.0?“,回答是这样的:”Koa与Express有很大差异,整个设计都是不同的,所以如果将Express 3.0按照这种写法升级到4.0,就意味着重写整个程序。所以,我们觉得创造一个新的库,是更合适的做法。“ [TOC] ## 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请求的数据。 * co-body * [https://github.com/koajs/body-parser](https://github.com/koajs/body-parser) * [https://github.com/koajs/body-parsers](https://github.com/koajs/body-parsers) ~~~ 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 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); } ~~~ ## 参考链接 * [Koa Guide](https://github.com/koajs/koa/blob/master/docs/guide.md) * William XING, [Is Koa.js right for me?](http://william.xingyp.com/is-koa-js-right-for-me/)