Express中文文档

时间  2019-11-18
标签 express 中文 文档 繁體版
原文   原文链接

Express 4.x API

express 翻译 api文档 中文javascript

--css

 
 

express()

express()用来建立一个Express的程序。express()方法是express模块导出的顶层方法。html

 
  1. var express = require('express');
  2. var app = express();
 

Methods

 

express.static(root, [options])

express.static是Express中惟一的内建中间件。它以server-static模块为基础开发，负责托管 Express 应用内的静态资源。 
参数root为静态资源的所在的根目录。 
参数options是可选的，支持如下的属性：前端

属性 描述 类型 默认值
dotfiles 是否响应点文件。供选择的值有"allow"，"deny"和"ignore" String "ignore"
etag 使能或者关闭etag Boolean true
extensions 设置文件延期回退 Boolean true
index 发送目录索引文件。设置false将不发送。 Mixed "index.html"
lastModified 设置文件在系统中的最后修改时间到Last-Modified头部。可能的取值有false和true。 Boolean true
maxAge 在Cache-Control头部中设置max-age属性，精度为毫秒(ms)或则一段ms format的字符串 Number 0
redirect 当请求的pathname是一个目录的时候，重定向到尾随"/" Boolean true
setHeaders 当响应静态文件请求时设置headers的方法 Funtion  

若是你想得到更多关于使用中间件的细节，你能够查阅Serving static files in Express。vue

 

Application()

app对象通常用来表示Express程序。经过调用Express模块导出的顶层的express()方法来建立它:java

 
  1. var express = require('express');
  2. var app = express();
  4. app.get('/', function(req, res) {
  5. res.send('hello world!');
  6. });
  8. app.listen(3000);

app对象具备如下的方法：node

它还有一些属性设置，这些属性能够改变程序的行为。得到更多的信息，能够查阅Application settings。jquery

 

Properties

 

app.locals

app.locals对象是一个javascript对象，它的属性就是程序本地的变量。git

 
  1. app.locals.title
  2. // => 'My App'
  4. app.locals.email
  5. // => 'me@myapp.com'

一旦设定，app.locals的各属性值将贯穿程序的整个生命周期，与其相反的是res.locals，它只在此次请求的生命周期中有效。github

在程序中，你能够在渲染模板时使用这些本地变量。它们是很是有用的，能够为模板提供一些有用的方法，以及app级别的数据。经过req.app.locals(具体查看req.app)，Locals能够在中间件中使用。

 
  1. app.locals.title = 'My App';
  2. app.locals.strftime = require('strftime');
  3. app.locals.email = 'me@myapp.com';
 

app.mountpath

app.mountpath属性是子程序挂载的路径模式。

一个子程序是一个express的实例，其能够被用来做为路由句柄来处理请求。

 
  1. var express = require('express');
  2. var app = express(); // the main app
  3. var admin = express(); // the sub app
  4. admin.get('/', function(req, res) {
  5. console.log(admin.mountpath); // /admin
  6. res.send('Admin Homepage');
  7. });
  9. app.use('/admin', admin); // mount the sub app

它和req对象的baseUrl属性比较类似，除了req.baseUrl是匹配的URL路径，而不是匹配的模式。若是一个子程序被挂载在多条路径模式，app.mountpath就是一个关于挂载路径模式项的列表，以下面例子所示。

 
  1. var admin = express();
  2. admin.get('/', function(req, res) {
  3. console.log(admin.mountpath); // ['adm*n', '/manager'] 
  4. res.send('Admin Homepage');
  5. });
  7. var secret = express();
  8. secret.get('/', function(req, res) {
  9. console.log(secret.mountpath); // /secr*t
  10. res.send('Admin secret');
  11. });
  13. admin.use('/secr*t', secret); // load the 'secret' router on '/secr*t', on the 'admin' sub app
  14. app.use(['/adm*n', '/manager'], admin); // load the 'admin' router on '/adm*n' and '/manager' , on the parent app
 

Events

 

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

当子程序被挂载到父程序时，mount事件被发射。父程序对象做为参数，传递给回调方法。

 
  1. var admin = express();
  2. admin.on('mount', function(parent) {
  3. console.log('Admin Mounted');
  4. console.log(parent); // refers to the parent app
  5. });
  7. admin.get('/', function(req, res) {
  8. res.send('Admin Homepage');
  9. });
  11. app.use('/admin', admin);
 

Methods

 

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

app.all方法和标准的app.METHOD()方法类似，除了它匹配全部的HTTP动词。 
对于给一个特殊前缀映射一个全局的逻辑处理，或者无条件匹配，它是颇有效的。例如，若是你把下面内容放在全部其余的路由定义的前面，它要求全部从这个点开始的路由须要认证和自动加载一个用户。记住这些回调并非必定是终点:loadUser能够在完成了一个任务后，调用next()方法来继续匹配随后的路由。

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

或者这种相等的形式:

 
  1. app.all('*', requireAuthentication);
  2. app.all('*', loadUser);

另外一个例子是全局的白名单方法。这个例子和前面的很像，然而它只是限制以/api开头的路径。

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

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

路由HTTP DELETE请求到有特殊回调方法的特殊的路径。获取更多的信息，能够查阅routing guide。 
你能够提供多个回调函数，它们的行为和中间件同样，除了这些回调能够经过调用next('router')来绕过剩余的路由回调。你可使用这个机制来为一个路由设置一些前提条件，若是不能知足当前路由的处理条件，那么你能够传递控制到随后的路由。

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

app.disable(name)

设置类型为布尔的设置名为name的值为false，此处的name是app settings table中各属性的一个。调用app.set('foo', false)和调用app.disable('foo')是等价的。 
好比:

 
  1. app.disable('trust proxy');
  2. app.get('trust proxy');
  3. // => false
 

app.disabled(name)

返回true若是布尔类型的设置值name被禁用为false，此处的name是app settings table中各属性的一个。

 
  1. app.disabled('trust proxy');
  2. // => true
  3. app.enable('trust proxy');
  4. app.disabled('trust proxy');
  5. // => false
 

app.enable(name)

设置布尔类型的设置值name为true，此处的name是app settings table中各属性的一个。调用app.set('foo', true)和调用app.enable('foo')是等价的。

 
  1. app.enable('trust proxy');
  2. app.get('trust proxy');
  3. // => true
 

app.enabled(name)

返回true若是布尔类型的设置值name被启动为true，此处的name是app settings table中各属性的一个。

 
  1. app.enabled('trust proxy');
  2. // => false
  3. app.enable('trust proxy');
  4. app.enabled('trust proxy');
  5. // => true
 

app.engine(ext, callback)

注册给定引擎的回调，用来渲染处理ext文件。 
默认状况下，Express须要使用require()来加载基于文件扩展的引擎。例如，若是你尝试渲染一个foo.jade文件，Express在内部调用下面的内容，同时缓存require()结果供随后的调用，来加速性能。

 
  1. app.engine('jade', require('jade').__express);

使用下面的方法对于那些没有提供开箱即用的.__express方法的模板，或者你但愿使用不一样的模板引擎扩展。 
好比，使用EJS模板引擎来渲染.html文件：

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

在这个例子中，EJS提供了一个.renderFile方法，这个方法知足了Express规定的签名规则：(path, options, callback)，然而记住在内部它只是ejs.__express的一个别名，因此你能够在不作任何事的状况下直接使用.ejs扩展。 
一些模板引擎没有遵循这种规范，consolidate.js库映射模板引擎如下面的使用方式，因此他们能够无缝的和Express工做。

 
  1. var engines = require('consolidate');
  2. app.engine('haml', engines.haml);
  3. app.engine('html', engines.hogan);
 

app.get(name)

