Response

res对象代表了当一个HTTP请求到来时，Express程序返回的HTTP响应。在本文档中，按照惯例，这个对象总是简称为res(http请求简称为req)，但是它们实际的名字由这个回调方法在那里使用时的参数决定。
例如：

  1. app.get('/user/:id', function(req, res) {
  2.     res.send('user' + req.params.id);
  3. });

这样写也是一样的：

  1. app.get('/user/:id', function(request, response) {
  2.     response.send('user' + request.params.id);
  3. });

Properties

res.app

这个属性持有express程序实例的一个引用，其可以在中间件中使用。
res.app和请求对象中的req.app属性是相同的。

res.headersSent

布尔类型的属性，指示这个响应是否已经发送HTTP头部。

  1. app.get('/', function(req, res) {
  2.     console.log(res.headersSent); // false
  3.     res.send('OK'); // send之后就发送了头部
  4.     console.log(res.headersSent); // true
  5. });

res.locals

一个对象，其包含了响应的能够反应出请求的本地参数和因此只提供给视图渲染，在请求响应的周期内(如果有的话)—我要翻译吐了。否则，其和app.locals是一样的。(不知道翻译的什么…)
这个参数在导出请求级别的信息是很有效的，这些信息比如请求路径，已认证的用户，用户设置等等。

  1. app.use(function(req, res, next) {
  2.     res.locals.user = req.user;
  3.     res.locals.authenticated = !req.user.anonymous;
  4.     next();
  5. });

Methods

res.append(field [, value])

res.append()方法在Expresxs4.11.0以上版本才支持。

在指定的field的HTTP头部追加特殊的值value。如果这个头部没有被设置，那么将用value新建这个头部。value可以是一个字符串或者数组。
注意：在res.append()之后调用app.set()函数将重置前面设置的值。

  1. res.append('Lind', ['<http://localhost>', '<http://localhost:3000>']);
  2. res.append('Set-Cookie', 'foo=bar;Path=/;HttpOnly');
  3. res.append('Warning', '199 Miscellaneous warning');

res.attachment([filename])

设置HTTP响应的Content-Disposition头内容为”attachment”。如果提供了filename，那么将通过res.type()获得扩展名来设置Content-Type，并且设置Content-Disposition内容为”filename=”parameter。

  1. res.attachment();
  2. // Content-Disposition: attachment
  4. res.attachment('path/to/logo.png');
  5. // Content-Disposition: attachment; filename="logo.png"
  6. // Content-Type: image/png

res.cookie(name, value [,options])

设置name和value的cookie，value参数可以是一串字符或者是转化为json字符串的对象。
options是一个对象，其可以有下列的属性。
|属性|类型|描述|
|:—-:|:—-:|:—-:|
|domain|String|设置cookie的域名。默认是你本app的域名。|
|expires|Date|cookie的过期时间，GMT格式。如果没有指定或者设置为0，则产生新的cookie。|
|httpOnly|Boolean|这个cookie只能被web服务器获取的标示。|
|maxAge|String|是设置过去时间的方便选项，其为过期时间到当前时间的毫秒值。|
|path|String|cookie的路径。默认值是/。|
|secure|Boolean|标示这个cookie只用被HTTPS协议使用。|
|signed|Boolean|指示这个cookie应该是签名的。|

res.cookie()所作的都是基于提供的options参数来设置Set-Cookie头部。没有指定任何的options，那么默认值在RFC6265中指定。

使用实例：

  1. res.cookie('name', 'tobi', {'domain':'.example.com', 'path':'/admin', 'secure':true});
  2. res.cookie('remenberme', '1', {'expires':new Date(Date.now() + 90000), 'httpOnly':true});

maxAge是一个方便设置过期时间的方便的选项，其以当前时间开始的毫秒数来计算。下面的示例和上面的第二条功效一样。

  1. res.cookie('rememberme', '1', {'maxAge':90000}, "httpOnly":true);

你可以设置传递一个对象作为value的参数。然后其将被序列化为Json字符串，被bodyParser()中间件解析。

  1. res.cookie('cart', {'items':[1, 2, 3]});
  2. res.cookie('cart', {'items':[1, 2, 3]}, {'maxAge':90000});

