4.x API

express.json([options])

这是 Express 中的内置中间件函数。它解析具有 JSON 负载的传入请求，并基于 body-parser。

返回仅解析 JSON 且仅查看 Content-Type 标头与 type 选项匹配的请求的中间件。此解析器接受主体任何 Unicode 编码，并支持自动膨胀 gzip 和 deflate 编码。

在中间件之后，在 request 对象上填充一个包含解析数据的新的 body 对象（即 req.body），或者如果没有任何主体要解析，Content-Type 未匹配，或者发生错误，则填充一个空对象 ({})。

下表描述了可选 options 对象的属性。

express.raw([options])

这是 Express 中的内置中间件函数。它将传入的请求有效负载解析为 Buffer，并基于 body-parser。

返回一个中间件，该中间件将所有正文解析为 Buffer，并且仅查看 Content-Type 标头与 type 选项匹配的请求。此解析器接受正文的任何 Unicode 编码，并支持自动膨胀 gzip 和 deflate 编码。

在中间件之后（即 req.body）在 request 对象上填充一个新的 body Buffer，其中包含解析后的数据，或者如果没有任何正文要解析、Content-Type 未匹配或发生错误，则填充一个空对象 ({})。

下表描述了可选 options 对象的属性。

express.Router([options])

创建一个新的 路由器 对象。

var router = express.Router([options])

可选的 options 参数指定路由器的行为。

您可以像应用程序一样向 router 添加中间件和 HTTP 方法路由（例如 get、put、post 等）。

有关更多信息，请参阅 路由器。

express.static(root, [options])

这是 Express 中的内置中间件函数。它提供静态文件，并基于 serve-static。

root 参数指定提供静态资产的根目录。该函数通过将 req.url 与提供的 root 目录组合来确定要提供的文件。如果找不到文件，它不会发送 404 响应，而是调用 next() 以继续执行下一个中间件，从而允许堆叠和回退。

下表描述了 options 对象的属性。另请参阅 下面的示例。

有关更多信息，请参见 在 Express 中提供静态文件 和 使用中间件 - 内置中间件。

dotfiles

此选项的可能值是

• “allow” - 对点文件没有特殊处理。
• “deny” - 拒绝对点文件的请求，以 403 响应，然后调用 next()。
• “ignore” - 就像点文件不存在一样，以 404 响应，然后调用 next()。

注意：使用默认值，它不会忽略以点开头的目录中的文件。

fallthrough

当此选项为 true 时，客户端错误（如错误请求或对不存在文件的请求）将导致此中间件简单地调用 next() 以调用堆栈中的下一个中间件。当为 false 时，这些错误（即使是 404），将调用 next(err)。

将此选项设置为 true，以便您可以将多个物理目录映射到同一个 Web 地址，或者让路由填充不存在的文件。

如果您已将此中间件安装在旨在严格作为单个文件系统目录的路径上，则使用 false，这允许为较少的开销短路 404。此中间件还将回复所有方法。

setHeaders

对于此选项，指定一个函数来设置自定义响应头。对头的更改必须同步发生。

函数的签名是

fn(res, path, stat)

参数

• res，响应对象。
• path，正在发送的文件路径。
• stat，正在发送的文件的 stat 对象。

express.static 的示例

以下是如何使用带有详细选项对象的 express.static 中间件函数的示例

var options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders: function (res, path, stat) {
    res.set('x-timestamp', Date.now())
  }
}

app.use(express.static('public', options))

express.text([options])

这是 Express 中的内置中间件函数。它将传入的请求有效负载解析为字符串，并且基于 body-parser。

返回将所有主体解析为字符串的中间件，并且仅查看 Content-Type 头与 type 选项匹配的请求。此解析器接受主体的任何 Unicode 编码，并支持自动膨胀 gzip 和 deflate 编码。

在中间件之后（即 req.body），request 对象上会填充一个包含解析数据的新的 body 字符串，如果没有任何数据要解析，Content-Type 没有匹配，或者发生了错误，则填充一个空对象 ({})。

下表描述了可选 options 对象的属性。

express.urlencoded([options])

这是 Express 中的内置中间件函数。它解析具有 URL 编码有效负载的传入请求，并且基于 body-parser。

返回仅解析 URL 编码主体且仅查看 Content-Type 标头与 type 选项匹配的请求的中间件。此解析器仅接受主体的 UTF-8 编码，并支持 gzip 和 deflate 编码的自动膨胀。

在中间件之后（即 req.body），request 对象上会填充一个包含解析数据的新的 body 对象，如果没有任何数据要解析，Content-Type 没有匹配，或者发生了错误，则填充一个空对象 ({})。此对象将包含键值对，其中值可以是字符串或数组（当 extended 为 false 时），或任何类型（当 extended 为 true 时）。

下表描述了可选 options 对象的属性。

app.locals

app.locals对象具有作为应用程序中局部变量的属性，并且将在使用res.render渲染的模板中可用。

console.dir(app.locals.title)
// => 'My App'

console.dir(app.locals.email)
// => '[email protected]'

设置后，app.locals属性的值在应用程序的整个生命周期内持续存在，与仅在请求生命周期内有效的res.locals属性形成对比。

您可以在应用程序中渲染的模板中访问局部变量。这对于向模板提供辅助函数以及应用程序级数据很有用。局部变量通过req.app.locals（参见req.app）在中间件中可用。

app.locals.title = 'My App'
app.locals.strftime = require('strftime')
app.locals.email = '[email protected]'

app.mountpath

app.mountpath 属性包含一个或多个用于挂载子应用程序的路径模式。

var express = require('express')

var app = express() // the main app
var admin = express() // the sub app

admin.get('/', function (req, res) {
  console.log(admin.mountpath) // /admin
  res.send('Admin Homepage')
})

app.use('/admin', admin) // mount the sub app

它类似于 req 对象的 baseUrl 属性，不同之处在于 req.baseUrl 返回匹配的 URL 路径，而不是匹配的模式。

如果子应用程序挂载在多个路径模式上，app.mountpath 将返回它所挂载的模式列表，如下例所示。

var admin = express()

admin.get('/', function (req, res) {
  console.dir(admin.mountpath) // [ '/adm*n', '/manager' ]
  res.send('Admin Homepage')
})