得到设置名为name的app设置的值，此处的name是app settings table中各属性的一个。 
以下：

 
  1. app.get('title');
  2. // => undefined
  4. app.set('title', 'My Site');
  5. app.get('title');
  6. // => 'My Site'
 

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

路由HTTP GET请求到有特殊回调的特殊路径。获取更多的信息，能够查阅routing guide。 
你能够提供多个回调函数，它们的行为和中间件同样，除了这些回调能够经过调用next('router')来绕过剩余的路由回调。你可使用这个机制来为一个路由设置一些前提条件，若是请求没能知足当前路由的处理条件，那么传递控制到随后的路由。

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

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

绑定程序监听端口到指定的主机和端口号。这个方法和Node中的http.Server.listen()是同样的。

 
  1. var express = require('express');
  2. var app = express();
  3. app.listen(3000);

经过调用express()返回获得的app其实是一个JavaScript的Function，被设计用来做为一个回调传递给Node HTTP servers来处理请求。这样，其就能够很简便的基于同一份代码提供http和https版本，因此app没有从这些继承(它只是一个简单的回调)。

 
  1. var express = require('express');
  2. var https = require('https');
  3. var http = require('http');
  5. http.createServer(app).listen(80);
  6. https.createServer(options, app).listen(443);

app.listen()方法是下面所示的一个便利的方法(只针对HTTP协议):

 
  1. app.listen = function() {
  2. var server = http.createServer(this);
  3. return server.listen.apply(server, arguments);
  4. };
 

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

路由一个HTTP请求，METHOD是这个请求的HTTP方法，好比GET，PUT，POST等等，注意是小写的。因此，实际的方法是app.get()，app.post()，app.put()等等。下面有关于方法的完整的表。 
获取更多信息，请看routing guide。 
Express支持下面的路由方法，对应与同名的HTTP方法：

  • checkout
  • connect
  • copy
  • delete
  • get
  • head
  • lock
  • merge
  • mkactivity
  • mkcol
  • move
  • m-search
  • notify
  • options
  • patch
  • post
  • propfind
  • proppatch
  • purege
  • put
  • report
  • search
  • subscribe
  • trace
  • unlock
  • unsubscribe