当我们使用cookie-parser中间件的时候，这个方法也支持签名的cookie。简单地，在设置options时包含signed选项为true。然后res.cookie()将使用传递给cookieParser(secret)的密钥来签名这个值。

  1. res.cookie('name', 'tobi', {'signed':true});

res.clearCookie(name [,options])

根据指定的name清除对应的cookie。更多关于options对象可以查阅res.cookie()。

  1. res.cookie('name', 'tobi', {'path':'/admin'});
  2. res.clearCookie('name', {'path':'admin'});

res.download(path, [,filename], [,fn])

传输path指定文件作为一个附件。通常，浏览器提示用户下载。默认情况下，Content-Disposition头部”filename=”的参数为path(通常会出现在浏览器的对话框中)。通过指定filename参数来覆盖默认值。
当一个错误发生时或者传输完成，这个方法将调用fn指定的回调方法。这个方法使用res.sendFile()来传输文件。

  1. res.download('/report-12345.pdf');
  3. res.download('/report-12345.pdf', 'report.pdf');
  5. res.download('report-12345.pdf', 'report.pdf', function(err) {
  6. // Handle error, but keep in mind the response may be partially-sent
  7. // so check res.headersSent
  8. if (err) {
  9. } else {
  10. // decrement a download credit, etc.
  11. }
  12. });

res.end([data] [, encoding])

结束本响应的过程。这个方法实际上来自Node核心模块，具体的是response.end() method of http.ServerResponse。
用来快速结束请求，没有任何的数据。如果你需要发送数据，可以使用res.send()和res.json()这类的方法。

  1. res.end();
  2. res.status(404).end();

res.format(object)

进行内容协商，根据请求的对象中AcceptHTTP头部指定的接受内容。它使用req.accepts()来选择一个句柄来为请求服务，这些句柄按质量值进行排序。如果这个头部没有指定，那么第一个方法默认被调用。当不匹配时，服务器将返回406“Not Acceptable”，或者调用default回调。
Content-Type请求头被设置，当一个回调方法被选择。然而你可以改变他，在这个方法中使用这些方法，比如res.set()或者res.type()。
下面的例子，将回复{"message":"hey"}，当请求的对象中Accept头部设置成”application/json”或者”/json”(不过如果是`/*`，然后这个回复就是”hey”)。

  1. res.format({
  2.     'text/plain':function() {
  3.         res.send('hey')'
  4.     },
  5.     'text/html':function() {
  6.         res.send('<p>hey</p>');
  7.     },
  8.     'application/json':function() {
  9.         res.send({message:'hey'});
  10.     },
  11.     'default':function() {
  12.         res.status(406).send('Not Acceptable');
  13.     }
  14. })

除了规范化的MIME类型之外，你也可以使用拓展名来映射这些类型来避免冗长的实现：

  1. res.format({
  2.     text:function() {
  3.         res.send('hey');
  4.     },
  5.     html:function() {
  6.         res.send('<p>hey</p>');
  7.     },
  8.     json:function() {
  9.         res.send({message:'hey'});
  10.     }
  11. })

res.get(field)

返回field指定的HTTP响应的头部。匹配是区分大小写。

  1. res.get('Content-Type');
  2. // => "text/plain"

res.json([body])

发送一个json的响应。这个方法和将一个对象或者一个数组作为参数传递给res.send()方法的效果相同。不过，你可以使用这个方法来转换其他的值到json，例如null，undefined。(虽然这些都是技术上无效的JSON)。

  1. res.json(null);
  2. res.json({user:'tobi'});
  3. res.status(500).json({error:'message'});

res.jsonp([body])

发送一个json的响应，并且支持JSONP。这个方法和res.json()效果相同，除了其在选项中支持JSONP回调。

  1. res.jsonp(null)
  2. // => null
  4. res.jsonp({user:'tobi'})
  5. // => {"user" : "tobi"}
  7. res.status(500).jsonp({error:'message'})
  8.  // => {"error" : "message"}

默认情况下，jsonp的回调方法简单写作callback。可以通过jsonp callback name设置来重写它。
下面是一些例子使用JSONP响应，使用相同的代码:

  1. // ?callback=foo
  2. res.jsonp({user:'tobo'})
  3. // => foo({"user":"tobi"})
  5. app.set('jsonp callback name', 'cb')
  7. // ?cb=foo
  8. res.status(500).jsonp({error:'message'})
  9. // => foo({"error":"message"})

