Express 4.x API 翻译-Router

路由（Router）

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

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

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

一旦您创建了一个路由对象，您就可以像应用程序一样向它添加中间件和HTTP方法路由（例如GET、PUT、POST等）。例如：

// 为传递到此路由器的任何请求调用
router.use(function(req, res, next) {
  // .. 这里有些逻辑……像其他中间件一样
  next();
});

// 将处理以'/events'结尾的任何请求
// 取决于路由在哪被用到'use()'
router.get('/events', function(req, res, next) {
  // ..
});

然后，您可以通过这种方式将路由用于特定的根URL，将您的路由分为文件甚至迷你应用程序。

// 只有对'/calendar/*'的请求才会发送到我们的“路由”
app.use('/calendar', router);

方法

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

这个方法和router.METHOD()方法一样，只是它匹配所有的HTTP方法。

此方法对于为特定path前缀或任意匹配映射“全局”逻辑非常有用。例如，如果将以下路由放置在所有其他路由定义的顶层，则需要来自该点的所有路由都需要身份验证，并自动加载用户。请记住，这些回调不必充当端点，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()等等。

注意：如果在router.get()之前的路径path没有调用router.head()，那么除了get方法之外，还会为 HTTP HEAD 方法自动调用router.get()函数。

您可以提供多个回调，所有回调都被同等对待，其行为与中间件类似，只是这些回调可能调用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参数的值。
• 参数的名称。

注意：与app.param()不同，router.param()不接受一个路由参数数组。

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

router.param('user', function(req, res, next, id) {

  // 尝试从用户模型获取用户详细信息并将其附加到请求对象
  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'));
    }
  });
});

参数回调（Param callback ）函数是定义它们的路由器的本地函数。它们不会被挂载的应用程序或路由器继承。因此，只有在router路由上定义的路由参数才会触发在router 上定义的参数回调（param callbacks）。

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

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(callback，自v4.11.0起已弃用。

router.param(name, callback)方法的行为完全可以通过只向router.param()传递函数来更改。这个函数是router.param(name，callback)的一个自定义实现，它接受两个参数，必须返回一个中间件。

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

函数返回的中间件决定捕获URL参数时的行为。

在本例中，router.param(name, callback)签名修改为router.param(name，accessid)。router.param()现在不接受name和callback，而是接受name和数字。

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.route()时，中间件排序是基于创建路由的时机，而不是方法处理程序添加到路由的时机。为此，可以将方法处理器视为属于添加它们的路由。

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

router.use(logger());
router.use(express.static(__dirname + '/public'));
router.use(function(req, res){
  res.send('Hello');
});

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

router.use(express.static(__dirname + '/public'));
router.use(logger());
router.use(function(req, res){
  res.send('Hello');
});

另一个例子是为来自多个目录的文件提供服务，将“./public”优先于其他目录：

app.use(express.static(__dirname + '/public'));
app.use(express.static(__dirname + '/files'));
app.use(express.static(__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'上。要避免这种行为，请为每个路由器使用不同的路径。