var secret = express()
secret.get('/', function (req, res) {
  console.log(secret.mountpath) // /secr*t
  res.send('Admin Secret')
})

admin.use('/secr*t', secret) // load the 'secret' router on '/secr*t', on the 'admin' sub app
app.use(['/adm*n', '/manager'], admin) // load the 'admin' router on '/adm*n' and '/manager', on the parent app

app.on('mount', callback(parent))

当子应用程序挂载到父应用程序上时，将触发 mount 事件。父应用程序将传递给回调函数。

var admin = express()

admin.on('mount', function (parent) {
  console.log('Admin Mounted')
  console.log(parent) // refers to the parent app
})

admin.get('/', function (req, res) {
  res.send('Admin Homepage')
})

app.use('/admin', admin)

app.all(path, callback [, callback ...])

此方法类似于标准的 app.METHOD() 方法，不同之处在于它匹配所有 HTTP 动词。

参数

示例

以下回调函数将针对/secret的请求执行，无论使用 GET、POST、PUT、DELETE 还是任何其他 HTTP 请求方法。

app.all('/secret', function (req, res, next) {
  console.log('Accessing the secret section ...')
  next() // pass control to the next handler
})

app.all() 方法用于为特定路径前缀或任意匹配映射“全局”逻辑。例如，如果您将以下内容放在所有其他路由定义的顶部，它将要求从该点开始的所有路由都需要身份验证，并自动加载用户。请记住，这些回调函数不必充当端点：loadUser 可以执行一项任务，然后调用 next() 以继续匹配后续路由。

app.all('*', requireAuthentication, loadUser)

或等效的

app.all('*', requireAuthentication)
app.all('*', loadUser)

另一个示例是白名单“全局”功能。该示例类似于上面的示例，但它仅限制以“/api”开头的路径。

app.all('/api/*', requireAuthentication)

app.delete(path, callback [, callback ...])

将 HTTP DELETE 请求路由到指定路径，并使用指定的回调函数。有关更多信息，请参阅路由指南。

参数

示例

app.delete('/', function (req, res) {
  res.send('DELETE request to homepage')
})

app.disable(name)

将布尔设置name设置为false，其中name是应用程序设置表中的属性之一。对于布尔属性，调用app.set('foo', false) 等同于调用app.disable('foo')。

例如

app.disable('trust proxy')
app.get('trust proxy')
// => false

app.disabled(name)

如果布尔设置name被禁用（false），则返回true，其中name是应用程序设置表中的属性之一。

app.disabled('trust proxy')
// => true

app.enable('trust proxy')
app.disabled('trust proxy')
// => false

app.enable(name)

将布尔设置name设置为true，其中name是应用程序设置表中的属性之一。对于布尔属性，调用app.set('foo', true) 等同于调用app.enable('foo')。

app.enable('trust proxy')
app.get('trust proxy')
// => true

app.enabled(name)

如果设置name已启用（true），则返回true，其中name是应用程序设置表中的属性之一。

app.enabled('trust proxy')
// => false

app.enable('trust proxy')
app.enabled('trust proxy')
// => true

app.engine(ext, callback)

将给定的模板引擎callback注册为ext。

默认情况下，Express 将根据文件扩展名require() 引擎。例如，如果您尝试渲染“foo.pug”文件，Express 会在内部调用以下内容，并在后续调用中缓存require() 以提高性能。

app.engine('pug', require('pug').__express)

对于没有提供.__express 的引擎，或如果您希望将不同的扩展名映射到模板引擎，请使用此方法。

例如，将 EJS 模板引擎映射到“.html”文件

app.engine('html', require('ejs').renderFile)

在这种情况下，EJS 提供了一个 .renderFile() 方法，它具有与 Express 预期相同的签名：(path, options, callback)，但请注意，它在内部将此方法别名为 ejs.__express，因此如果您使用“.ejs”扩展名，则无需执行任何操作。

一些模板引擎不遵循此约定。该 consolidate.js 库将 Node 模板引擎映射到遵循此约定，因此它们可以与 Express 无缝协作。

var engines = require('consolidate')
app.engine('haml', engines.haml)
app.engine('html', engines.hogan)

app.get(name)

返回 name 应用设置的值，其中 name 是 应用设置表 中的字符串之一。例如

app.get('title')
// => undefined

app.set('title', 'My Site')
app.get('title')
// => "My Site"

app.get(path, callback [, callback ...])

将 HTTP GET 请求路由到指定路径，并使用指定的回调函数。

参数

有关更多信息，请参阅 路由指南。

示例

app.get('/', function (req, res) {
  res.send('GET request to homepage')
})

app.listen(path, [callback])

启动一个 UNIX 套接字并在给定路径上监听连接。此方法与 Node 的 http.Server.listen() 相同。

var express = require('express')
var app = express()
app.listen('/tmp/sock')

app.listen([port[, host[, backlog]]][, callback])

在指定的 host 和 port 上绑定并监听连接。此方法与 Node 的 http.Server.listen() 相同。

如果省略 port 或 port 为 0，操作系统将分配一个任意的未使用端口，这对于自动任务（测试等）很有用。

var express = require('express')
var app = express()
app.listen(3000)

由 express() 返回的 app 实际上是一个 JavaScript Function，旨在传递给 Node 的 HTTP 服务器作为回调来处理请求。这使得使用相同的代码库轻松提供 HTTP 和 HTTPS 版本的应用程序，因为应用程序不会从这些服务器继承（它只是一个回调）。

var express = require('express')
var https = require('https')
var http = require('http')
var app = express()

http.createServer(app).listen(80)
https.createServer(options, app).listen(443)

app.listen() 方法返回一个 http.Server 对象，并且（对于 HTTP）是一个方便的方法，用于以下操作

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

app.METHOD(path, callback [, callback ...])

路由 HTTP 请求，其中 METHOD 是请求的 HTTP 方法，例如 GET、PUT、POST 等，以小写形式表示。因此，实际方法是 app.get()、app.post()、app.put() 等。有关完整列表，请参见下面的 路由方法。

参数

路由方法

Express 支持以下路由方法，对应于同名 HTTP 方法

API 文档中只对最常用的 HTTP 方法 app.get()、app.post()、app.put() 和 app.delete() 有明确的条目。但是，上面列出的其他方法的工作方式完全相同。