res.links(links)

连接这些links，links是以传入参数的属性形式提供，连接之后的内容用来填充响应的Link HTTP头部。

  1. res.links({
  2.     next:'http://api.example.com/users?page=2',
  3.     last:'http://api.example.com/user?page=5'
  4. });

效果：

  1. Link:<http://api.example.com/users?page=2>;rel="next",
  2. <http://api.example.com/users?page=5>;rel="last"

res.location(path)

设置响应的LocationHTTP头部为指定的path参数。

  1.     res.location('/foo/bar');
  2.     res.location('http://example.com');
  3.     res.location('back');

当path参数为back时，其具有特殊的意义，其指定URL为请求对象的Referer头部指定的URL。如果请求中没有指定，那么其即为”/“。

Express传递指定的URL字符串作为回复给浏览器响应中的Location头部的值，不检测和操作，除了当是back这个case时。浏览器有推导预期URL从当前的URL或者指定的URL，和在Location指定的URL的责任；相应地重定向它。(我也不知道翻译的什么…)

res.redirect([status,] path)

重定向来源于指定path的URL，以及指定的HTTP status codestatus。如果你没有指定status，status code默认为”302 Found”。

  1. res.redirect('/foo/bar');
  2. res.redirect('http://example.com');
  3. res.redirect(301, 'http://example.com');
  4. res.redirect('../login');

重定向也可以是完整的URL，来重定向到不同的站点。

  1. res.redirect('http://google.com');

重定向也可以相对于主机的根路径。比如，如果程序的路径为http://example.com/admin/post/new，那么下面将重定向到http://example.com/admim:

  1. res.redirect('/admin');

重定向也可以相对于当前的URL。比如，来之于http://example.com/blog/admin/(注意结尾的/)，下面将重定向到http://example.com/blog/admin/post/new。

  1. res.redirect('post/new');

如果来至于http://example.com/blog/admin（没有尾部/），重定向post/new，将重定向到http://example.com/blog/post/new。如果你觉得上面很混乱，可以把路径段认为目录(有’/‘)或者文件，这样是可以的。相对路径的重定向也是可以的。如果你当前的路径为http://example.com/admin/post/new，下面的操作将重定向到http://example.com/admin/post：

  1. res.redirect('..');

back将重定向请求到referer，当没有referer的时候，默认为/。

  1. res.redirect('back');

res.render(view [, locals] [, callback])

渲染一个视图，然后将渲染得到的HTML文档发送给客户端。可选的参数为:

  • locals，定义了视图本地参数属性的一个对象。
  • callback，一个回调方法。如果提供了这个参数，render方法将返回错误和渲染之后的模板，并且不自动发送响应。当有错误发生时，可以在这个回调内部，调用next(err)方法。

本地变量缓存使能视图缓存。在开发环境中缓存视图，需要手动设置为true；视图缓存在生产环境中默认开启。

  2. // send the rendered view to the client
  3. res.render('index');
  5. // if a callback is specified, the render HTML string has to be sent explicitly
  7. res.render('index', function(err, html) {
  8.     res.send(html);
  9. });
  11. // pass a local variable to  the view
  12. res.render('user', {name:'Tobi'}, function(err, html) {
  13.     // ...
  14. });

res.send([body])

发送HTTP响应。
body参数可以是一个Buffer对象，一个字符串，一个对象，或者一个数组。比如：

  1. res.send(new Buffer('whoop'));
  2. res.send({some:'json'});
  3. res.send('<p>some html</p>');
  4. res.status(404).send('Sorry, we cannot find that!');
  5. res.status(500).send({ error: 'something blew up' });

对于一般的非流请求，这个方法可以执行许多有用的的任务：比如，它自动给Content-LengthHTTP响应头赋值(除非先前定义)，也支持自动的HEAD和HTTP缓存更新。
当参数是一个Buffer对象，这个方法设置Content-Type响应头为application/octet-stream，除非事先提供，如下所示:

  1. res.set('Content-Type', 'text/html');
  2. res.send(new Buffer('<p>some html</p>'));

当参数是一个字符串，这个方法设置Content-Type响应头为text/html：

  1. res.send('<p>some html</p>');

当参数是一个对象或者数组，Express使用JSON格式来表示：

  1. res.send({user:'tobi'});
  2. res.send([1, 2, 3]);

