路由(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'
上。要避免这种行为,请为每个路由器使用不同的路径。