Response

res对象表示Express应用收到HTTP请求时发送的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. })

res对象是Node自己的响应对象的增强版本,并支持所有内置字段和方法

属性

res.app

此属性保存对使用中间件的Express应用程序实例的引用。
res.app与请求对象中的req.app属性相同。

res.headersSent

布尔属性,指示应用程序是否为响应发送了HTTP标头。

  1. app.get('/', function (req, res) {
  2. console.dir(res.headersSent) // false
  3. res.send('OK')
  4. console.dir(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. })

方法

res.append(field [, value])

res.append() Express v4.11.0 +支持

将指定的内容附加value到HTTP响应标头field。如果标题尚未设置,它将创建具有指定值的标题。该value参数可以是字符串或数组。
注意:res.set()在之后调用res.append()将重置先前设置的标头值。

  1. res.append('Link', ['<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标头字段设置为“附件”。如果filename给出a,则它通过扩展名基于Content-Type进行res.type()设置,并设置Content-Disposition“ filename =”参数。

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

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

将cookie设置namevalue。所述value参数可以是转换为JSON字符串或对象。
options参数是可以具有以下属性的对象。

属性 类型 描述
domain String Cookie的域名。默认为应用程序的域名。
encode Function 用于cookie值编码的同步函数。默认为encodeURIComponent
expires Date Cookie在GMT中的到期日期。如果未指定或设置为0,则创建会话cookie。
httpOnly Number 将Cookie标记为只能由Web服务器访问。
maxAge 方便的选项,用于设置相对于当前时间的到期时间(以毫秒为单位)。
path String Cookie的路径。默认为“ /”。
secure Boolean 将cookie标记为仅与HTTPS一起使用。
signed Boolean 指示是否应该对cookie进行签名。
sameSite Boolean或String “ SameSite” Set-Cookie属性的值。有关更多信息,请参见https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1.1

所有res.cookie()操作都是Set-Cookie使用提供的选项设置HTTP 标头。未指定的任何选项默认为RFC 6265中规定的值。

例如:

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

您可以通过res.cookie多次调用在单个响应中设置多个Cookie ,例如:

res
  .status(201)
  .cookie('access_token', 'Bearer ' + token, {
    expires: new Date(Date.now() + 8 * 3600000) // cookie will be removed after 8 hours
  })
  .cookie('test', 'test')
  .redirect(301, '/admin')

encode选项允许您选择用于cookie值编码的函数。不支持异步功能。
用例示例:您需要为组织中的另一个站点设置一个域范围的cookie。该其他站点(不受您的管理控制)不使用URI编码的cookie值。

// Default encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com' })
// Result: 'some_cross_domain_cookie=http%3A%2F%2Fmysubdomain.example.com; Domain=example.com; Path=/'
// Custom encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com', encode: String })
// Result: 'some_cross_domain_cookie=http://mysubdomain.example.com; Domain=example.com; Path=/;'

maxAge选项是用于设置相对于当前时间(以毫秒为单位)的“到期时间”的便捷选项。以下等效于上面的第二个示例。

res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })

您可以传递一个对象作为value参数。然后将其序列化为JSON并由bodyParser()中间件进行解析。

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

使用cookie解析器中间件时,此方法还支持签名的cookie。只需将signed选项设置为即可true。然后res.cookie()将使用传递的秘密cookieParser(secret)对值进行签名。

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

稍后,您可以通过req.signedCookie对象访问此值。

res.clearCookie(name [, options])

清除由指定的Cookie name。有关该options对象的详细信息,请参见res.cookie()

仅当给options定的与res.cookie()相同的Web浏览器和其他兼容客户端才会清除cookie ,但不包括 expiresmaxAge

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

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

optionsExpress v4.16.0及更高版本支持可选参数。

path以“附件”的形式传输文件。通常,浏览器会提示用户下载。默认情况下,Content-Disposition标头“ filename =”参数是path(通常显示在浏览器对话框中)。使用filename参数覆盖此默认值。
当发生错误或传输完成时,该方法将调用可选的回调函数fn。此方法使用res.sendFile()传输文件。
可选options参数传递给基础的res.sendFile() 调用,并采用完全相同的参数。

res.download('/report-12345.pdf')
res.download('/report-12345.pdf', 'report.pdf')
res.download('/report-12345.pdf', 'report.pdf', function (err) {
  if (err) {
    // Handle error, but keep in mind the response may be partially-sent
    // so check res.headersSent
  } else {
    // decrement a download credit, etc.
  }
})

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

结束响应过程。该方法实际上来自Node核心,特别是http.ServerResponseresponse.end()方法
用于快速结束响应,而无需任何数据。如果您需要用数据响应,请使用诸如res.send()res.json()之类的方法

res.end()
res.status(404).end()

res.format(object)

Accept如果存在,则对请求对象上的HTTP标头执行内容协商。它使用req.accepts()为请求选择处理程序,基于它们的质量值排序的可接受类型。如果未指定头,则调用第一个回调。如果找不到匹配项,服务器将以406“不可接受”进行响应,或调用default回调。
Content-Type当选择一个回调响应首部设置。但是,您可以使用res.set()或方法在回调中更改此设置res.type()
以下示例将{ "message": "hey" }Accept标头字段设置为“ application / json”或“ / json” 时做出响应(但是,如果它是“ / *”,则响应将为“ hey”)。

res.format({
  'text/plain': function () {
    res.send('hey')
  },
  'text/html': function () {
    res.send('<p>hey</p>')
  },
  'application/json': function () {
    res.send({ message: 'hey' })
  },
  default: function () {
    // log the request and respond with 406
    res.status(406).send('Not Acceptable')
  }
})

除了规范化的MIME类型之外,您还可以使用映射到这些类型的扩展名来实现稍微冗长的实现:

res.format({
  text: function () {
    res.send('hey')
  },
  html: function () {
    res.send('<p>hey</p>')
  },
  json: function () {
    res.send({ message: 'hey' })
  }
})

res.get(field)

返回由指定的HTTP响应标头field。匹配不区分大小写。

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

res.json([body])

发送JSON响应。此方法发送响应(具有正确的内容类型),该响应是使用JSON.stringify()转换为JSON字符串的参数。
该参数可以是任何JSON类型,包括对象,数组,字符串,布尔值,数字或null,并且您还可以使用它将其他值转换为JSON。

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

res.jsonp([body])

发送带有JSONP支持的JSON响应。此方法与相同res.json(),除了它选择加入JSONP回调支持。

res.jsonp(null)
// => callback(null)
res.jsonp({ user: 'tobi' })
// => callback({ "user": "tobi" })
res.status(500).jsonp({ error: 'message' })
// => callback({ "error": "message" })

默认情况下,JSONP回调名称为simple callback。使用jsonp回调名称设置覆盖此 设置。
以下是使用相同代码的JSONP响应的一些示例:

// ?callback=foo
res.jsonp({ user: 'tobi' })
// => foo({ "user": "tobi" })
app.set('jsonp callback name', 'cb')
// ?cb=foo
res.status(500).jsonp({ error: 'message' })
// => foo({ "error": "message" })

res.links(links)

加入links提供的作为参数的属性,以填充响应的 LinkHTTP标头字段。
例如,以下调用:

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

产生以下结果:

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

res.location(path)

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

res.location('/foo/bar')
res.location('http://example.com')
res.location('back')

path“背”的值具有特殊的含义,它指的是在指定的URL Referer的请求的报头中。如果Referer未指定头,则引用“ /”。

对URL进行编码后,如果尚未进行编码,则Express会在Location不进行任何验证的情况下将指定的URL传递到标头中的浏览器。 浏览器负责从当前URL或引用URL以及Location标头中指定的URL派生预期URL 。并相应地重定向用户。

res.redirect([status,] path)

重定向到从指定的派生的URL path(指定status的正整数),该整数与HTTP状态码相对应。如果未指定,则status默认为“ 302“找到””。

res.redirect('/foo/bar')
res.redirect('http://example.com')
res.redirect(301, 'http://example.com')
res.redirect('../login')

重定向可以是用于重定向到其他站点的标准URL:

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

重定向可以相对于主机名的根。例如,如果应用程序打开[http://example.com/admin/post/new](http://example.com/admin/post/new),则以下内容将重定向到URL [http://example.com/admin](http://example.com/admin)

res.redirect('/admin')

重定向可以相对于当前URL。例如,从[http://example.com/blog/admin/](http://example.com/blog/admin/)(注意结尾的斜杠),以下内容将重定向到URL [http://example.com/blog/admin/post/new](http://example.com/blog/admin/post/new)

res.redirect('post/new')

post/new从重定向到[http://example.com/blog/admin](http://example.com/blog/admin)(不带斜杠),将重定向到[http://example.com/blog/post/new](http://example.com/blog/post/new)
如果您发现上述行为令人困惑,请将路径段视为目录(带有斜杠)和文件,这将变得有意义。
相对路径重定向也是可能的。如果您在 [http://example.com/admin/post/new](http://example.com/admin/post/new),则以下内容将重定向到 [http://example.com/admin/post](http://example.com/admin/post)

res.redirect('..')

一个back重定向请求重定向回引荐,默认为/引荐丢失时。

res.redirect('back')

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

呈现a view并将呈现的HTML字符串发送到客户端。可选参数:

  • locals,是一个对象,其属性定义了视图的局部变量。
  • callback,一个回调函数。如果提供,该方法将返回可能的错误和呈现的字符串,但不会执行自动响应。发生错误时,该方法在next(err)内部调用。

view参数是一个字符串,它是视图文件来渲染的文件路径。这可以是绝对路径,也可以是相对于views设置的路径。如果路径不包含文件扩展名,则该view engine设置确定文件扩展名。如果路径中确实包含文件扩展名,则Express将(通过require())为指定的模板引擎加载模块,并使用加载的模块的__express功能对其进行呈现。
有关更多信息,请参阅将模板引擎与Express结合使用
注意:view参数执行文件系统操作,例如从磁盘读取文件并评估Node.js模块,因此出于安全原因,不应包含最终用户的输入。

局部变量cache启用视图缓存。将其设置为true,以在开发期间缓存视图;默认情况下,生产中启用了视图缓存。

// send the rendered view to the client
res.render('index')
// if a callback is specified, the rendered HTML string has to be sent explicitly
res.render('index', function (err, html) {
  res.send(html)
})
// pass a local variable to the view
res.render('user', { name: 'Tobi' }, function (err, html) {
  // ...
})

res.send([body])

发送HTTP响应。
所述body参数可以是一个Buffer对象,一个String,对象,BooleanArray。例如:

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

此方法对简单的非流式响应执行许多有用的任务:例如,它自动分配Content-LengthHTTP响应标头字段(除非先前定义),并提供自动的HEAD和HTTP缓存新鲜度支持。
当参数是一个Buffer对象时,该方法将Content-Type 响应头字段设置为“ application / octet-stream”,除非事先定义如下:

res.set('Content-Type', 'text/html')
res.send(Buffer.from('<p>some html</p>'))

当参数为时String,该方法将设置Content-Type为“ text / html”:

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

当参数为Array或时Object,Express将以JSON表示形式响应:

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

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

res.sendFile() Express v4.8.0及更高版本受支持。

在给定的位置传输文件pathContent-Type根据文件名的扩展名设置响应HTTP标头字段。除非root在options对象中设置了选项,path否则必须是文件的绝对路径。

该API提供对正在运行的文件系统上的数据的访问。确保(a)如果path参数包含用户输入,则将参数构造为绝对路径的方法是安全的;或者(b)将root选项设置为包含访问权限的目录的绝对路径。 当root被提供的选项,所述path参数被允许是相对路径,包括含有..。Express将验证所提供的相对路径path是否可以在给定的root选项内解析。

下表提供了有关该options参数的详细信息。

属性 描述 默认 可用性
maxAge Cache-Control以毫秒为单位设置标头的max-age属性,或以ms格式设置字符串 0
root 相对文件名的根目录。
lastModified Last-Modified标头设置为操作系统上文件的最后修改日期。设置false为禁用它。 Enabled 4.9.0+
headers 包含要与文件一起使用的HTTP标头的对象。
dotfiles 用于提供点文件的选项。可能的值为“允许”,“拒绝”,“忽略”。 “ignore”
acceptRanges 启用或禁用接受远程请求。 true 4.14+
cacheControl 启用或禁用设置Cache-Control响应头。 true 4.14+
immutable immutableCache-Control响应头中启用或禁用指令。如果启用,maxAge还应指定该选项以启用缓存。该immutable指令将阻止受支持的客户端在maxAge选项有效期内提出条件请求,以检查文件是否已更改。 false 4.16+

fn(err)传输完成或发生错误时,该方法将调用回调函数。如果指定了回调函数并且发生错误,则回调函数必须通过结束请求-响应周期或将控制权传递到下一条路由来显式处理响应过程。
这是使用res.sendFile其所有参数的示例。

app.get('/file/:name', function (req, res, next) {
  var options = {
    root: path.join(__dirname, 'public'),
    dotfiles: 'deny',
    headers: {
      'x-timestamp': Date.now(),
      'x-sent': true
    }
  }
  var fileName = req.params.name
  res.sendFile(fileName, options, function (err) {
    if (err) {
      next(err)
    } else {
      console.log('Sent:', fileName)
    }
  })
})

以下示例说明了如何使用 res.sendFile来提供对文件的细粒度支持:

app.get('/user/:uid/photos/:file', function (req, res) {
  var uid = req.params.uid
  var file = req.params.file
  req.user.mayViewFilesFrom(uid, function (yes) {
    if (yes) {
      res.sendFile('/uploads/' + uid + '/' + file)
    } else {
      res.status(403).send("Sorry! You can't see that.")
    }
  })
})

有关更多信息,或者如果您有任何问题或疑虑,请参阅发送

res.sendStatus(statusCode)

将响应HTTP状态代码设置为statusCode,并将其字符串表示形式发送为响应主体。

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

如果指定了不受支持的状态代码,则HTTP状态仍设置为,statusCode并且该代码的字符串版本作为响应正文发送。
res.statusCode设置为无效的HTTP状态代码(超出的范围100599),将抛出某些版本的Node.js。请查阅HTTP服务器文档以获取所使用的Node.js版本。

res.sendStatus(9999) // equivalent to res.status(9999).send('9999')

有关HTTP状态代码的更多信息

res.set(field [, value])

将响应的HTTP标头设置fieldvalue。要一次设置多个字段,请传递一个对象作为参数。

res.set('Content-Type', 'text/plain')
res.set({
  'Content-Type': 'text/plain',
  'Content-Length': '123',
  ETag: '12345'
})

别名为res.header(field [, value])

res.status(code)

设置响应的HTTP状态。它是Node的response.statusCode的可链接别名。

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

res.type(type)

Content-TypeHTTP标头设置为mime.lookup()为指定的MIME类型 type。如果type包含“ /”字符,则将其设置Content-Typetype

res.type('.html')
// => 'text/html'
res.type('html')
// => 'text/html'
res.type('json')
// => 'application/json'
res.type('application/json')
// => 'application/json'
res.type('png')
// => 'image/png'

res.vary(field)

将字段添加到Vary响应头(如果尚未存在)。

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