若是使用上述方法时，致使了无效的javascript的变量名，可使用中括号符号，好比,app['m-search']('/', function ...

你能够提供多个回调函数，它们的行为和中间件同样，除了这些回调能够经过调用next('router')来绕过剩余的路由回调。你可使用这个机制来为一个路由设置一些前提条件，若是请求没有知足当前路由的处理条件，那么传递控制到随后的路由。

本API文档把使用比较多的HTTP方法app.get()，app.post，app.put()，app.delete()做为一个个单独的项进行说明。然而，其余上述列出的方法以彻底相同的方式工做。

app.all()是一个特殊的路由方法，它不属于HTTP协议中的规定的方法。它为一个路径加载中间件，其对全部的请求方法都有效。

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

app.param([name], callback)

给路由参数添加回调触发器，这里的name是参数名或者参数数组，function是回调方法。回调方法的参数按序是请求对象，响应对象，下个中间件，参数值和参数名。 
若是name是数组，会按照各个参数在数组中被声明的顺序将回调触发器注册下来。还有，对于除了最后一个参数的其余参数，在他们的回调中调用next()来调用下个声明参数的回调。对于最后一个参数，在回调中调用next()将调用位于当前处理路由中的下一个中间件，若是name只是一个string那就和它是同样的(就是说只有一个参数，那么就是最后一个参数，和数组中最后一个参数是同样的)。 
例如，当:user出如今路由路径中，你能够映射用户加载的逻辑处理来自动提供req.user给这个路由，或者对输入的参数进行验证。

 
  1. app.param('user', function(req, res, next, id) {
  2. User.find(id, function(error, user) {
  3. if (err) {
  4. next(err);
  5. }
  6. else if (user){
  7. req.user = user;
  8. } else {
  9. next(new Error('failed to load user'));
  10. }
  11. });
  12. });

对于Param的回调定义的路由来讲，他们是局部的。它们不会被挂载的app或者路由继承。因此，定义在app上的Param回调只有是在app上的路由具备这个路由参数时才起做用。 
在定义param的路由上，param回调都是第一个被调用的，它们在一个请求-响应循环中都会被调用一次而且只有一次，即便多个路由都匹配，以下面的例子：

 
  1. app.param('id', function(req, res, next, id) {
  2. console.log('CALLED ONLY ONCE');
  3. next();
  4. });
  6. app.get('/user/:id', function(req, res, next) {
  7. console.log('although this matches');
  8. next();
  9. });
  11. app.get('/user/:id', function(req, res) {
  12. console.log('and this mathces too');
  13. res.end();
  14. });

当GET /user/42，获得下面的结果:

 
  1. CALLED ONLY ONCE
  2. although this matches
  3. and this matches too
 
  1. app.param(['id', 'page'], function(req, res, next, value) {
  2. console.log('CALLED ONLY ONCE with', value);
  3. next();
  4. });
  6. app.get('/user/:id/:page', function(req. res, next) {
  7. console.log('although this matches');
  8. next();
  9. });
  11. app.get('/user/:id/:page', function (req, res, next) {
  12. console.log('and this matches too');
  13. res.end();
  14. });

当执行GET /user/42/3，结果以下：

 
  1. CALLED ONLY ONCE with 42
  2. CALLED ONLY ONCE with 3
  3. although this matches
  4. and this mathes too

下面章节描述的app.param(callback)在v4.11.0以后被弃用。

经过只传递一个回调参数给app.param(name, callback)方法，app.param(naem, callback)方法的行为将被彻底改变。这个回调参数是关于app.param(name, callback)该具备怎样的行为的一个自定义方法，这个方法必须接受两个参数而且返回一个中间件。 
这个回调的第一个参数就是须要捕获的url的参数名，第二个参数能够是任一的JavaScript对象，其可能在实现返回一个中间件时被使用。 
这个回调方法返回的中间件决定了当URL中包含这个参数时所采起的行为。 
在下面的例子中，app.param(name, callback)参数签名被修改为了app.param(name, accessId)。替换接受一个参数名和回调，app.param()如今接受一个参数名和一个数字。

 
  1. var express = require('express');
  2. var app = express();
  4. app.param(function(param, option){
  5. return function(req, res, next, val) {
  6. if (val == option) {
  7. next();
  8. }
  9. else {
  10. res.sendStatus(403);
  11. }
  12. }
  13. });
  15. app.param('id', 1337);
  17. app.get('/user/:id', function(req, res) {
  18. res.send('Ok');
  19. });
  21. app.listen(3000, function() {
  22. console.log('Ready');
  23. });

在这个例子中，app.param(name, callback)参数签名保持和原来同样，可是替换成了一个中间件，定义了一个自定义的数据类型检测方法来检测user id的类型正确性。

 
  1. app.param(function(param, validator) {
  2. return function(req, res, next, val) {
  3. if (validator(val)) {
  4. next();
  5. }
  6. else {
  7. res.sendStatus(403);
  8. }
  9. }
  10. });
  12. app.param('id', function(candidate) {
  13. return !isNaN(parseFloat(candidate)) && isFinite(candidate);
  14. });

在使用正则表达式来，不要使用.。例如，你不能使用/user-.+/来捕获user-gami，用使用[\\s\\S]或者[\\w\\>W]来代替(正如/user-[\\s\\S]+/)。

  1. //captures '1-a_6' but not '543-azser-sder'
  2. router.get('/[0-9]+-[[\\w]]*', function);
  4. //captures '1-a_6' and '543-az(ser"-sder' but not '5-a s'
  5. router.get('/[0-9]+-[[\\S]]*', function);
  7. //captures all (equivalent to '.*')
  8. router.get('[[\\s\\S]]*', function);
 

app.path()

经过这个方法能够获得app典型的路径，其是一个string。

 
  1. var app = express()
  2. , blog = express()
  3. , blogAdmin = express();
  5. app.use('/blog', blog);
  6. app.use('/admin', blogAdmin);
  8. console.log(app.path()); // ''
  9. console.log(blog.path()); // '/blog'
  10. console.log(blogAdmin.path()); // '/blog/admin'

若是app挂载很复杂下，那么这个方法的行为也会很复杂：一种更好用的方式是使用req.baseUrl来得到这个app的典型路径。

 

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

路由HTTP POST请求到有特殊回调的特殊路径。获取更多的信息，能够查阅routing guide。 
你能够提供多个回调函数，它们的行为和中间件同样，除了这些回调能够经过调用next('router')来绕过剩余的路由回调。你可使用这个机制来为一个路由设置一些前提条件，若是请求没能知足当前路由的处理条件，那么传递控制到随后的路由。

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

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

路由HTTP PUT请求到有特殊回调的特殊路径。获取更多的信息，能够查阅routing guide。 
你能够提供多个回调函数，它们的行为和中间件同样，除了这些回调能够经过调用next('router')来绕过剩余的路由回调。你可使用这个机制来为一个路由设置一些前提条件，若是请求没能知足当前路由的处理条件，那么传递控制到随后的路由。

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

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

经过callback回调返回一个view渲染以后获得的HTML文本。它能够接受一个可选的参数，可选参数包含了这个view须要用到的本地数据。这个方法相似于res.render()，除了它不能把渲染获得的HTML文本发送给客户端。

将app.render()看成是能够生成渲染视图字符串的工具方法。在res.render()内部，就是使用的app.render()来渲染视图。

若是使能了视图缓存，那么本地变量缓存就会保留。若是你想在开发的过程当中缓存视图，设置它为true。在生产环境中，视图缓存默认是打开的。

 
  1. app.render('email', function(err, html) {
  2. // ...
  3. });
  5. app.render('email', {name:'Tobi'}, function(err, html) {
  6. // ...
  7. });
 

app.route(path)

返回一个单例模式的路由的实例，以后你能够在其上施加各类HTTP动做的中间件。使用app.route()来避免重复路由名字(所以错字错误)--说的意思应该是使用app.router()这个单例方法来避免同一个路径多个路由实例。

 
  1. var app = express();
  3. app.route('/events')
  4. .all(function(req, res, next) {
  5. // runs for all HTTP verbs first
  6. // think of it as route specific middleware!
  7. })
  8. .get(function(req, res, next) {
  9. res.json(...);
  10. })
  11. .post(function(req, res, next) {
  12. // maybe add a new event...
  13. })
 

app.set(name, value)

给name设置项赋value值，name是app settings table中属性的一项。 
对于一个类型是布尔型的属性调用app.set('foo', ture)等价于调用app.enable('foo')。一样的，调用app.set('foo', false)等价于调用app.disable('foo')。 
可使用app.get()来取得设置的值：

 
  1. app.set('title', 'My Site');
  2. app.get('title'); // 'My Site'

Application Settings 
若是name是程序设置之一，它将影响到程序的行为。下边列出了程序中的设置。

Property Type Value Default
case sensitive routing Boolean 启用区分大小写。 不启用。对/Foo和/foo处理是同样。
env String 环境模型。 process.env.NODE_ENV(NODE_ENV环境变量)或者"development"
etag Varied 设置ETag响应头。可取的值，能够查阅etag options table。更多关于HTTP ETag header。 weak
jsonp callback name String 指定默认JSONP回调的名称。 ?callback=
json replacer String JSON替代品回调 null
json spaces Number 当设置了这个值后，发送缩进空格美化过的JSON字符串。 Disabled
query parser Varied 设置值为false来禁用query parser，或者设置simple,extended，也能够本身实现query string解析函数。simple基于Node原生的query解析，querystring。 "extend"
strict routing Boolean 启用严格的路由。 不启用。对/foo和/foo/的路由处理是同样。
subdomain offset Number 用来删除访问子域的主机点分部分的个数 2
trust proxy Varied 指示app在一个反向代理的后面，使用x-Forwarded-*来肯定链接和客户端的IP地址。注意:X-Forwarded-*头部很容易被欺骗，全部检测客户端的IP地址是靠不住的。trust proxy默认不启用。当启用时，Express尝试经过前端代理或者一系列代理来获取已链接的客户端IP地址。req.ips属性包含了已链接客户端IP地址的一个数组。为了启动它，须要设置在下面trust proxy options table中定义的值。trust proxy的设置实现使用了proxy-addr包。若是想得到更多的信息，能够查阅它的文档 Disable
views String or Array view所在的目录或者目录数组。若是是一个数组，将按在数组中的顺序来查找view。 process.cwd() + '/views'
view cache Boolean 启用视图模板编译缓存。 在生成环境默认开启。
view engine String 省略时，默认的引擎被扩展使用。  
x-powered-by Boolean 启用X-Powered-By:ExpressHTTP头部 true

Options for trust proxy settings 
查阅Express behind proxies来获取更多信息。

Type Value
Boolean

若是为true，客户端的IP地址做为X-Forwarded-*头部的最左边的条目。若是为false，能够理解为app直接与英特网直连，客户端的IP地址衍生自req.connection.remoteAddress。false是默认设置。
IP addresses

一个IP地址，子网，或者一组IP地址，和委托子网。下面列出的是一个预先配置的子网名列表。

  • loopback - 127.0.0.1/8, ::1/128
  • linklocal - 169.254.0.0/16, fe80::/10
  • uniquelocal - 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7

使用下面方法中的任何一种来设置IP地址:

app.set('trust proxy', 'loopback') // specify a single subnet app.set('trust proxy', 'loopback, 123.123.123.123') // specify a subnet and an address app.set('trust proxy', 'loopback, linklocal, uniquelocal') // specify multiple subnets as CSV app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']) // specify multiple subnets as an array

当指定IP地址以后, 这个IP地址或子网会被设置了这个IP地址或子网的`app`排除在外, 最靠近程序服务的没有委托的地址将被看作客户端IP地址。
Number

信任从反向代理到app中间小于等于n跳的链接为客户端。
Function

客户自定义委托代理信任机制。若是你使用这个，请确保你本身知道你在干什么。

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

Options for etag settings 
ETag功能的实现使用了etag包。若是你须要得到更多的信息，你能够查阅它的文档。

Type Value
Boolean

设置为true，启用weak ETag。这个是默认设置。设置false，禁用全部的ETag。
String 若是是strong，使能strong ETag。若是是weak，启用weak ETag。
Function

客户自定义`ETag`方法的实现. 若是你使用这个，请确保你本身知道你在干什么。

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

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

挂载中间件方法到路径上。若是路径未指定，那么默认为"/"。

一个路由将匹配任何路径若是这个路径以这个路由设置路径后紧跟着"/"。好比：app.use('/appale', ...)将匹配"/apple"，"/apple/images"，"/apple/images/news"等。

中间件中的req.originalUrl是req.baseUrl和req.path的组合，以下面的例子所示。

  1. app.use('/admin', function(req, res, next) {
  2. // GET 'http://www.example.com/admin/new'
  3. console.log(req.originalUrl); // '/admin/new'
  4. console.log(req.baseUrl); // '/admin'
  5. console.log(req.path);// '/new'
  6. });

在一个路径上挂载一个中间件以后，每当请求的路径的前缀部分匹配了这个路由路径，那么这个中间件就会被执行。 
因为默认的路径为/，中间件挂载没有指定路径，那么对于每一个请求，这个中间件都会被执行。

 
  1. // this middleware will be executed for every request to the app.
  2. app.use(function(req, res, next) {
  3. console.log('Time: %d', Date.now());
  4. next();
  5. });

中间件方法是顺序处理的，因此中间件包含的顺序是很重要的。

 
  1. // this middleware will not allow the request to go beyond it
  2. app.use(function(req, res, next) {
  3. res.send('Hello World');
  4. });
  6. // this middleware will never reach this route
  7. app.use('/', function(req, res) {
  8. res.send('Welcome');
  9. });

路径能够是表明路径的一串字符，一个路径模式，一个匹配路径的正则表达式，或者他们的一组集合。

下面是路径的简单的例子。

Type Example
Path 
// will match paths starting with /abcd
app.use('/abcd', function (req, res, next) { next(); })
Path Pattern 
// will match paths starting with /abcd and /abd
app.use('/abc?d', function (req, res, next) { next(); }) // will match paths starting with /abcd, /abbcd, /abbbbbcd and so on app.use('/ab+cd', function (req, res, next) { next(); }) // will match paths starting with /abcd, /abxcd, /abFOOcd, /abbArcd and so on app.use('/ab\*cd', function (req, res, next) { next(); }) // will match paths starting with /ad and /abcd app.use('/a(bc)?d', function (req, res, next) { next(); })
Regular Expression 
// will match paths starting with /abc and /xyz
app.use(/\/abc|\/xyz/, function (req, res, next) { next(); })
Array 
// will match paths starting with /abcd, /xyza, /lmn, and /pqr
app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], function (req, res, next) { next(); })