要路由转换为无效 JavaScript 变量名的方法，请使用方括号表示法。例如，app['m-search']('/', function ...。

方法 app.all() 不是从任何 HTTP 方法派生的，它在指定路径上为所有 HTTP 请求方法加载中间件。有关更多信息，请参见 app.all。

有关路由的更多信息，请参见 路由指南。

app.param([name], callback)

向 路由参数 添加回调触发器，其中 name 是参数的名称或它们的数组，callback 是回调函数。回调函数的参数依次是请求对象、响应对象、下一个中间件、参数的值和参数的名称。

如果 name 是一个数组，则 callback 触发器将为其中声明的每个参数注册，按照它们声明的顺序。此外，对于除最后一个参数之外的每个声明的参数，回调内部对 next 的调用将调用下一个声明的参数的回调。对于最后一个参数，对 next 的调用将调用当前正在处理的路由的下一个中间件，就像 name 只是一个字符串一样。

例如，当路由路径中存在:user时，您可以将用户加载逻辑映射到自动提供req.user到路由，或对参数输入进行验证。

app.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (err, user) {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

参数回调函数是定义它们的路由的本地函数。它们不会被挂载的应用程序或路由继承。因此，在app上定义的参数回调将仅由app路由上定义的路由参数触发。

所有参数回调将在任何包含该参数的路由的任何处理程序之前被调用，并且它们在一次请求-响应循环中只会被调用一次，即使该参数在多个路由中匹配，如下面的示例所示。

app.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

app.get('/user/:id', function (req, res, next) {
  console.log('although this matches')
  next()
})

app.get('/user/:id', function (req, res) {
  console.log('and this matches too')
  res.end()
})

在GET /user/42上，打印以下内容

CALLED ONLY ONCE
although this matches
and this matches too

app.param(['id', 'page'], function (req, res, next, value) {
  console.log('CALLED ONLY ONCE with', value)
  next()
})

app.get('/user/:id/:page', function (req, res, next) {
  console.log('although this matches')
  next()
})

app.get('/user/:id/:page', function (req, res) {
  console.log('and this matches too')
  res.end()
})

在GET /user/42/3上，打印以下内容

CALLED ONLY ONCE with 42
CALLED ONLY ONCE with 3
although this matches
and this matches too

app.param(name, callback)方法的行为可以通过仅将一个函数传递给app.param()来完全改变。此函数是app.param(name, callback)如何工作的自定义实现 - 它接受两个参数，并且必须返回一个中间件。

此函数的第一个参数是要捕获的 URL 参数的名称，第二个参数可以是任何 JavaScript 对象，它可能用于返回中间件实现。

函数返回的中间件决定了捕获 URL 参数时发生的事情的行为。

在此示例中，app.param(name, callback)签名被修改为app.param(name, accessId)。app.param()现在将接受一个名称和一个数字，而不是接受一个名称和一个回调。

var express = require('express')
var app = express()

// customizing the behavior of app.param()
app.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      next('route')
    }
  }
})

// using the customized app.param()
app.param('id', 1337)

// route to trigger the capture
app.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.listen(3000, function () {
  console.log('Ready')
})

在此示例中，app.param(name, callback)签名保持不变，但自定义数据类型检查函数已定义为验证用户 ID 的数据类型，而不是中间件回调。

app.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      next('route')
    }
  }
})

app.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

// captures '1-a_6' but not '543-azser-sder'
router.get('/[0-9]+-[[\\w]]*', function (req, res, next) { next() })

// captures '1-a_6' and '543-az(ser"-sder' but not '5-a s'
router.get('/[0-9]+-[[\\S]]*', function (req, res, next) { next() })

// captures all (equivalent to '.*')
router.get('[[\\s\\S]]*', function (req, res, next) { next() })

app.path()

返回应用程序的规范路径，一个字符串。

var app = express()
var blog = express()
var blogAdmin = express()

app.use('/blog', blog)
blog.use('/admin', blogAdmin)

console.dir(app.path()) // ''
console.dir(blog.path()) // '/blog'
console.dir(blogAdmin.path()) // '/blog/admin'

此方法的行为在挂载应用程序的复杂情况下可能会变得非常复杂：通常最好使用req.baseUrl来获取应用程序的规范路径。

app.post(path, callback [, callback ...])

将 HTTP POST 请求路由到指定路径，并使用指定的回调函数。有关更多信息，请参阅 路由指南。

参数

示例

app.post('/', function (req, res) {
  res.send('POST request to homepage')
})

app.put(path, callback [, callback ...])

将 HTTP PUT 请求路由到指定路径，并使用指定的回调函数。

参数

示例

app.put('/', function (req, res) {
  res.send('PUT request to homepage')
})

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

通过 callback 函数返回渲染后的视图 HTML。它接受一个可选参数，该参数是一个包含视图局部变量的对象。它类似于 res.render()，但它不能自行将渲染后的视图发送到客户端。

app.render('email', function (err, html) {
  // ...
})

app.render('email', { name: 'Tobi' }, function (err, html) {
  // ...
})

app.route(path)

返回单个路由的实例，然后可以使用它来处理带有可选中间件的 HTTP 动词。使用 app.route() 来避免重复的路由名称（从而避免打字错误）。

var app = express()

app.route('/events')
  .all(function (req, res, next) {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
  })
  .get(function (req, res, next) {
    res.json({})
  })
  .post(function (req, res, next) {
    // maybe add a new event...
  })

app.set(name, value)

将设置 name 赋值为 value。您可以存储任何想要的值，但某些名称可用于配置服务器的行为。这些特殊名称在 应用程序设置表 中列出。

对于布尔属性，调用 app.set('foo', true) 等同于调用 app.enable('foo')。类似地，对于布尔属性，调用 app.set('foo', false) 等同于调用 app.disable('foo')。

使用 app.get() 检索设置的值。

app.set('title', 'My Site')
app.get('title') // "My Site"

应用程序设置

下表列出了应用程序设置。

请注意，子应用程序将

• 不继承具有默认值的设置的值。您必须在子应用程序中设置该值。
• 继承没有默认值的设置的值；这些在下面的表格中明确指出。

例外：子应用程序将继承 trust proxy 的值，即使它具有默认值（为了向后兼容）；子应用程序不会在生产环境中继承 view cache 的值（当 NODE_ENV 为“production”时）。