res.sendFile(path [, options] [, fn])

res.sendFile()从Express v4.8.0开始支持。

传输path指定的文件。根据文件的扩展名设置Content-TypeHTTP头部。除非在options中有关于root的设置，path一定是关于文件的绝对路径。
下面的表提供了options参数的细节:
|属性|描述|默认值|可用版本|
|:—-:|:—-:|:—-:|:—-:|
|maxAge|设置Cache-Control的max-age属性，格式为毫秒数，或者是ms format的一串字符串|0||
|root|相对文件名的根目录|||
|lastModified|设置Last-Modified头部为此文件在系统中的最后一次修改时间。设置false来禁用它|Enable|4.9.0+|
|headers|一个对象，包含了文件所在的sever的HTTP头部。(不知道怎么翻译了)|||
|dotfiles|是否支持点开头文件名的选项。可选的值”allow”,”deny”,”ignore”|”ignore”||

当传输完成或者发生了什么错误，这个方法调用fn回调方法。如果这个回调参数指定了和一个错误发生，回调方法必须明确地通过结束请求-响应循环或者传递控制到下个路由来处理响应过程。
下面是使用了所有参数的使用res.sendFile()的例子：

  1. app.get('/file/:name', function(req, res, next) {
  3.     var options = {
  4.         root:__dirname + '/public',
  5.         dotfile:'deny',
  6.         headers:{
  7.             'x-timestamp':Date.now(),
  8.             'x-sent':true
  9.         }
  10.     };
  12.     var fileName = req.params.name;
  13.     res.sendFile(fileName, options, function(err) {
  14.         if (err) {
  15.             console.log(err);
  16.             res.status(err.status).end();
  17.         }
  18.         else {
  19.             console.log('sent', fileName);
  20.         }
  21.     });
  25. });

res.sendFile提供了文件服务的细粒度支持，如下例子说明：

  1. app.get('/user/:uid/photos/:file', function(req, res) {
  2.     var uid = req.params.uid
  3.         , file = req.params.file;
  6.     req.user.mayViewFilesFrom(uid, function(yes) {
  7.         if (yes) {
  8.             res.sendFile('/upload/' + uid + '/' + file);
  9.         }
  10.         else {
  11.             res.status(403).send('Sorry! you cant see that.');
  12.         }
  13.     });
  15. })

获取更多信息，或者你有问题或者关注，可以查阅send。

res.sendStatus(statusCode)

设置响应对象的HTTP status code为statusCode并且发送statusCode的相应的字符串形式作为响应的Body。

  1.     res.sendStatus(200); // equivalent to res.status(200).send('OK');
  2.     res.sendStatus(403); // equivalent to res.status(403).send('Forbidden');
  3.     res.sendStatus(404); // equivalent to res.status(404).send('Not Found');
  4.     res.sendStatus(500); // equivalent to res.status(500).send('Internal Server Error')

如果一个不支持的状态被指定，这个HTTP status依然被设置为statusCode并且用这个code的字符串作为Body。

  1. res.sendStatus(2000); // equivalent to res.status(2000).send('2000');

More about HTTP Status Codes

res.set(field [, value])

设置响应对象的HTTP头部field为value。为了一次设置多个值，那么可以传递一个对象为参数。

  1. res.set('Content-Type', 'text/plain');
  3. res.set({
  4.     'Content-Type':'text/plain',
  5.     'Content-Length':'123',
  6.     'ETag':'123456'
  7. })

其和res.header(field [,value])效果一致。

res.status(code)

使用这个方法来设置响应对象的HTTP status。其是Node中response.statusCode的一个连贯性的别名。

  1. res.status(403).end();
  2. res.status(400).send('Bad Request');
  3. res.status(404).sendFile('/absolute/path/to/404.png');

res.type(type)

设置Content-TypeHTTP头部为MIME type，如果这个指定的type能够被mime.lookup确定。如果type包含/字符，那么设置Content-Type为type(我已经晕了)。

  1. res.type('.html');              // => 'text/html'
  2. res.type('html');               // => 'text/html'
  3. res.type('json');               // => 'application/json'
  4. res.type('application/json');   // => 'application/json'
  5. res.type('png');                // => image/png:

res.vary(field)

设置Vary响应头为field，如果已经不在那里。(不懂什么意思)

  1. res.vary('User-Agent').render('docs');