方法能够是一个中间件方法，一系列中间件方法，一组中间件方法或者他们的集合。因为router和app实现了中间件接口，你能够像使用其余任一中间件方法那样使用它们。

Usage Example
单个中间件 你能够局部定义和挂载一个中间件。 
app.use(function (req, res, next) { next(); })
一个router是有效的中间件。 
var router = express.Router(); router.get('/', function (req, res, next) { next(); }) app.use(router);
一个Express程序是一个有效的中间件。 
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目录下的静态资源：

 
  1. // GET /style.css etc
  2. app.use(express.static(__dirname + '/public'));

在/static路径下挂载中间件来提供静态资源托管服务，只当请求是以/static为前缀的时候。

 
  1. // GET /static/style.css etc.
  2. app.use('/static', express.static(express.__dirname + '/public'));

经过在设置静态资源中间件以后加载日志中间件来关闭静态资源请求的日志。

 
  1. app.use(express.static(__dirname + '/public'));
  2. app.use(logger());

托管静态资源从不一样的路径，但./public路径比其余更容易被匹配：

 
  1. app.use(express.static(__dirname + '/public'));
  2. app.use(express.static(__dirname + '/files'));
  3. app.use(express.static(__dirname + '/uploads'));
 

Request

req对象表明了一个HTTP请求，其具备一些属性来保存请求中的一些数据，好比query string，parameters，body，HTTP headers等等。在本文档中，按照惯例，这个对象老是简称为req(http响应简称为res)，可是它们实际的名字由这个回调方法在那里使用时的参数决定。 
以下例子:

 
  1. app.get('/user/:id', function(req, res) {
  2. res.send('user' + req.params.id);
  3. });

其实你也能够这样写：

 
  1. app.get('/user/:id', function(request, response) {
  2. response.send('user' + request.params.id);
  3. });
 

Properties

在Express 4中，req.files默认在req对象中再也不是可用的。为了经过req.files对象来得到上传的文件，你可使用一个multipart-handling(多种处理的工具集)中间件，好比busboy，multer，formidable，multipraty，connect-multiparty或者pez。

 

req.app

这个属性持有express程序实例的一个引用，其能够做为中间件使用。 
若是你按照这个模式，你建立一个模块导出一个中间件，这个中间件只在你的主文件中require()它，那么这个中间件能够经过req.app来获取express的实例。 
例如:

 
  1. // index.js
  2. app.get("/viewdirectory", require('./mymiddleware.js'));
 
  1. // mymiddleware.js
  2. module.exports = function(req, res) {
  3. res.send('The views directory is ' + req.app.get('views'));
  4. };
 

req.baseUrl

一个路由实例挂载的Url路径。

 
  1. var greet = express.Router();
  2. greet.get('/jp', function(req, res) {
  3. console.log(req.baseUrl); // greet
  4. res.send('Konichiwa!');
  5. });
  6. app.use('/greet', greet);

即便你使用的路径模式或者一系列路径模式来加载路由，baseUrl属性返回匹配的字符串，而不是路由模式。下面的例子，greet路由被加载在两个路径模式上。

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

当一个请求路径是/greet/jp，baseUrl是/greet，当一个请求路径是/hello/jp，req.baseUrl是/hello。 
req.baseUrl和app对象的mountpath属性类似，除了app.mountpath返回的是路径匹配模式。

 

req.body

在请求的body中保存的是提交的一对对键值数据。默认状况下，它是undefined，当你使用好比body-parser和multer这类解析body数据的中间件时，它是填充的。 
下面的例子，给你展现了怎么使用body-parser中间件来填充req.body。

 
  1. var app = require('express');
  2. var bodyParser = require('body-parser');
  3. var multer = require('multer')；// v1.0.5
  4. var upload = multer(); // for parsing multipart/form-data
  5. app.use(bodyParser.json()); // for parsing application/json
  6. app.use(bodyParser.urlencoded({extended:true})); // for parsing application/x-www-form-urlencoded
  8. app.post('/profile', upload.array(), function(req, res, next) {
  9. console.log(req.body);
  10. res.json(req.body);
  11. });
 

req.cookies

当使用cookie-parser中间件的时候，这个属性是一个对象，其包含了请求发送过来的cookies。若是请求没有带cookies，那么其值为{}。

 
  1. // Cookie: name=tj
  2. req.cookies.name
  3. // => "tj"

获取更多信息，问题，或者关注，能够查阅cookie-parser。

 

req.fresh

指示这个请求是不是新鲜的。其和req.stale是相反的。 
当cache-control请求头没有no-cache指示和下面中的任一一个条件为true，那么其就为true：

  • if-modified-since请求头被指定，和last-modified请求头等于或者早于modified响应头。
  • if-none-match请求头是*。
  • if-none-match请求头在被解析进它的指令以后，不匹配etag响应头(彻底不知道什么鬼)。
 
  1. req.fresh
  2. // => true
 

req.hostname

包含了源自HostHTTP头部的hostname。 
当trust proxy设置项被设置为启用值，X-Forwarded-Host头部被使用来代替Host。这个头部能够被客户端或者代理设置。

 
  1. // Host: "example.com"
  2. req.hostname
  3. // => "example.com"
 

req.ips

当trust proxy设置项被设置为启用值，这个属性包含了一组在X-Forwarded-For请求头中指定的IP地址。否则，其就包含一个空的数组。这个头部能够被客户端或者代理设置。 
例如，若是X-Forwarded-For是client，proxy1，proxy2，req.ips就是["clinet", "proxy1", "proxy2"]，这里proxy2就是最远的下游。

 

req.originalUrl

req.url不是一个原生的Express属性，它继承自Node's http module。

这个属性很像req.url；然而，其保留了原版的请求连接，容许你自由地重定向req.url到内部路由。好比，app.use()的mounting特色能够重定向req.url跳转到挂载点。

 
  1. // GET /search?q=something
  2. req.originalUrl
  3. // => "/search?q=something"
 

req.params

一个对象，其包含了一系列的属性，这些属性和在路由中命名的参数名是一一对应的。例如，若是你有/user/:name路由，name属性可做为req.params.name。这个对象默认值为{}。

 
  1. // GET /user/tj
  2. req.params.name
  3. // => "tj"