app.set('trust proxy', 'loopback')

app.set('trust proxy', 'loopback, 123.123.123.123')

app.set('trust proxy', 'loopback, linklocal, uniquelocal')

app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal'])

app.set('trust proxy', function (ip) {
  if (ip === '127.0.0.1' || ip === '123.123.123.123') return true // trusted IPs
  else return false
})

app.set('etag', function (body, encoding) {
  return generateHash(body, encoding) // consider the function is defined
})

app.use([path,] callback [, callback...])

在指定路径上挂载指定的 中间件 函数或函数：当请求路径的基部与 path 匹配时，将执行中间件函数。

参数

描述

路由将匹配任何紧随其路径的路径，并以“/”结尾。例如：app.use('/apple', ...) 将匹配“/apple”、“/apple/images”、“/apple/images/news”等等。

由于 path 默认值为“/”，因此在没有路径的情况下挂载的中间件将对应用程序的每个请求执行。
例如，此中间件函数将对应用程序的每个请求执行

app.use(function (req, res, next) {
  console.log('Time: %d', Date.now())
  next()
})

中间件函数按顺序执行，因此中间件包含的顺序很重要。

// this middleware will not allow the request to go beyond it
app.use(function (req, res, next) {
  res.send('Hello World')
})

// requests will never reach this route
app.get('/', function (req, res) {
  res.send('Welcome')
})

错误处理中间件

错误处理中间件始终接受四个参数。您必须提供四个参数才能将其识别为错误处理中间件函数。即使您不需要使用 next 对象，也必须指定它以保持签名。否则，next 对象将被解释为常规中间件，并且无法处理错误。有关错误处理中间件的详细信息，请参阅：错误处理。

以与其他中间件函数相同的方式定义错误处理中间件函数，只是使用四个参数而不是三个，具体来说是使用签名 (err, req, res, next))

app.use(function (err, req, res, next) {
  console.error(err.stack)
  res.status(500).send('Something broke!')
})

路径示例

下表提供了一些用于挂载中间件的有效 path 值的简单示例。

app.use('/abcd', function (req, res, next) {
  next()
})

app.use('/abc?d', function (req, res, next) {
  next()
})

app.use('/ab+cd', function (req, res, next) {
  next()
})

app.use('/ab*cd', function (req, res, next) {
  next()
})

app.use('/a(bc)?d', function (req, res, next) {
  next()
})

app.use(/\/abc|\/xyz/, function (req, res, next) {
  next()
})

app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], function (req, res, next) {
  next()
})

中间件回调函数示例

下表提供了一些简单的中间件函数示例，这些函数可以用作app.use()、app.METHOD()和app.all()的callback参数。虽然示例是针对app.use()的，但它们也适用于app.use()、app.METHOD()和app.all()。

app.use(function (req, res, next) {
  next()
})

var router = express.Router()
router.get('/', function (req, res, next) {
  next()
})
app.use(router)

var subApp = express()
subApp.get('/', function (req, res, next) {
  next()
})
app.use(subApp)

var r1 = express.Router()
r1.get('/', function (req, res, next) {
  next()
})

var r2 = express.Router()
r2.get('/', function (req, res, next) {
  next()
})

app.use(r1, r2)

var r1 = express.Router()
r1.get('/', function (req, res, next) {
  next()
})

var r2 = express.Router()
r2.get('/', function (req, res, next) {
  next()
})

app.use([r1, r2])

function mw1 (req, res, next) { next() }
function mw2 (req, res, next) { next() }

var r1 = express.Router()
r1.get('/', function (req, res, next) { next() })

var r2 = express.Router()
r2.get('/', function (req, res, next) { next() })

var subApp = express()
subApp.get('/', function (req, res, next) { next() })

app.use(mw1, [mw2, r1, r2], subApp)

以下是一些在 Express 应用程序中使用express.static 中间件的示例。

从应用程序目录中的“public”目录为应用程序提供静态内容

// GET /style.css etc
app.use(express.static(path.join(__dirname, 'public')))

将中间件挂载到“/static”上，以便仅在请求路径以“/static”为前缀时提供静态内容

// GET /static/style.css etc.
app.use('/static', express.static(path.join(__dirname, 'public')))

通过在静态中间件之后加载日志记录中间件，为静态内容请求禁用日志记录

app.use(express.static(path.join(__dirname, 'public')))
app.use(logger())

从多个目录提供静态文件，但优先考虑“./public”而不是其他目录

app.use(express.static(path.join(__dirname, 'public')))
app.use(express.static(path.join(__dirname, 'files')))
app.use(express.static(path.join(__dirname, 'uploads')))

req.app

此属性保存对使用中间件的 Express 应用程序实例的引用。

如果您遵循创建仅导出中间件函数的模块并在主文件中 require() 它的模式，那么中间件可以通过 req.app 访问 Express 实例。

例如

// index.js
app.get('/viewdirectory', require('./mymiddleware.js'))

// mymiddleware.js
module.exports = function (req, res) {
  res.send('The views directory is ' + req.app.get('views'))
}

req.baseUrl

路由器实例挂载的 URL 路径。

req.baseUrl 属性类似于 app 对象的 mountpath 属性，不同之处在于 app.mountpath 返回匹配的路径模式。

例如

var greet = express.Router()

greet.get('/jp', function (req, res) {
  console.log(req.baseUrl) // /greet
  res.send('Konichiwa!')
})

app.use('/greet', greet) // load the router on '/greet'

即使您使用路径模式或一组路径模式来加载路由器，baseUrl 属性也会返回匹配的字符串，而不是模式。在以下示例中，greet 路由器在两个路径模式上加载。

app.use(['/gre+t', '/hel{2}o'], greet) // load the router on '/gre+t' and '/hel{2}o'

当向 /greet/jp 发出请求时，req.baseUrl 为“/greet”。当向 /hello/jp 发出请求时，req.baseUrl 为“/hello”。

req.body

包含在请求主体中提交的数据的键值对。默认情况下，它为 undefined，并在使用主体解析中间件（如 express.json() 或 express.urlencoded()）时填充。

以下示例展示了如何使用主体解析中间件来填充 req.body。

var express = require('express')

