5.x API

express.json([options])

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

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

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

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

express.static(root, [options])

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

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

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

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

dotfiles

此选项的可能值为

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

贯穿

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

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

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

setHeaders

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

函数的签名是

fn(res, path, stat)

参数

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

express.static 的示例

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

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

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

express.Router([options])

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

const router = express.Router([options])

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

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

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

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 属性包含一个或多个子应用程序安装的路径模式。

const express = require('express')

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

admin.get('/', (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 返回它安装的模式列表，如以下示例所示。

const admin = express()

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

const secret = express()
secret.get('/', (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.router

应用程序的内置路由器实例。它是在第一次访问时延迟创建的。

const express = require('express')
const app = express()
const router = app.router

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

app.listen(3000)

您可以像应用程序一样向 router 添加中间件和 HTTP 方法路由。

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

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

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

const admin = express()

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

admin.get('/', (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', (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('/', (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 无缝协作。

const 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('/', (req, res) => {
  res.send('GET request to homepage')
})

app.listen(path, [callback])

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

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

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

绑定并监听指定主机和端口上的连接。此方法与 Node 的 http.Server.listen() 相同。

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

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

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

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

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

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

app.listen = function () {
  const 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', (req, res, next, id) => {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, (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', (req, res, next, id) => {
  console.log('CALLED ONLY ONCE')
  next()
})

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

app.get('/user/:id', (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'], (req, res, next, value) => {
  console.log('CALLED ONLY ONCE with', value)
  next()
})

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

app.get('/user/:id/:page', (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.path()

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

const app = express()
const blog = express()
const blogAdmin = express()

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

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

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

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

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

参数

示例

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

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

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

参数

示例

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

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

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

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

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

app.route(path)

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

const app = express()

app.route('/events')
  .all((req, res, next) => {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
  })
  .get((req, res, next) => {
    res.json({})
  })
  .post((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的值，即使它具有默认值（为了向后兼容）；子应用程序在生产环境中（当NODE_ENV为“production”时）不会继承view cache的值。

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', (ip) => {
  if (ip === '127.0.0.1' || ip === '123.123.123.123') return true // trusted IPs
  else return false
})

app.set('etag', (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((req, res, next) => {
  console.log('Time: %d', Date.now())
  next()
})

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

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

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

错误处理中间件

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

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

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

路径示例

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

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

app.use('/ab(c?)d', (req, res, next) => {
  next()
})

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

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

中间件回调函数示例

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

app.use((req, res, next) => {
  next()
})

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

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

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

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

app.use(r1, r2)

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

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

app.use([r1, r2])

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

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

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

const subApp = express()
subApp.get('/', (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 = (req, res) => {
  res.send(`The views directory is ${req.app.get('views')}`)
}

req.baseUrl

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

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

例如

const greet = express.Router()

greet.get('/jp', (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，并在您使用正文解析中间件（如 body-parser 和 multer）时填充。

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

const app = require('express')()
const bodyParser = require('body-parser')
const multer = require('multer') // v1.0.5
const upload = multer() // for parsing multipart/form-data

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

app.post('/profile', upload.array(), (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.host

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

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

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

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

// Host: "[::1]:3000"
console.dir(req.host)
// => '[::1]:3000'

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 的组合。请考虑以下示例

// GET 'http://www.example.com/admin/new?sort=desc'
app.use('/admin', (req, res, next) => {
  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

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

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

req.res

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

req.route

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

app.get('/user/:id?', (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。等效于以下内容

req.protocol === 'https'

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。

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

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.range(size[, options])

Range 头解析器。

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

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

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

• -2 表示头字符串格式错误
• -1 表示无法满足的范围

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

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

res.app

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

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

res.headersSent

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

app.get('/', (req, res) => {
  console.log(res.headersSent) // false
  res.send('OK')
  console.log(res.headersSent) // true
})

res.locals

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

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

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

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

res.req

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

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

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.signedCookies 对象访问此值。

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 是相对路径，则它将基于进程的当前工作目录。

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

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

res.download('/report-12345.pdf')

res.download('/report-12345.pdf', 'report.pdf')

res.download('/report-12345.pdf', 'report.pdf', (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' () {
    res.send('hey')
  },

  'text/html' () {
    res.send('<p>hey</p>')
  },

  'application/json' () {
    res.send({ message: 'hey' })
  },

  default () {
    // log the request and respond with 406
    res.status(406).send('Not Acceptable')
  }
})

除了规范化的 MIME 类型之外，您还可以使用映射到这些类型的扩展名，以实现稍微不那么冗长的实现。

res.format({
  text () {
    res.send('hey')
  },

  html () {
    res.send('<p>hey</p>')
  },

  json () {
    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 的模板引擎。

注意：view 参数执行文件系统操作，例如从磁盘读取文件和评估 Node.js 模块，因此出于安全原因，它不应包含来自最终用户的输入。

// 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', (err, html) => {
  res.send(html)
})

// pass a local variable to the view
res.render('user', { name: 'Tobi' }, (err, html) => {
  // ...
})

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 头字段。除非在选项对象中设置了root选项，否则path必须是文件的绝对路径。

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

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

以下是用res.sendFile及其所有参数的示例。

app.get('/file/:name', (req, res, next) => {
  const options = {
    root: path.join(__dirname, 'public'),
    dotfiles: 'deny',
    headers: {
      'x-timestamp': Date.now(),
      'x-sent': true
    }
  }

  const fileName = req.params.name
  res.sendFile(fileName, options, (err) => {
    if (err) {
      next(err)
    } else {
      console.log('Sent:', fileName)
    }
  })
})

以下示例说明了使用res.sendFile为提供文件提供细粒度支持

app.get('/user/:uid/photos/:file', (req, res) => {
  const uid = req.params.uid
  const file = req.params.file

  req.user.mayViewFilesFrom(uid, (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((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', (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('/', (req, res) => {
  res.send('hello world')
})

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

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

您可以使用 next 原语根据特定程序状态在不同的中间件函数之间实现流程控制。使用字符串 'router' 调用 next 将导致该路由器上的所有剩余路由回调被绕过。

以下示例说明了 next('router') 的用法。

function fn (req, res, next) {
  console.log('I come here')
  next('router')
}
router.get('/foo', fn, (req, res, next) => {
  console.log('I dont come here')
})
router.get('/foo', (req, res, next) => {
  console.log('I dont come here')
})
app.get('/foo', (req, res) => {
  console.log(' I come here too')
  res.end('good')
})

router.param(name, callback)

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

回调函数的参数是

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

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

router.param('user', (req, res, next, id) => {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, (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', (req, res, next, id) => {
  console.log('CALLED ONLY ONCE')
  next()
})

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

router.get('/user/:id', (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() 现在将接受一个名称和一个数字，而不是接受一个名称和一个回调。

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

// customizing the behavior of router.param()
router.param((param, option) => {
  return (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', (req, res) => {
  res.send('OK')
})

app.use(router)

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

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

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

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

router.route(path)

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

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

const router = express.Router()

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

router.route('/users/:user_id')
  .all((req, res, next) => {
  // runs for all HTTP verbs first
  // think of it as route specific middleware!
    next()
  })
  .get((req, res, next) => {
    res.json(req.user)
  })
  .put((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((req, res, next) => {
    next(new Error('not implemented'))
  })
  .delete((req, res, next) => {
    next(new Error('not implemented'))
  })

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

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

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

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

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

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

// simple logger for this router's requests
// all requests to this router will first hit this middleware
router.use((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', (req, res, next) => {
  // ... maybe some additional /bar logging ...
  next()
})

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

app.use('/foo', router)

app.listen(3000)

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

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

const logger = require('morgan')

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

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

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

另一个例子是从多个目录提供文件，优先考虑“./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')))

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

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

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

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

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

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

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