当你使用正则表达式来定义路由规则，捕获组的组合通常使用req.params[n]，这里的n是第几个捕获租。这个规则被施加在无名通配符匹配，好比/file/*的路由：

 
  1. // GET /file/javascripts/jquery.js
  2. req.params[0]
  3. // => "javascripts/jquery.js"
 

req.path

包含请求URL的部分路径。

 
  1. // example.com/users?sort=desc
  2. req.path
  3. // => "/users"

当在一个中间件中被调用，挂载点不包含在req.path中。你能够查阅app.use()得到跟多的信息。

 

req.protocol

请求的协议，通常为http，当启用TLS加密，则为https。 
当trust proxy设置一个启用的参数，若是存在X-Forwarded-Proto头部的话，其将被信赖和使用。这个头部能够被客户端或者代理设置。

 
  1. req.ptotocol
  2. // => "http"
 

req.query

一个对象，为每个路由中的query string参数都分配一个属性。若是没有query string，它就是一个空对象，{}。

 
  1. // GET /search?q=tobi+ferret
  2. req.query.q
  3. // => "tobi ferret"
  5. // GET /shoes?order=desc&shoe[color]=blue&shoe[type]=converse
  6. req.query.order
  7. // => "desc"
  9. req.query.shoe.color
  10. // => "blue"
  12. req.query.shoe.type
  13. // => "converse"
 

req.route

当前匹配的路由，其为一串字符。好比：

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

前面片断的输出为:

 
  1. { path:"/user/:id?"
  2. stack:
  3. [
  4. { handle:[Function:userIdHandler],
  5. name:"userIdHandler",
  6. params:undefined,
  7. path:undefined,
  8. keys:[],
  9. regexp:/^\/?$/i,
  10. method:'get'
  11. }
  12. ]
  13. methods:{get:true}
  14. }
 

req.secure

一个布尔值，若是创建的是TLS的链接，那么就为true。等价与：

 
  1. 'https' == req.protocol;
 

req.signedCookies

当使用cookie-parser中间件的时候，这个属性包含的是请求发过来的签名cookies，不签名的而且为使用作好了准备(这句真不知道怎么翻译了...)。签名cookies驻留在不一样的对象中来体现开发者的意图；否则，一个恶意攻击能够被施加在req.cookie值上(它是很容易被欺骗的)。记住，签名一个cookie不是把它藏起来或者加密；而是简单的防止篡改(由于签名使用的加密是私人的)。若是没有发送签名的cookie，那么这个属性默认为{}。

 
  1. // Cookie： user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
  2. req.signedCookies.user
  3. // => "tobi"

为了获取更多的信息，问题或者关注，能够参阅cookie-parser。

 

req.stale

指示这个请求是不是stale(陈旧的)，它与req.fresh是相反的。更多信息，能够查看req.fresh。

 
  1. req.stale
  2. // => true
 

req.subdomains

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

 
  1. // Host: "tobi.ferrets.example.com"
  2. req.subdomains
  3. // => ["ferrets", "tobi"]
 

req.xhr

一个布尔值，若是X-Requested-With的值为XMLHttpRequest，那么其为true，其指示这个请求是被一个客服端库发送，好比jQuery。

 
  1. req.xhr
  2. // => true
 

Methods

 

req.accepts(types)

检查这个指定的内容类型是否被接受，基于请求的Accept HTTP头部。这个方法返回最佳匹配，若是没有一个匹配，那么其返回undefined(在这个case下，服务器端应该返回406和"Not Acceptable")。 
type值能够是一个单的MIME type字符串(好比application/json)，一个扩展名好比json，一个逗号分隔的列表，或者一个数组。对于一个列表或者数组，这个方法返回最佳项(若是有的话)。

 
  1. // Accept: text/html
  2. req.accepts('html');
  3. // => "html"
  5. // Accept: text/*, application/json
  6. req.accepts('html');
  7. // => "html"
  9. req.accepts('text/html');
  10. // => "text/html"
  12. req.accepts(['json', 'text']);
  13. // => "json"
  15. req.accepts('application/json');
  16. // => "application/json"
  18. // Accept: text/*, application/json
  19. req.accepts('image/png');
  20. req.accepts('png');
  21. // => undefined
  23. // Accept: text/*;q=.5, application/json
  24. req.accepts(['html', 'json']);
  25. // => "json"

获取更多信息，或者若是你有问题或关注，能够参阅accepts。

 

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

返回指定的字符集集合中第一个的配置的字符集，基于请求的Accept-CharsetHTTP头。若是指定的字符集没有匹配的，那么就返回false。 
获取更多信息，或者若是你有问题或关注，能够参阅accepts。

 

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

返回指定的编码集合中第一个的配置的编码，基于请求的Accept-EncodingHTTP头。若是指定的编码集没有匹配的，那么就返回false。 
获取更多信息，或者若是你有问题或关注，能够参阅accepts。

 

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

返回指定的语言集合中第一个的配置的语言，基于请求的Accept-LanguageHTTP头。若是指定的语言集没有匹配的，那么就返回false。 
获取更多信息，或者若是你有问题或关注，能够参阅accepts。

 

req.get(field)

返回指定的请求HTTP头部的域内容(不区分大小写)。Referrer和Referer的域内容可互换。

 
  1. req.get('Content-type');
  2. // => "text/plain"
  4. req.get('content-type');
  5. // => "text/plain"
  7. req.get('Something')
  8. // => undefined

其是req.header(field)的别名。

 

req.is(type)

若是进来的请求的Content-type头部域匹配参数type给定的MIME type，那么其返回true。不然返回false。

 
  1. // With Content-Type: text/html; charset=utf-8
  2. req.is('html');
  3. req.is('text/html');
  4. req.is('text/*');
  5. // => true
  7. // When Content-Type is application/json
  8. req.is('json');
  9. req.is('application/json');
  10. req.is('application/*');
  11. // => true
  13. req.is('html');
  14. // => false

获取更多信息，或者若是你有问题或关注，能够参阅type-is。

 

req.param(naem, [, defaultValue])

过期的。能够在适合的状况下，使用req.params，req.body或者req.query。

返回当前参数name的值。

 
  1. // ?name=tobi
  2. req.param('name')
  3. // => "tobi"
  5. // POST name=tobi
  6. req.param('name')
  7. // => "tobi"
  8. // /user/tobi for /user/:name
  9. req.param('name')
  10. // => "tobi"

按下面给出的顺序查找：

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

可选的，你能够指定一个defaultValue来设置一个默认值，若是这个参数在任何一个请求的对象中都不能找到。

直接经过req.params，req.body，req.query取得应该更加的清晰-除非你肯定每个对象的输入。 
Body-parser中间件必须加载，若是你使用req.param()。详细请看req.body。

 

Response

res对象表明了当一个HTTP请求到来时，Express程序返回的HTTP响应。在本文档中，按照惯例，这个对象老是简称为res(http请求简称为req)，可是它们实际的名字由这个回调方法在那里使用时的参数决定。 
例如：

 
  1. app.get('/user/:id', function(req, res) {
  2. res.send('user' + req.params.id);
  3. });

这样写也是同样的：

 
  1. app.get('/user/:id', function(request, response) {
  2. response.send('user' + request.params.id);
  3. });
 

Properties

 

res.app

这个属性持有express程序实例的一个引用，其能够在中间件中使用。 
res.app和请求对象中的req.app属性是相同的。

 

res.headersSent

布尔类型的属性，指示这个响应是否已经发送HTTP头部。

 
  1. app.get('/', function(req, res) {
  2. console.log(res.headersSent); // false
  3. res.send('OK'); // send以后就发送了头部
  4. console.log(res.headersSent); // true
  5. });
 

res.locals

一个对象，其包含了响应的可以反应出请求的本地参数和所以只提供给视图渲染，在请求响应的周期内(若是有的话)--我要翻译吐了。不然，其和app.locals是同样的。(不知道翻译的什么...) 
这个参数在导出请求级别的信息是颇有效的，这些信息好比请求路径，已认证的用户，用户设置等等。

 
  1. app.use(function(req, res, next) {
  2. res.locals.user = req.user;
  3. res.locals.authenticated = !req.user.anonymous;
  4. next();
  5. });
 

Methods

 

res.append(field [, value])

res.append()方法在Expresxs4.11.0以上版本才支持。

在指定的field的HTTP头部追加特殊的值value。若是这个头部没有被设置，那么将用value新建这个头部。value能够是一个字符串或者数组。 
注意：在res.append()以后调用app.set()函数将重置前面设置的值。

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

res.attachment([filename])

设置HTTP响应的Content-Disposition头内容为"attachment"。若是提供了filename，那么将经过res.type()得到扩展名来设置Content-Type，而且设置Content-Disposition内容为"filename="parameter。

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

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

设置name和value的cookie，value参数能够是一串字符或者是转化为json字符串的对象。 
options是一个对象，其能够有下列的属性。

属性 类型 描述
domain String 设置cookie的域名。默认是你本app的域名。
expires Date cookie的过时时间，GMT格式。若是没有指定或者设置为0，则产生新的cookie。
httpOnly Boolean 这个cookie只能被web服务器获取的标示。
maxAge String 是设置过去时间的方便选项，其为过时时间到当前时间的毫秒值。
path String cookie的路径。默认值是/。
secure Boolean 标示这个cookie只用被HTTPS协议使用。
signed Boolean 指示这个cookie应该是签名的。

res.cookie()所做的都是基于提供的options参数来设置Set-Cookie头部。没有指定任何的options，那么默认值在RFC6265中指定。

使用实例：

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

maxAge是一个方便设置过时时间的方便的选项，其以当前时间开始的毫秒数来计算。下面的示例和上面的第二条功效同样。

 
  1. res.cookie('rememberme', '1', {'masAge':90000}, "httpOnly":true);

你能够设置传递一个对象做为value的参数。而后其将被序列化为Json字符串，被bodyParser()中间件解析。

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

当咱们使用cookie-parser中间件的时候，这个方法也支持签名的cookie。简单地，在设置options时包含signed选项为true。而后res.cookie()将使用传递给cookieParser(secret)的密钥来签名这个值。

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

res.clearCookie(name [,options])

根据指定的name清除对应的cookie。更多关于options对象能够查阅res.cookie()。

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

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

传输path指定文件做为一个附件。一般，浏览器提示用户下载。默认状况下，Content-Disposition头部"filename="的参数为path(一般会出如今浏览器的对话框中)。经过指定filename参数来覆盖默认值。 
当一个错误发生时或者传输完成，这个方法将调用fn指定的回调方法。这个方法使用res.sendFile()来传输文件。

 
  1. res.download('/report-12345.pdf');
  3. res.download('/report-12345.pdf', 'report.pdf');
  5. res.download('report-12345.pdf', 'report.pdf', function(err) {
  6. // Handle error, but keep in mind the response may be partially-sent
  7. // so check res.headersSent
  8. if (err) {
  9. } else {
  10. // decrement a download credit, etc.
  11. }
  12. });
 

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

结束本响应的过程。这个方法实际上来自Node核心模块，具体的是response.end() method of http.ServerResponse。 
用来快速结束请求，没有任何的数据。若是你须要发送数据，可使用res.send()和res.json()这类的方法。

 
  1. res.end();
  2. res.status(404).end();
 

res.format(object)

进行内容协商，根据请求的对象中AcceptHTTP头部指定的接受内容。它使用req.accepts()来选择一个句柄来为请求服务，这些句柄按质量值进行排序。若是这个头部没有指定，那么第一个方法默认被调用。当不匹配时，服务器将返回406"Not Acceptable"，或者调用default回调。 
Content-Type请求头被设置，当一个回调方法被选择。然而你能够改变他，在这个方法中使用这些方法，好比res.set()或者res.type()。 
下面的例子，将回复{"message":"hey"}，当请求的对象中Accept头部设置成"application/json"或者"*/json"(不过若是是*/*，而后这个回复就是"hey")。

 
  1. res.format({
  2. 'text/plain':function() {
  3. res.send('hey')'
  4. },
  5. 'text/html':function() {
  6. res.send('<p>hey</p>');
  7. },
  8. 'application/json':function() {
  9. res.send({message:'hey'});
  10. },
  11. 'default':function() {
  12. res.status(406).send('Not Acceptable');
  13. }
  14. })