var app = express()

app.use(express.json()) // for parsing application/json
app.use(express.urlencoded({ extended: true })) // for parsing application/x-www-form-urlencoded

app.post('/profile', function (req, res, next) {
  console.log(req.body)
  res.json(req.body)
})

req.cookies

当使用 cookie-parser 中间件时，此属性是一个包含请求发送的 cookie 的对象。如果请求不包含 cookie，则默认为 {}。

// Cookie: name=tj
console.dir(req.cookies.name)
// => 'tj'

如果 cookie 已签名，则必须使用 req.signedCookies。

有关更多信息、问题或疑虑，请参阅 cookie-parser。

req.fresh

当响应在客户端的缓存中仍然“新鲜”时，返回 true，否则返回 false 以指示客户端缓存现在已过期，应发送完整响应。

当客户端发送 Cache-Control: no-cache 请求头以指示端到端重新加载请求时，此模块将返回 false 以使处理这些请求透明。

有关缓存验证工作原理的更多详细信息，请参阅 HTTP/1.1 缓存规范。

console.dir(req.fresh)
// => true

req.hostname

包含从 Host HTTP 头部派生的主机名。

当 trust proxy 设置 不评估为 false 时，此属性将改为从 X-Forwarded-Host 头部字段获取值。此头部可以由客户端或代理设置。

如果请求中存在多个 X-Forwarded-Host 头部，则使用第一个头部的值。这包括一个包含逗号分隔值的单个头部，其中使用第一个值。

// Host: "example.com:3000"
console.dir(req.hostname)
// => 'example.com'

req.ip

包含请求的远程 IP 地址。

当 trust proxy 设置 不等于 false 时，此属性的值将从 X-Forwarded-For 标头中最左边的条目中获取。此标头可以由客户端或代理设置。

console.dir(req.ip)
// => '127.0.0.1'

req.ips

当 trust proxy 设置 不等于 false 时，此属性包含 X-Forwarded-For 请求标头中指定的 IP 地址数组。否则，它包含一个空数组。此标头可以由客户端或代理设置。

例如，如果 X-Forwarded-For 是 client, proxy1, proxy2，则 req.ips 将为 ["client", "proxy1", "proxy2"]，其中 proxy2 是最下游的代理。

req.method

包含与请求的 HTTP 方法相对应的字符串：GET、POST、PUT 等。

req.originalUrl

此属性与 req.url 非常相似；但是，它保留了原始请求 URL，允许您自由地重写 req.url 以用于内部路由目的。例如，app.use() 的“挂载”功能将重写 req.url 以去除挂载点。

// GET /search?q=something
console.dir(req.originalUrl)
// => '/search?q=something'

req.originalUrl 在中间件和路由器对象中都可用，并且是 req.baseUrl 和 req.url 的组合。请考虑以下示例

app.use('/admin', function (req, res, next) { // GET 'http://www.example.com/admin/new?sort=desc'
  console.dir(req.originalUrl) // '/admin/new?sort=desc'
  console.dir(req.baseUrl) // '/admin'
  console.dir(req.path) // '/new'
  next()
})

req.params

此属性是一个对象，包含映射到 命名路由“参数” 的属性。例如，如果您有路由 /user/:name，则“name”属性可用作 req.params.name。此对象默认为 {}。

// GET /user/tj
console.dir(req.params.name)
// => 'tj'

当您对路由定义使用正则表达式时，捕获组将使用 req.params[n] 提供在数组中，其中 n 是第 n 个捕获组。此规则适用于使用字符串路由（如 /file/*）的未命名通配符匹配。

// GET /file/javascripts/jquery.js
console.dir(req.params[0])
// => 'javascripts/jquery.js'

如果您需要更改 req.params 中的键，请使用 app.param 处理程序。更改仅适用于在路由路径中已定义的 参数。

在中间件或路由处理程序中对 req.params 对象所做的任何更改都将被重置。

req.path

包含请求 URL 的路径部分。

// example.com/users?sort=desc
console.dir(req.path)
// => '/users'

req.protocol

包含请求协议字符串：http 或（对于 TLS 请求）https。

当 trust proxy 设置 不评估为 false 时，此属性将使用 X-Forwarded-Proto 标头字段的值（如果存在）。此标头可以由客户端或代理设置。

console.dir(req.protocol)
// => 'http'

req.query

此属性是一个对象，包含路由中每个查询字符串参数的属性。当 查询解析器 设置为禁用时，它是一个空对象 {}，否则它是配置的查询解析器的结果。

此属性的值可以使用 查询解析器应用程序设置 进行配置，以满足应用程序的需求。一个非常流行的查询字符串解析器是 qs 模块，这是默认使用的模块。qs 模块具有许多可配置的设置，并且可能需要使用与默认设置不同的设置来填充 req.query

var qs = require('qs')
app.set('query parser', function (str) {
  return qs.parse(str, { /* custom options */ })
})

查看 查询解析器应用程序设置 文档以了解其他自定义选项。

req.res

此属性保存对与该请求对象相关的 响应对象 的引用。

req.route

包含当前匹配的路由，一个字符串。例如

app.get('/user/:id?', function userIdHandler (req, res) {
  console.log(req.route)
  res.send('GET')
})

上一段代码的示例输出

{ path: '/user/:id?',
  stack:
   [ { handle: [Function: userIdHandler],
       name: 'userIdHandler',
       params: undefined,
       path: undefined,
       keys: [],
       regexp: /^\/?$/i,
       method: 'get' } ],
  methods: { get: true } }

req.secure

如果建立了 TLS 连接，则为布尔属性，值为 true。等同于

console.dir(req.protocol === 'https')
// => true

req.signedCookies

使用 cookie-parser 中间件时，此属性包含请求发送的已签名 cookie，未签名且可供使用。已签名 cookie 位于不同的对象中，以显示开发人员的意图；否则，恶意攻击可能会放在 req.cookie 值上（这些值很容易伪造）。请注意，对 cookie 进行签名不会使其“隐藏”或加密；而只是防止篡改（因为用于签名的密钥是私有的）。

如果没有发送已签名 cookie，则该属性默认为 {}。

// Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
console.dir(req.signedCookies.user)
// => 'tobi'

有关更多信息、问题或疑虑，请参阅 cookie-parser。

req.stale

指示请求是否“陈旧”，与 req.fresh 相反。有关更多信息，请参阅 req.fresh。

console.dir(req.stale)
// => true

req.subdomains

请求域名中的子域名的数组。

// Host: "tobi.ferrets.example.com"
console.dir(req.subdomains)
// => ['ferrets', 'tobi']

应用程序属性 subdomain offset（默认为 2）用于确定子域段的开头。要更改此行为，请使用 app.set 更改其值。

req.xhr

如果请求的 X-Requested-With 标头字段为“XMLHttpRequest”，则为布尔属性，值为 true，表示该请求是由 jQuery 等客户端库发出的。

console.dir(req.xhr)
// => true

req.accepts(types)

根据请求的 Accept HTTP 标头字段，检查指定的 content type 是否可接受。该方法返回最佳匹配，如果指定的 content type 中没有一个可接受，则返回 false（在这种情况下，应用程序应返回 406 "Not Acceptable"）。

type 值可以是单个 MIME 类型字符串（例如“application/json”）、扩展名（例如“json”）、逗号分隔的列表或数组。对于列表或数组，该方法返回最佳匹配（如果有）。

// Accept: text/html
req.accepts('html')
// => "html"

// Accept: text/*, application/json
req.accepts('html')
// => "html"
req.accepts('text/html')
// => "text/html"
req.accepts(['json', 'text'])
// => "json"
req.accepts('application/json')
// => "application/json"

// Accept: text/*, application/json
req.accepts('image/png')
req.accepts('png')
// => false

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

有关更多信息，或如果您有任何问题或疑虑，请参阅 accepts。

req.acceptsCharsets(charset [, ...])

根据请求的 Accept-Charset HTTP 标头字段，返回指定的字符集中第一个被接受的字符集。如果指定的字符集中没有一个被接受，则返回 false。

有关更多信息，或如果您有任何问题或疑虑，请参阅 accepts。

req.acceptsEncodings(encoding [, ...])

根据请求的 Accept-Encoding HTTP 标头字段，返回指定的编码中第一个被接受的编码。如果指定的编码中没有一个被接受，则返回 false。

有关更多信息，或如果您有任何问题或疑虑，请参阅 accepts。

req.acceptsLanguages([lang, ...])

根据请求的 Accept-Language HTTP 标头字段，返回指定的语言中第一个被接受的语言。如果指定的语言中没有一个被接受，则返回 false。

如果未提供lang参数，则req.acceptsLanguages()将返回HTTP Accept-Language标头中的所有语言，作为Array。

有关更多信息，或如果您有任何问题或疑虑，请参阅 accepts。

Express (4.x) 源代码：request.js 第 179 行

Accepts (1.3) 源代码：index.js 第 195 行

req.get(field)

返回指定的 HTTP 请求标头字段（不区分大小写匹配）。Referrer 和 Referer 字段可以互换。

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

req.get('content-type')
// => "text/plain"

req.get('Something')
// => undefined

别名为 req.header(field)。

req.is(type)

如果传入请求的“Content-Type” HTTP 标头字段与type参数指定的 MIME 类型匹配，则返回匹配的 Content-Type。如果请求没有主体，则返回null。否则返回false。

// With Content-Type: text/html; charset=utf-8
req.is('html')
// => 'html'
req.is('text/html')
// => 'text/html'
req.is('text/*')
// => 'text/*'

// When Content-Type is application/json
req.is('json')
// => 'json'
req.is('application/json')
// => 'application/json'
req.is('application/*')
// => 'application/*'

req.is('html')
// => false

有关更多信息，或如果您有任何问题或疑虑，请参阅 type-is。

req.param(name [, defaultValue])

返回参数name的值（如果存在）。

// ?name=tobi
req.param('name')
// => "tobi"

// POST name=tobi
req.param('name')
// => "tobi"

// /user/tobi for /user/:name
req.param('name')
// => "tobi"

查找顺序如下

• req.params
• req.body
• req.query

可以选择指定defaultValue，如果在任何请求对象中都找不到参数，则设置默认值。

req.range(size[, options])

Range 标头解析器。

size参数是资源的最大大小。

options参数是一个对象，可以具有以下属性。

将返回一个范围数组，或者返回负数表示解析错误。

• -2 表示标头字符串格式错误
• -1 表示不可满足的范围

// parse header from request
var range = req.range(1000)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}

res.app

此属性保存对使用中间件的 Express 应用程序实例的引用。

res.app 与请求对象中的 req.app 属性相同。

res.headersSent

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

app.get('/', function (req, res) {
  console.dir(res.headersSent) // false
  res.send('OK')
  console.dir(res.headersSent) // true
})

res.locals

使用此属性设置使用 res.render 渲染的模板中可访问的变量。在 res.locals 上设置的变量在单个请求-响应周期内可用，不会在请求之间共享。

为了保留本地变量以便在请求之间用于模板渲染，请使用 app.locals。

此属性对于将请求级信息（例如请求路径名称、已认证用户、用户设置等）公开给应用程序中渲染的模板很有用。

app.use(function (req, res, next) {
  // Make `user` and `authenticated` available in templates
  res.locals.user = req.user
  res.locals.authenticated = !req.user.anonymous
  next()
})

res.append(field [, value])

将指定的 value 附加到 HTTP 响应头 field。如果头尚未设置，则使用指定的值创建头。value 参数可以是字符串或数组。

注意：在 res.append() 之后调用 res.set() 将重置先前设置的头值。

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

res.attachment([filename])

将 HTTP 响应 Content-Disposition 头字段设置为“attachment”。如果给出了 filename，则通过 res.type() 根据扩展名设置 Content-Type，并设置 Content-Disposition 的“filename=”参数。

res.attachment()
// Content-Disposition: attachment

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

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

将 cookie name 设置为 value。value 参数可以是字符串或转换为 JSON 的对象。

options参数是一个对象，可以具有以下属性。

例如

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-parser 中间件时，此方法还支持已签名的 cookie。只需将 signed 选项设置为 true 即可。然后 res.cookie() 将使用传递给 cookieParser(secret) 的密钥来对值进行签名。

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

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

res.clearCookie(name [, options])

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

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

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