除了规范化的MIME类型以外，你也可使用拓展名来映射这些类型来避免冗长的实现：

 
  1. res.format({
  2. text:function() {
  3. res.send('hey');
  4. },
  5. html:function() {
  6. res.send('<p>hey</p>');
  7. },
  8. json:function() {
  9. res.send({message:'hey'});
  10. }
  11. })
 

res.get(field)

返回field指定的HTTP响应的头部。匹配是区分大小写。

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

res.json([body])

发送一个json的响应。这个方法和将一个对象或者一个数组做为参数传递给res.send()方法的效果相同。不过，你可使用这个方法来转换其余的值到json，例如null，undefined。(虽然这些都是技术上无效的JSON)。

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

res.jsonp([body])

发送一个json的响应，而且支持JSONP。这个方法和res.json()效果相同，除了其在选项中支持JSONP回调。

 
  1. res.jsonp(null)
  2. // => null
  4. res.jsonp({user:'tobi'})
  5. // => {"user" : "tobi"}
  7. res.status(500).jsonp({error:'message'})
  8. // => {"error" : "message"}

默认状况下，jsonp的回调方法简单写做callback。能够经过jsonp callback name设置来重写它。 
下面是一些例子使用JSONP响应，使用相同的代码:

 
  1. // ?callback=foo
  2. res.jsonp({user:'tobo'})
  3. // => foo({"user":"tobi"})
  5. app.set('jsonp callback name', 'cb')
  7. // ?cb=foo
  8. res.status(500).jsonp({error:'message'})
  9. // => foo({"error":"message"})
 

链接这些links，links是以传入参数的属性形式提供，链接以后的内容用来填充响应的Link HTTP头部。

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

效果：

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

res.location(path)

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

 
  1. res.location('/foo/bar');
  2. res.location('http://example.com');
  3. res.location('back');

当path参数为back时，其具备特殊的意义，其指定URL为请求对象的Referer头部指定的URL。若是请求中没有指定，那么其即为"/"。

Express传递指定的URL字符串做为回复给浏览器响应中的Location头部的值，不检测和操做，除了当是back这个case时。浏览器有推导预期URL从当前的URL或者指定的URL，和在Location指定的URL的责任；相应地重定向它。(我也不知道翻译的什么...)

 

res.redirect([status,] path)

重定向来源于指定path的URL，以及指定的HTTP status codestatus。若是你没有指定status，status code默认为"302 Found"。

 
  1. res.redirect('/foo/bar');
  2. res.redirect('http://example.com');
  3. res.redirect(301, 'http://example.com');
  4. res.redirect('../login');

重定向也能够是完整的URL，来重定向到不一样的站点。

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

重定向也能够相对于主机的根路径。好比，若是程序的路径为http://example.com/admin/post/new，那么下面将重定向到http://example.com/admim:

 
  1. res.redirect('/admin');

重定向也能够相对于当前的URL。好比，来之于http://example.com/blog/admin/(注意结尾的/)，下面将重定向到http://example.com/blog/admin/post/new。

 
  1. 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：

 
  1. res.redirect('..');

back将重定向请求到referer，当没有referer的时候，默认为/。

 
  1. res.redirect('back');
 

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

渲染一个视图，而后将渲染获得的HTML文档发送给客户端。可选的参数为:

  • locals，定义了视图本地参数属性的一个对象。
  • callback，一个回调方法。若是提供了这个参数，render方法将返回错误和渲染以后的模板，而且不自动发送响应。当有错误发生时，能够在这个回调内部，调用next(err)方法。

本地变量缓存使能视图缓存。在开发环境中缓存视图，须要手动设置为true；视图缓存在生产环境中默认开启。

 
  2. // send the rendered view to the client
  3. res.render('index');
  5. // if a callback is specified, the render HTML string has to be sent explicitly
  7. res.render('index', function(err, html) {
  8. res.send(html);
  9. });
  11. // pass a local variable to the view
  12. res.render('user', {name:'Tobi'}, function(err, html) {
  13. // ...
  14. });
 

res.send([body])

发送HTTP响应。 
body参数能够是一个Buffer对象，一个字符串，一个对象，或者一个数组。好比：

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

对于通常的非流请求，这个方法能够执行许多有用的的任务：好比，它自动给Content-LengthHTTP响应头赋值(除非先前定义)，也支持自动的HEAD和HTTP缓存更新。 
当参数是一个Buffer对象，这个方法设置Content-Type响应头为application/octet-stream，除非事先提供，以下所示:

 
  1. res.set('Content-Type', 'text/html');
  2. res.send(new Buffer('<p>some html</p>'));

当参数是一个字符串，这个方法设置Content-Type响应头为text/html：

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

当参数是一个对象或者数组，Express使用JSON格式来表示：

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

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

res.sendFile()从Express v4.8.0开始支持。

传输path指定的文件。根据文件的扩展名设置Content-TypeHTTP头部。除非在options中有关于root的设置，path必定是关于文件的绝对路径。 
下面的表提供了options参数的细节:

属性 描述 默认值 可用版本
maxAge 设置Cache-Control的max-age属性，格式为毫秒数，或者是ms format的一串字符串 0  
root 相对文件名的根目录    
lastModified 设置Last-Modified头部为此文件在系统中的最后一次修改时间。设置false来禁用它 Enable 4.9.0+
headers 一个对象，包含了文件所在的sever的HTTP头部。(不知道怎么翻译了)    
dotfiles 是否支持点开头文件名的选项。可选的值"allow","deny","ignore" "ignore"  

当传输完成或者发生了什么错误，这个方法调用fn回调方法。若是这个回调参数指定了和一个错误发生，回调方法必须明确地经过结束请求-响应循环或者传递控制到下个路由来处理响应过程。 
下面是使用了全部参数的使用res.sendFile()的例子：

 
  1. app.get('/file/:name', function(req, res, next) {
  3. var options = {
  4. root:__dirname + '/public',
  5. dotfile:'deny',
  6. headers:{
  7. 'x-timestamp':Date.now(),
  8. 'x-sent':true
  9. }
  10. };
  12. var fileName = req.params.name;
  13. res.sendFile(fileName, options, function(err) {
  14. if (err) {
  15. console.log(err);
  16. res.status(err.status).end();
  17. }
  18. else {
  19. console.log('sent', fileName);
  20. }
  21. });
  25. });

res.sendFile提供了文件服务的细粒度支持，以下例子说明：

 
  1. app.get('/user/:uid/photos/:file', function(req, res) {
  2. var uid = req.params.uid
  3. , file = req.params.file;
  6. req.user.mayViewFilesFrom(uid, function(yes) {
  7. if (yes) {
  8. res.sendFile('/upload/' + uid + '/' + file);
  9. }
  10. else {
  11. res.status(403).send('Sorry! you cant see that.');
  12. }
  13. });
  15. })

获取更多信息，或者你有问题或者关注，能够查阅send。

 

res.sendStatus(statusCode)

设置响应对象的HTTP status code为statusCode而且发送statusCode的相应的字符串形式做为响应的Body。

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

若是一个不支持的状态被指定，这个HTTP status依然被设置为statusCode而且用这个code的字符串做为Body。

 
  1. res.sendStatus(2000); // equivalent to res.status(2000).send('2000');

More about HTTP Status Codes

 

res.set(field [, value])

设置响应对象的HTTP头部field为value。为了一次设置多个值，那么能够传递一个对象为参数。

 
  1. res.set('Content-Type', 'text/plain');
  3. res.set({
  4. 'Content-Type':'text/plain',
  5. 'Content-Length':'123',
  6. 'ETag':'123456'
  7. })

其和res.header(field [,value])效果一致。

 

res.status(code)

使用这个方法来设置响应对象的HTTP status。其是Node中response.statusCode的一个连贯性的别名。

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

res.type(type)

设置Content-TypeHTTP头部为MIME type，若是这个指定的type可以被mime.lookup肯定。若是type包含/字符，那么设置Content-Type为type(我已经晕了)。

 
  1. res.type('.html');  // => 'text/html'
  2. res.type('html');  // => 'text/html'
  3. res.type('json');  // => 'application/json'
  4. res.type('application/json');  // => 'application/json'
  5. res.type('png');  // => image/png:
 

res.vary(field)

设置Vary响应头为field，若是已经不在那里。(不懂什么意思)

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

Router

一个router对象是一个单独的实例关于中间件和路由。你能够认为其是一个"mini-application"（迷你程序），其具备操做中间件和路由方法的能力。每一个Express程序有一个内建的app路由。 
路由自身表现为一个中间件，因此你可使用它做为app.use()方法的一个参数或者做为另外一个路由的use()的参数。 
顶层的express对象有一个Router()方法，你可使用Router()来建立一个新的router对象。

 

Router([options])

以下，能够建立一个路由：

 
  1. var router = express.Router([options]);

options参数能够指定路由的行为，其有下列选择：

属性 描述 默认值 可用性
caseSensitive 是否区分大小写 默认不启用。对待/Foo和/foo同样。  
mergeParams 保存父路由的res.params。若是父路由参数和子路由参数冲突，子路由参数优先。 false 4.5.0+
strict 使能严格路由。 默认不启用，/foo和/foo/被路由同样对待处理  

你能够将router看成一个程序，能够在其上添加中间件和HTTP路由方法(例如get，put，post等等)。

 
  1. // invoked for any requests passed to this router
  2. router.use(function(req, res, next) {
  3. // .. some logic here .. like any other middleware
  4. next();
  5. });
  7. // will handle any request that ends in /events
  8. // depends on where the router is "use()'d"
  9. router.get('/events', function(req, res, next) {
  10. // ..
  11. });

你能够在一个特别的根URL上挂载一个路由，这样你就以将你的各个路由放到不一样的文件中或者甚至是mini的程序。

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

Methods

 

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

这个方法和router.METHOD()方法同样，除了这个方法会匹配全部的HTTP动做。 
这个方法对想映射全局的逻辑处理到特殊的路径前缀或者任意匹配是十分有用的。好比，若是你放置下面所示的这个路由在其余路由的前面，那么其将要求从这个点开始的全部的路由进行验证操做和自动加载用户信息。记住，这些全局的逻辑操做，不须要结束请求响应周期：loaduser能够执行一个任务，而后调用next()来将执行流程移交到随后的路由。

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

相等的形式:

 
  1. router.all('*', requireAuthentication)
  2. router.all('*', loadUser);

这是一个白名单全局功能的例子。这个例子很像前面的，不过其仅仅做用于以/api开头的路径:

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

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