将 path 处的文件作为“附件”传输。通常，浏览器会提示用户下载。默认情况下，Content-Disposition 标头的“filename=”参数是从 path 参数派生的，但可以使用 filename 参数覆盖。如果 path 是相对路径，则它将基于进程的当前工作目录或提供的 root 选项。

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

该方法在传输完成或发生错误时调用回调函数fn(err)。如果指定了回调函数并且发生错误，则回调函数必须通过结束请求-响应循环或将控制权传递给下一个路由来显式处理响应过程。

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.ServerResponse 的 response.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()等方法来更改它。

以下示例将在Accept标头字段设置为“application/json”或“*/json”时响应{ "message": "hey" }（但是，如果它是“*/*”，则响应将是“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)

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

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

res.json([body])

发送 JSON 响应。此方法发送一个响应（带有正确的 content-type），该响应是使用 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 回调名称只是 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 连接起来，以填充响应的 Link HTTP 标头字段。

例如，以下调用

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)

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

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

path 值为“back”具有特殊含义，它指的是请求的 Referer 标头中指定的 URL。如果未指定 Referer 标头，则它指的是“/”。

res.redirect([status,] path)

重定向到从指定的 path 派生的 URL，并使用指定的 status，这是一个正整数，对应于 HTTP 状态代码。如果未指定，status 默认值为“302 “Found”。

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，则以下操作将重定向到 URL http://example.com/admin。

res.redirect('/admin')

重定向可以相对于当前 URL。例如，从 http://example.com/blog/admin/（注意尾部斜杠），以下操作将重定向到 URL http://example.com/blog/admin/post/new。

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。

res.redirect('..')

back 重定向将请求重定向回 referer，在 referer 缺失时默认为 /。

res.redirect('back')

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

渲染一个 view 并将渲染后的 HTML 字符串发送到客户端。可选参数

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

view 参数是一个字符串，它是要渲染的视图文件的路径。这可以是绝对路径，也可以是相对于 views 设置的路径。如果路径不包含文件扩展名，则 view engine 设置将确定文件扩展名。如果路径包含文件扩展名，则 Express 将加载指定模板引擎的模块（通过 require()）并使用加载的模块的 __express 函数渲染它。

有关更多信息，请参阅 在 Express 中使用模板引擎。

// 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.req

res.send([body])

发送 HTTP 响应。

body 参数可以是 Buffer 对象、String、对象、Boolean 或 Array。例如

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-Length HTTP 响应头字段（除非之前已定义），并提供自动 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])

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

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

该方法在传输完成或发生错误时调用回调函数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.")
    }
  })
})

有关更多信息，或者如果您遇到问题或疑虑，请参阅 send。

res.sendStatus(statusCode)

将响应 HTTP 状态代码设置为 statusCode，并将注册的状态消息作为文本响应主体发送。如果指定了未知状态代码，则响应主体将只是代码编号。

res.sendStatus(404)

更多关于 HTTP 状态码的信息

res.set(field [, value])

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

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-Type HTTP 标头设置为由指定 type 确定的 MIME 类型。如果 type 包含“/”字符，则将其设置为 type 的确切值，否则将其视为文件扩展名，并使用 express.static.mime.lookup() 方法在映射中查找 MIME 类型。

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')

router 对象是中间件和路由的独立实例。可以将其视为一个“迷你应用程序”，它只能执行中间件和路由功能。每个 Express 应用程序都具有一个内置的应用程序路由器。

路由器本身的行为类似于中间件，因此可以将其用作 app.use() 的参数，或用作另一个路由器的 use() 方法的参数。

顶级 express 对象具有一个 Router() 方法，该方法创建一个新的 router 对象。

创建路由器对象后，可以向其添加中间件和 HTTP 方法路由（例如 get、put、post 等），就像应用程序一样。例如

// invoked for any requests passed to this router
router.use(function (req, res, next) {
  // .. some logic here .. like any other middleware
  next()
})

// will handle any request that ends in /events
// depends on where the router is "use()'d"
router.get('/events', function (req, res, next) {
  // ..
})

然后，可以使用路由器来处理特定的根 URL，从而将路由分离到文件甚至迷你应用程序中。

// only requests to /calendar/* will be sent to our "router"
app.use('/calendar', router)

router.all(path, [callback, ...] callback)

此方法与 router.METHOD() 方法类似，只是它匹配所有 HTTP 方法（动词）。

此方法对于映射特定路径前缀或任意匹配的“全局”逻辑非常有用。例如，如果将以下路由放在所有其他路由定义的顶部，则它将要求从该点开始的所有路由都需要身份验证，并自动加载用户。请记住，这些回调不必充当端点；loadUser 可以执行任务，然后调用 next() 以继续匹配后续路由。

router.all('*', requireAuthentication, loadUser)

或等效的

router.all('*', requireAuthentication)
router.all('*', loadUser)

另一个示例是白名单“全局”功能。这里示例与之前类似，但它只限制以“/api”为前缀的路径

router.all('/api/*', requireAuthentication)

router.METHOD(path, [callback, ...] callback)

router.METHOD() 方法提供了 Express 中的路由功能，其中 METHOD 是 HTTP 方法之一，例如 GET、PUT、POST 等，以小写形式表示。因此，实际方法为 router.get()、router.post()、router.put() 等。

您可以提供多个回调函数，它们都将被平等对待，并且行为与中间件相同，只是这些回调函数可以调用 next('route') 来绕过剩余的路由回调函数。您可以使用此机制对路由执行先决条件，然后在没有理由继续执行匹配的路由时将控制权传递给后续路由。

以下代码片段说明了最简单的路由定义。Express 将路径字符串转换为正则表达式，在内部用于匹配传入的请求。在执行这些匹配时，不会考虑查询字符串，例如“GET /”将匹配以下路由，就像“GET /?name=tobi”一样。

router.get('/', function (req, res) {
  res.send('hello world')
})

您还可以使用正则表达式——如果您有非常具体的约束，这很有用，例如以下将匹配“GET /commits/71dbb9c”以及“GET /commits/71dbb9c..4c084f9”。

router.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function (req, res) {
  var from = req.params[0]
  var to = req.params[1] || 'HEAD'
  res.send('commit range ' + from + '..' + to)
})

router.param(name, callback)

为路由参数添加回调触发器，其中 name 是参数的名称，callback 是回调函数。虽然 name 在技术上是可选的，但从 Express v4.11.0 开始，不使用它使用此方法已过时（见下文）。

回调函数的参数是

• req，请求对象。
• res，响应对象。
• next，指示下一个中间件函数。
• name 参数的值。
• 参数的名称。

例如，当路由路径中存在:user时，您可以将用户加载逻辑映射到自动提供req.user到路由，或对参数输入进行验证。

router.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (err, user) {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

参数回调函数是定义它们的路由的本地函数。它们不会被挂载的应用程序或路由继承。因此，在 router 上定义的参数回调将仅由 router 路由上定义的路由参数触发。

即使参数在多个路由中匹配，参数回调在一次请求-响应周期中也只会调用一次，如下例所示。

router.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

router.get('/user/:id', function (req, res, next) {
  console.log('although this matches')
  next()
})

router.get('/user/:id', function (req, res) {
  console.log('and this matches too')
  res.end()
})

在GET /user/42上，打印以下内容

CALLED ONLY ONCE
although this matches
and this matches too

通过仅将函数传递给router.param()，可以完全改变router.param(name, callback)方法的行为。此函数是router.param(name, callback)行为的自定义实现 - 它接受两个参数，并且必须返回一个中间件。

此函数的第一个参数是要捕获的 URL 参数的名称，第二个参数可以是任何 JavaScript 对象，它可能用于返回中间件实现。

函数返回的中间件决定了捕获 URL 参数时发生的事情的行为。

在本例中，router.param(name, callback)签名被修改为router.param(name, accessId)。router.param()现在将接受一个名称和一个数字，而不是接受一个名称和一个回调。

var express = require('express')
var app = express()
var router = express.Router()

// customizing the behavior of router.param()
router.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

// using the customized router.param()
router.param('id', '1337')

// route to trigger the capture
router.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.use(router)

app.listen(3000, function () {
  console.log('Ready')
})

在本例中，router.param(name, callback)签名保持不变，但已定义一个自定义数据类型检查函数来验证用户 ID 的数据类型，而不是中间件回调。

router.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

router.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

router.route(path)

返回单个路由的实例，您可以使用它来处理带有可选中间件的 HTTP 动词。使用router.route()避免重复路由命名，从而避免类型错误。

基于上面的router.param()示例，以下代码展示了如何使用router.route()来指定各种 HTTP 方法处理程序。

var router = express.Router()

router.param('user_id', function (req, res, next, id) {
  // sample user, would actually fetch from DB, etc...
  req.user = {
    id: id,
    name: 'TJ'
  }
  next()
})

router.route('/users/:user_id')
  .all(function (req, res, next) {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
    next()
  })
  .get(function (req, res, next) {
    res.json(req.user)
  })
  .put(function (req, res, next) {
    // just an example of maybe updating the user
    req.user.name = req.params.name
    // save user ... etc
    res.json(req.user)
  })
  .post(function (req, res, next) {
    next(new Error('not implemented'))
  })
  .delete(function (req, res, next) {
    next(new Error('not implemented'))
  })

这种方法重新使用单个/users/:user_id路径，并为各种 HTTP 方法添加处理程序。

router.use([path], [function, ...] function)

使用指定的中间件函数或函数，带有可选的挂载路径path，默认值为“/”。

此方法类似于app.use()。下面描述了一个简单的示例和用例。有关更多信息，请参阅app.use()。

中间件就像一个管道：请求从定义的第一个中间件函数开始，并沿着中间件堆栈“向下”工作，处理它们匹配的每个路径。

var express = require('express')
var app = express()
var router = express.Router()

// simple logger for this router's requests
// all requests to this router will first hit this middleware
router.use(function (req, res, next) {
  console.log('%s %s %s', req.method, req.url, req.path)
  next()
})

// this will only be invoked if the path starts with /bar from the mount point
router.use('/bar', function (req, res, next) {
  // ... maybe some additional /bar logging ...
  next()
})

// always invoked
router.use(function (req, res, next) {
  res.send('Hello World')
})

app.use('/foo', router)

app.listen(3000)

“mount” 路径会被剥离，并且对中间件函数不可见。此功能的主要作用是，无论其“前缀”路径是什么，已挂载的中间件函数都可以在不进行代码更改的情况下运行。

使用 router.use() 定义中间件的顺序非常重要。它们按顺序调用，因此顺序定义了中间件的优先级。例如，通常记录器是您使用的第一个中间件，以便记录每个请求。

var logger = require('morgan')
var path = require('path')

router.use(logger())
router.use(express.static(path.join(__dirname, 'public')))
router.use(function (req, res) {
  res.send('Hello')
})

现在假设您想忽略对静态文件的日志记录请求，但继续记录在 logger() 之后定义的路由和中间件。您只需将对 express.static() 的调用移到顶部，在添加记录器中间件之前。

router.use(express.static(path.join(__dirname, 'public')))
router.use(logger())
router.use(function (req, res) {
  res.send('Hello')
})

另一个例子是从多个目录提供文件，优先考虑“./public”而不是其他目录。

router.use(express.static(path.join(__dirname, 'public')))
router.use(express.static(path.join(__dirname, 'files')))
router.use(express.static(path.join(__dirname, 'uploads')))

router.use() 方法还支持命名参数，以便您的其他路由器的挂载点可以从使用命名参数的预加载中受益。

注意：虽然这些中间件函数是通过特定路由添加的，但它们运行的时间由它们附加到的路径（而不是路由）定义。因此，通过一个路由添加的中间件可能会为其他路由运行，如果其路由匹配。例如，此代码显示了两个挂载在同一路径上的不同路由器。

var authRouter = express.Router()
var openRouter = express.Router()

authRouter.use(require('./authenticate').basic(usersdb))

authRouter.get('/:user_id/edit', function (req, res, next) {
  // ... Edit user UI ...
})
openRouter.get('/', function (req, res, next) {
  // ... List users ...
})
openRouter.get('/:user_id', function (req, res, next) {
  // ... View user ...
})

app.use('/users', authRouter)
app.use('/users', openRouter)

即使身份验证中间件是通过 authRouter 添加的，它也会在 openRouter 定义的路由上运行，因为这两个路由器都挂载在 /users 上。为了避免这种行为，请为每个路由器使用不同的路径。