router.METHOD()方法提供了路由方法在Express中，这里的METHOD是HTTP方法中的一个，好比GET，PUT，POST等等，但router中的METHOD是小写的。因此，实际的方法是router.get()，router.put()，router.post()等等。 
你能够提供多个回调函数，它们的行为和中间件同样，除了这些回调能够经过调用next('router')来绕过剩余的路由回调。你可使用这个机制来为一个路由设置一些前提条件，若是请求没有知足当前路由的处理条件，那么传递控制到随后的路由。 
下面的片断可能说明了最简单的路由定义。Experss转换path字符串为正则表达式，用于内部匹配传入的请求。在匹配的时候，是不考虑Query strings，例如，"GET /"将匹配下面的路由，"GET /?name=tobi"也是同样的。

 
  1. router.get('/', function(req, res) {
  2. res.send('Hello World');
  3. });

若是你对匹配的path有特殊的限制，你可使用正则表达式，例如，下面的能够匹配"GET /commits/71dbb9c"和"GET /commits/71bb92..4c084f9"。

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

router.param(name, callback)

给路由参数添加回调触发器，这里的name是参数名，function是回调方法。回调方法的参数按序是请求对象，响应对象，下个中间件，参数值和参数名。虽然name在技术上是可选的，可是自Express V4.11.0以后版本不推荐使用(见下面)。

不像app.param()，router.param()不接受一个数组做为路由参数。

例如，当:user出如今路由路径中，你能够映射用户加载的逻辑处理来自动提供req.user给这个路由，或者对输入的参数进行验证。

 
  1. router.param('user', function(req, res, next, id) {
  2. User.find(id, function(error, user) {
  3. if (err) {
  4. next(err);
  5. }
  6. else if (user){
  7. req.user = user;
  8. } else {
  9. next(new Error('failed to load user'));
  10. }
  11. });
  12. });

对于Param的回调定义的路由来讲，他们是局部的。它们不会被挂载的app或者路由继承。因此，定义在router上的param回调只有是在router上的路由具备这个路由参数时才起做用。 
在定义param的路由上，param回调都是第一个被调用的，它们在一个请求-响应循环中都会被调用一次而且只有一次，即便多个路由都匹配，以下面的例子：

 
  1. router.param('id', function(req, res, next, id) {
  2. console.log('CALLED ONLY ONCE');
  3. next();
  4. });
  6. router.get('/user/:id', function(req, res, next) {
  7. console.log('although this matches');
  8. next();
  9. });
  11. router.get('/user/:id', function(req, res) {
  12. console.log('and this mathces too');
  13. res.end();
  14. });

当GET /user/42，获得下面的结果:

 
  1. CALLED ONLY ONCE
  2. although this matches
  3. and this matches too

`

下面章节描述的router.param(callback)在v4.11.0以后被弃用。

经过只传递一个回调参数给router.param(name, callback)方法，router.param(naem, callback)方法的行为将被彻底改变。这个回调参数是关于router.param(name, callback)该具备怎样的行为的一个自定义方法，这个方法必须接受两个参数而且返回一个中间件。 
这个回调的第一个参数就是须要捕获的url的参数名，第二个参数能够是任一的JavaScript对象，其可能在实现返回一个中间件时被使用。 
这个回调方法返回的中间件决定了当URL中包含这个参数时所采起的行为。 
在下面的例子中，router.param(name, callback)参数签名被修改为了router.param(name, accessId)。替换接受一个参数名和回调，router.param()如今接受一个参数名和一个数字。

 
  1. var express = require('express');
  2. var app = express();
  3. var router = express.Router();
  5. router.param(function(param, option){
  6. return function(req, res, next, val) {
  7. if (val == option) {
  8. next();
  9. }
  10. else {
  11. res.sendStatus(403);
  12. }
  13. }
  14. });
  16. router.param('id', 1337);
  18. router.get('/user/:id', function(req, res) {
  19. res.send('Ok');
  20. });
  22. app.use(router);
  24. app.listen(3000, function() {
  25. console.log('Ready');
  26. });

在这个例子中，router.param(name. callback)参数签名保持和原来同样，可是替换成了一个中间件，定义了一个自定义的数据类型检测方法来检测user id的类型正确性。

 
  1. router.param(function(param, validator) {
  2. return function(req, res, next, val) {
  3. if (validator(val)) {
  4. next();
  5. }
  6. else {
  7. res.sendStatus(403);
  8. }
  9. }
  10. });
  12. router.param('id', function(candidate) {
  13. return !isNaN(parseFloat(candidate)) && isFinite(candidate);
  14. });
 

router.route(path)

返回一个单例模式的路由的实例，以后你能够在其上施加各类HTTP动做的中间件。使用app.route()来避免重复路由名字(所以错字错误)--后面这句不知道说的什么鬼，大概的意思就是避免同一个路径有两个路由实例。 
构建在上面的router.param()例子之上，下面的代码展现了怎么使用router.route()来指定各类HTTP方法的处理句柄。

 
  1. var router = express.Router();
  3. router.param('user_id', function(req, res, next, id) {
  4. // sample user, would actually fetch from DB, etc...
  5. req.user = {
  6. id:id,
  7. name:"TJ"
  8. };
  9. next();
  10. });
  12. router.route('/users/:user_id')
  13. .all(function(req, res, next) {
  14. // runs for all HTTP verbs first
  15. // think of it as route specific middleware!
  16. next();
  17. })
  18. .get(function(req, res, next) {
  19. res.json(req.user);
  20. })
  21. .put(function(req, res, next) {
  22. // just an example of maybe updating the user
  23. req.user.name = req.params.name;
  24. // save user ... etc
  25. res.json(req.user);
  26. })
  27. .post(function(req, res, next) {
  28. next(new Error('not implemented'));
  29. })
  30. .delete(function(req, res, next) {
  31. next(new Error('not implemented'));
  32. })

这种方法重复使用单个/usrs/:user_id路径来添加了各类的HTTP方法。

 

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

给可选的path参数指定的路径挂载给定的中间件方法，未指定path参数，默认值为/。 
这个方法相似于app.use()。一个简单的例子和用例在下面描述。查阅app.use()得到更多的信息。 
中间件就像一个水暖管道，请求在你定义的第一个中间件处开始，顺着中间件堆栈一路往下，若是路径匹配则处理这个请求。

 
  1. var express = require('express');
  2. var app = express();
  3. var router = express.Router();
  6. // simple logger for this router`s requests
  7. // all requests to this router will first hit this middleware
  9. router.use(function(req, res, next) {
  10. console.log('%s %s %s', req.method, req.url, req.path);
  11. next();
  12. })
  14. // this will only be invoked if the path starts with /bar form the mount ponit
  15. router.use('/bar', function(req, res, next) {
  16. // ... maybe some additional /bar logging ...
  17. next();
  18. })
  20. // always be invoked
  21. router.use(function(req, res, next) {
  22. res.send('hello world')；
  23. })
  25. app.use('/foo', router);
  27. app.listen(3000);

对于中间件function，挂载的路径是被剥离的和不可见的。关于这个特性主要的影响是对于不一样的路径，挂载相同的中间件可能对代码不作改动，尽管其前缀已经改变。 
你使用router.use()定义中间件的顺序很重要。中间们是按序被调用的，因此顺序决定了中间件的优先级。例如，一般日志是你将使用的第一个中间件，以便每个请求都被记录。

 
  1. var logger = require('morgan');
  3. router.use(logger());
  4. router.use(express.static(__dirname + '/public'));
  5. router.use(function(req, res) {
  6. res.send('Hello');
  7. });

如今为了支持你不但愿记录静态文件请求，但为了继续记录那些定义在logger()以后的路由和中间件。你能够简单的将static()移动到前面来解决：

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

另一个确凿的例子是从不一样的路径托管静态文件，你能够将./public放到前面来得到更高的优先级:

 
  1. app.use(express.static(__dirname + '/public'));
  2. app.use(express.static(__dirname + '/files'));
  3. app.use(express.static(__dirname + '/uploads'));

router.use()方法也支持命名参数，以便你的挂载点对于其余的路由而言，可使用命名参数来进行预加载，这样作是颇有益的。

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程