nodejs的大名好多人应该是听过的，而作为nodejs web 开发的框架express 大家也应该比较熟悉。
记录一下关于express API 的文档：
express()
创建express 应用.
var express = require('express');var app = express();app.get('/', function(req, res){res.send('hello world');});app.listen(3000);
应用
app.set(name, value)
指定对应名称的值
app.set('title', 'My Site');app.get('title');// => "My Site"
app.get(name)
获取对应名称的值
app.get('title');// => undefinedapp.set('title', 'My Site');app.get('title');// => "My Site"
app.enable(name)
进行布尔类型的设置
app.enable('trust proxy');app.get('trust proxy');// => true
app.disable(name)
同上
app.disable('trust proxy');app.get('trust proxy');// => false
app.enabled(name)
检查设置是否可用
app.enabled('trust proxy');// => falseapp.enable('trust proxy');app.enabled('trust proxy');// => true
app.disabled(name)
检查设置是否不可用
app.disabled('trust proxy');// => trueapp.enable('trust proxy');app.disabled('trust proxy');// => false
app.configure([env], callback)
Conditionally invokecallbackwhenenvmatchesapp.get('env'), akaprocess.env.NODE_ENV. This method remains for legacy reason, and is effectively anifstatement as illustrated in the following snippets. These functions arenotrequired in order to useapp.set()and other configuration methods.
// all environmentsapp.configure(function(){app.set('title', 'My Application');})// development onlyapp.configure('development', function(){app.set('db uri', 'localhost/dev');})// production onlyapp.configure('production', function(){app.set('db uri', 'n.n.n.n/prod');})
effectively sugar for:
// all environmentsapp.set('title', 'My Application');// development onlyif ('development' == app.get('env')) {app.set('db uri', 'localhost/dev');}// production onlyif ('production' == app.get('env')) {app.set('db uri', 'n.n.n.n/prod');}
app.use([path], function)
Use the given middlewarefunction, with optional mountpath, defaulting to "/".
var express = require('express');var app = express();// simple loggerapp.use(function(req, res, next){console.log('%s %s', req.method, req.url);next();});// respondapp.use(function(req, res, next){res.send('Hello World');});app.listen(3000);
The "mount" path is stripped and isnotvisible to the middlewarefunction. The main effect of this feature is that mounted middleware may operate without code changes regardless of its "prefix" pathname.
Here's a concrete example, take the typical use-case of serving files in ./public using theexpress.static()middleware:
// GET /javascripts/jquery.js// GET /style.css// GET /favicon.icoapp.use(express.static(__dirname + '/public'));
Say for example you wanted to prefix all static files with "/static", you could use the "mounting" feature to support this. Mounted middleware functions arenotinvoked unless thereq.urlcontains this prefix, at which point it is stripped when the function is invoked. This affects this function only, subsequent middleware will seereq.urlwith "/static" included unless they are mounted as well.
// GET /static/javascripts/jquery.js// GET /static/style.css// GET /static/favicon.icoapp.use('/static', express.static(__dirname + '/public'));
The order of which middleware are "defined" usingapp.use()is very important, they are invoked sequentially, thus this defines middleware precedence. For example usuallyexpress.logger()is the very first middleware you would use, logging every request:
app.use(express.logger());app.use(express.static(__dirname + '/public'));app.use(function(req, res){res.send('Hello');});
Now suppose you wanted to ignore logging requests for static files, but to continue logging routes and middleware defined afterlogger(), you would simply movestatic()above:
app.use(express.static(__dirname + '/public'));app.use(express.logger());app.use(function(req, res){res.send('Hello');});
Another concrete example would be serving files from multiple directories, giving precedence to "./public" over the others:
app.use(express.static(__dirname + '/public'));app.use(express.static(__dirname + '/files'));app.use(express.static(__dirname + '/uploads'));
settings
The following settings are provided to alter how Express will behave:
envEnvironment mode, defaults toprocess.env.NODE_ENVor "development"trust proxyEnables reverse proxy support, disabled by defaultjsonp callback nameChanges the default callback name of?callback=json replacerJSON replacer callback, null by defaultjson spacesJSON response spaces for formatting, defaults to2in development,0in productioncase sensitive routingEnable case sensitivity, disabled by default, treating "/Foo" and "/foo" as the samestrict routingEnable strict routing, by default "/foo" and "/foo/" are treated the same by the routerview cacheEnables view template compilation caching, enabled in production by defaultview engineThe default engine extension to use when omittedviewsThe view directory path, defaulting to "process.cwd() + '/views'"
app.engine(ext, callback)
Register the given template enginecallbackasextBy default willrequire()the engine based on the file extension. For example if you try to render a "foo.jade" file Express will invoke the following internally, and cache therequire()on subsequent calls to increase performance.
app.engine('jade', require('jade').__express);
For engines that do not provide.__expressout of the box - or if you wish to "map" a different extension to the template engine you may use this method. For example mapping the EJS template engine to ".html" files:
app.engine('html', require('ejs').renderFile);
In this case EJS provides a.renderFile()method with the same signature that Express expects:(path, options, callback), though note that it aliases this method asejs.__expressinternally so if you're using ".ejs" extensions you dont need to do anything.
Some template engines do not follow this convention, theconsolidate.jslibrary was created to map all of node's popular template engines to follow this convention, thus allowing them to work seemlessly within Express.
var engines = require('consolidate');app.engine('haml', engines.haml);app.engine('html', engines.hogan);
app.param([name], callback)
Map logic to route parameters. For example when:useris present in a route path you may map user loading logic to automatically providereq.userto the route, or perform validations on the parameter input.
The following snippet illustrates how thecallbackis much like middleware, thus supporting async operations, however providing the additional value of the parameter, here named asid. An attempt to load the user is then performed, assigningreq.user, otherwise passing an error tonext(err).
app.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'));}});});
Alternatively you may pass only acallback, in which case you have the opportunity to alter theapp.param()API. For example theexpress-paramsdefines the following callback which allows you to restrict parameters to a given regular expression.
This example is a bit more advanced, checking if the second argument is a regular expression, returning the callback which acts much like the "user" param example.
app.param(function(name, fn){if (fn instanceof RegExp) {return function(req, res, next, val){var captures;if (captures = fn.exec(String(val))) {req.params[name] = captures;next();} else {next('route');}}}});
The method could now be used to effectively validate parameters, or also parse them to provide capture groups:
app.param('id', /^\d+$/);app.get('/user/:id', function(req, res){res.send('user ' + req.params.id);});app.param('range', /^(\w+)\.\.(\w+)?$/);app.get('/range/:range', function(req, res){var range = req.params.range;res.send('from ' + range[1] + ' to ' + range[2]);});
app.VERB(path, [callback...], callback)
Theapp.VERB()methods provide the routing functionality in Express, whereVERBis one of the HTTP verbs, such asapp.post(). Multiple callbacks may be given, all are treated equally, and behave just like middleware, with the one exception that these callbacks may invokenext('route')to bypass the remaining route callback(s). This mechanism can be used to perform pre-conditions on a route then pass control to subsequent routes when there is no reason to proceed with the route matched.
The following snippet illustrates the most simple route definition possible. Express translates the path strings to regular expressions, used internally to match incoming requests. Query strings arenotconsidered when peforming these matches, for example "GET /" would match the following route, as would "GET /?name=tobi".
app.get('/', function(req, res){res.send('hello world');});
Regular expressions may also be used, and can be useful if you have very specific restraints, for example the following would match "GET /commits/71dbb9c" as well as "GET /commits/71dbb9c..4c084f9".
app.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function(req, res){var from = req.params[0];var to = req.params[1] || 'HEAD';res.send('commit range ' + from + '..' + to);});
Several callbacks may also be passed, useful for re-using middleware that load resources, perform validations, etc.
app.get('/user/:id', user.load, function(){// ... })
These callbacks may be passed within arrays as well, these arrays are simply flattened when passed:
var middleware = [loadForum, loadThread];app.get('/forum/:fid/thread/:tid', middleware, function(){// ...})app.post('/forum/:fid/thread/:tid', middleware, function(){// ...})
app.all(path, [callback...], callback)
This method functions just like theapp.VERB()methods, however it matches all HTTP verbs.
This method is extremely useful for mapping "global" logic for specific path prefixes or arbitrary matches. For example if you placed the following route at the top of all other route definitions, it would require that all routes from that point on would require authentication, and automatically load a user. Keep in mind that these callbacks do not have to act as end points,loadUsercan perform a task, thennext()to continue matching subsequent routes.
app.all('*', requireAuthentication, loadUser);
Or the equivalent:
app.all('*', requireAuthentication)app.all('*', loadUser);
Another great example of this is white-listed "global" functionality. Here the example is much like before, however only restricting paths prefixed with "/api":
app.all('/api/*', requireAuthentication);
app.locals
Application local variables are provided to all templates rendered within the application. This is useful for providing helper functions to templates, as well as app-level data.
app.locals.title = 'My App';app.locals.strftime = require('strftime');
Theapp.localsobject is a JavaScriptFunction, which when invoked with an object will merge properties into itself, providing a simple way to expose existing objects as local variables.
app.locals({title: 'My App',phone: '1-250-858-9990',email: 'me@'});app.locals.title// => 'My App'app.locals.email// => 'me@'
A consequence of theapp.localsObject being ultimately a Javascript Function Object is that you must not reuse existing (native) named properties for your own variable names, such asname, apply, bind, call, arguments, length, constructor.
app.locals({name: 'My App'});app.locals.name// => return 'app.locals' in place of 'My App' (app.locals is a Function !)// => if name's variable is used in a template, a ReferenceError will be returned.
The full list of native named properties can be found in many specifications. TheJavaScript specificationintroduced original properties, some of which still recognized by modern engines, and theEcmaScript specificationthen built on it and normalized the set of properties, adding new ones and removing deprecated ones. Check out properties for Functions and Objects if interested.
By default Express exposes only a single app-level local variable,settings.
app.set('title', 'My App');// use settings.title in a view
app.render(view, [options], callback)
Render aviewwith a callback responding with the rendered string. This is the app-level variant ofres.render(), and otherwise behaves the same way.
app.render('email', function(err, html){// ...});app.render('email', { name: 'Tobi' }, function(err, html){// ...});
app.routes
Theapp.routesobject houses all of the routes defined mapped by the associated HTTP verb. This object may be used for introspection capabilities, for example Express uses this internally not only for routing but to provide defaultOPTIONSbehaviour unlessapp.options()is used. Your application or framework may also remove routes by simply by removing them from this object.
console.log(app.routes){ get: [ { path: '/',method: 'get',callbacks: [Object],keys: [],regexp: /^\/\/?$/i },{ path: '/user/:id',method: 'get',callbacks: [Object],keys: [{ name: 'id', optional: false }],regexp: /^\/user\/(?:([^\/]+?))\/?$/i } ],delete: [ { path: '/user/:id',method: 'delete',callbacks: [Object],keys: [Object],regexp: /^\/user\/(?:([^\/]+?))\/?$/i } ] }
app.listen()
Bind and listen for connections on the given host and port, this method is identical to node'shttp.Server#listen().
var express = require('express');var app = express();app.listen(3000);
Theappreturned byexpress()is in fact a JavaScriptFunction, designed to be passed to node's http servers as a callback to handle requests. This allows you to provide both HTTP and HTTPS versions of your app with the same codebase easily, as the app does not inherit from these, it is simply a callback:
var express = require('express');var https = require('https');var http = require('http');var app = express();http.createServer(app).listen(80);https.createServer(options, app).listen(443);
Theapp.listen()method is simply a convenience method defined as, if you wish to use HTTPS or provide both, use the technique above.
app.listen = function(){var server = http.createServer(this);return server.listen.apply(server, arguments);};
Request
req.params
This property is an array containing properties mapped to the named route "parameters". For example if you have the route/user/:name, then the "name" property is available to you asreq.params.name. This object defaults to{}.
// GET /user/tjreq.params.name// => "tj"
When a regular expression is used for the route definition, capture groups are provided in the array usingreq.params[N], whereNis the nth capture group. This rule is applied to unnamed wild-card matches with string routes such as `/file/*`:
// GET /file/javascripts/jquery.jsreq.params[0]// => "javascripts/jquery.js"
req.query
This property is an object containing the parsed query-string, defaulting to{}.
// GET /search?q=tobi+ferretreq.query.q// => "tobi ferret"// GET /shoes?order=desc&shoe[color]=blue&shoe[type]=conversereq.query.order// => "desc"req.query.shoe.color// => "blue"req.query.shoe.type// => "converse"
req.body
This property is an object containing the parsed request body. This feature is provided by thebodyParser()middleware, though other body parsing middleware may follow this convention as well. This property defaults to{}whenbodyParser()is used.
// POST user[name]=tobi&user[email]=tobi@req.body.user.name// => "tobi"req.body.user.email// => "tobi@"// POST { "name": "tobi" }req.body.name// => "tobi"
req.files
This property is an object of the files uploaded. This feature is provided by thebodyParser()middleware, though other body parsing middleware may follow this convention as well. This property defaults to{}whenbodyParser()is used.
For example if afilefield was named "image", and a file was uploaded,req.files.imagewould contain the followingFileobject:
{ size: 74643,path: '/tmp/8ef9c52abe857867fd0a4e9a819d1876',name: 'edge.png',type: 'image/png',hash: false,lastModifiedDate: Thu Aug 09 20:07:51 GMT-0700 (PDT),_writeStream: { path: '/tmp/8ef9c52abe857867fd0a4e9a819d1876',fd: 13,writable: false,flags: 'w',encoding: 'binary',mode: 438,bytesWritten: 74643,busy: false,_queue: [],_open: [Function],drainable: true },length: [Getter],filename: [Getter],mime: [Getter] }
ThebodyParser()middleware utilizes thenode-formidablemodule internally, and accepts the same options. An example of this is thekeepExtensionsformidable option, defaulting tofalsewhich in this case gives you the filename "/tmp/8ef9c52abe857867fd0a4e9a819d1876" void of the ".png" extension. To enable this, and others you may pass them tobodyParser():
app.use(express.bodyParser({ keepExtensions: true, uploadDir: '/my/files' }));
req.param(name)
Return the value of paramnamewhen present.
// ?name=tobireq.param('name')// => "tobi"// POST name=tobireq.param('name')// => "tobi"// /user/tobi for /user/:name req.param('name')// => "tobi"
Lookup is performed in the following order:
req.paramsreq.bodyreq.query
Direct access toreq.body,req.params, andreq.queryshould be favoured for clarity - unless you truly accept input from each object.
req.route
The currently matchedRoutecontaining several properties such as the route's original path string, the regexp generated, and so on.
app.get('/user/:id?', function(req, res){console.log(req.route);});
Example output from the previous snippet:
{ path: '/user/:id?',method: 'get',callbacks: [ [Function] ],keys: [ { name: 'id', optional: true } ],regexp: /^\/user(?:\/([^\/]+?))?\/?$/i,params: [ id: '12' ] }
req.cookies
When thecookieParser()middleware is used this object defaults to{}, otherwise contains the cookies sent by the user-agent.
// Cookie: name=tjreq.cookies.name// => "tj"
req.signedCookies
When thecookieParser(secret)middleware is used this object defaults to{}, otherwise contains the signed cookies sent by the user-agent, unsigned and ready for use. Signed cookies reside in a different object to show developer intent, otherwise a malicious attack could be placed on `req.cookie` values which are easy to spoof. Note that signing a cookie does not mean it is "hidden" nor encrypted, this simply prevents tampering as the secret used to sign is private.
// Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3req.user// => "tobi"
req.get(field)
Get the case-insensitive request headerfield. TheReferrerandRefererfields are interchangeable.
req.get('Content-Type');// => "text/plain"req.get('content-type');// => "text/plain"req.get('Something');// => undefined
Aliased asreq.header(field).
req.accepts(types)
Check if the giventypesare acceptable, returning the best match when true, otherwiseundefined- in which case you should respond with 406 "Not Acceptable".
Thetypevalue may be a single mime type string such as "application/json", the extension name such as "json", a comma-delimited list or an array. When a list or array is given thebestmatch, if any is returned.
// Accept: text/htmlreq.accepts('html');// => "html"// Accept: text/*, application/jsonreq.accepts('html');// => "html"req.accepts('text/html');// => "text/html"req.accepts('json, text');// => "json"req.accepts('application/json');// => "application/json"// Accept: text/*, application/jsonreq.accepts('image/png');req.accepts('png');// => undefined// Accept: text/*;q=.5, application/jsonreq.accepts(['html', 'json']);req.accepts('html, json');// => "json"
req.accepted
Return an array of Accepted media types ordered from highest quality to lowest.
[ { value: 'application/json',quality: 1,type: 'application',subtype: 'json' },{ value: 'text/html',quality: 0.5,type: 'text',subtype: 'html' } ]
req.is(type)
Check if the incoming request contains the "Content-Type" header field, and it matches the give mimetype.
// With Content-Type: text/html; charset=utf-8req.is('html');req.is('text/html');req.is('text/*');// => true// When Content-Type is application/jsonreq.is('json');req.is('application/json');req.is('application/*');// => truereq.is('html');// => false
req.ip
Return the remote address, or when "trust proxy" is enabled - the upstream address.
req.ip// => "127.0.0.1"
req.ips
When "trust proxy" is `true`, parse the "X-Forwarded-For" ip address list and return an array, otherwise an empty array is returned. For example if the value were "client, proxy1, proxy2" you would receive the array["client", "proxy1", "proxy2"]where "proxy2" is the furthest down-stream.
req.path
Returns the request URL pathname.
// /users?sort=descreq.path// => "/users"
req.host
Returns the hostname from the "Host" header field (void of portno).
// Host: ":3000"req.host// => ""
req.fresh
Check if the request is fresh - aka Last-Modified and/or the ETag still match, indicating that the resource is "fresh".
req.fresh// => true
req.stale
Check if the request is stale - aka Last-Modified and/or the ETag do not match, indicating that the resource is "stale".
req.stale// => true
req.xhr
Check if the request was issued with the "X-Requested-With" header field set to "XMLHttpRequest" (jQuery etc).
req.xhr// => true
req.protocol
Return the protocol string "http" or "https" when requested with TLS. When the "trust proxy" setting is enabled the "X-Forwarded-Proto" header field will be trusted. If you're running behind a reverse proxy that supplies https for you this may be enabled.
req.protocol// => "http"
req.secure
Check if a TLS connection is established. This is a short-hand for:
'https' == req.protocol;
req.subdomains
Return subdomains as an array.
// Host: "tobi."req.subdomains// => ["ferrets", "tobi"]
req.originalUrl
This property is much likereq.url, however it retains the original request url, allowing you to rewritereq.urlfreely for internal routing purposes. For example the "mounting" feature ofapp.use()will rewritereq.urlto strip the mount point.
// GET /search?q=somethingreq.originalUrl// => "/search?q=something"
req.acceptedLanguages
Return an array of Accepted languages ordered from highest quality to lowest.
Accept-Language: en;q=.5, en-us// => ['en-us', 'en']
req.acceptedCharsets
Return an array of Accepted charsets ordered from highest quality to lowest.
Accept-Charset: iso-8859-5;q=.2, unicode-1-1;q=0.8// => ['unicode-1-1', 'iso-8859-5']
req.acceptsCharset(charset)
Check if the givencharsetare acceptable.
req.acceptsLanguage(lang)
Check if the givenlangare acceptable.
Response
res.status(code)
Chainable alias of node'sres.statusCode=.
res.status(404).sendfile('path/to/404.png');
res.set(field, [value])
Set headerfieldtovalue, or pass an object to set multiple fields at once.
res.set('Content-Type', 'text/plain');res.set({'Content-Type': 'text/plain','Content-Length': '123','ETag': '12345'})
Aliased asres.header(field, [value]).
res.get(field)
Get the case-insensitive response headerfield.
res.get('Content-Type');// => "text/plain"
res.cookie(name, value, [options])
Set cookienametovalue, which may be a string or object converted to JSON. Thepathoption defaults to "/".
res.cookie('name', 'tobi', { domain: '.', path: '/admin', secure: true });res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
ThemaxAgeoption is a convenience option for setting "expires" relative to the current time in milliseconds. The following is equivalent to the previous example.
res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })
An object may be passed which is then serialized as JSON, which is automatically parsed by thebodyParser()middleware.
res.cookie('cart', { items: [1,2,3] });res.cookie('cart', { items: [1,2,3] }, { maxAge: 900000 });
Signed cookies are also supported through this method. Simply pass thesignedoption. When givenres.cookie()will use the secret passed toexpress.cookieParser(secret)to sign the value.
res.cookie('name', 'tobi', { signed: true });
Later you may access this value through thereq.signedCookieobject.
res.clearCookie(name, [options])
Clear cookiename. Thepathoption defaults to "/".
res.cookie('name', 'tobi', { path: '/admin' });res.clearCookie('name', { path: '/admin' });
res.redirect([status], url)
Redirect to the givenurlwith optionalstatuscode defaulting to 302 "Found".
res.redirect('/foo/bar');res.redirect('');res.redirect(301, '');res.redirect('../login');
Express supports a few forms of redirection, first being a fully qualified URI for redirecting to a different site:
res.redirect('');
The second form is the pathname-relative redirect, for example if you were on/admin/post/new, the following redirect to/adminwould land you at/admin:
res.redirect('/admin');
This next redirect is relative to themountpoint of the application. For example if you have a blog application mounted at/blog, ideally it has no knowledge of where it was mounted, so where a redirect of/admin/post/newwould simply give you/admin/post/new, the following mount-relative redirect would give you/blog/admin/post/new:
res.redirect('admin/post/new');
Pathname relative redirects are also possible. If you were on/admin/post/new, the following redirect would land you athttp///admin/post:
res.redirect('..');
The final special-case is abackredirect, redirecting back to the Referer (or Referrer), defaulting to/when missing.
res.redirect('back');
res.location
Set the location header.
res.location('/foo/bar');res.location('foo/bar');res.location('');res.location('../login');res.location('back');
You can use the same kind ofurlsas inres.redirect().
For example, if your application is mounted at/blog, the following would set thelocationheader to/blog/admin:
res.location('admin')
res.charset
Assign the charset. Defaults to "utf-8".
res.charset = 'value';res.send('some html');// => Content-Type: text/html; charset=value
res.send([body|status], [body])
Send a response.
res.send(new Buffer('whoop'));res.send({ some: 'json' });res.send('some html');res.send(404, 'Sorry, we cannot find that!');res.send(500, { error: 'something blew up' });res.send(200);
This method performs a myriad of useful tasks for simple non-streaming responses such as automatically assigning the Content-Length unless previously defined and providing automaticHEADand HTTP cache freshness support.
When aBufferis given the Content-Type is set to "application/octet-stream" unless previously defined as shown below:
res.set('Content-Type', 'text/html');res.send(new Buffer('some html'));
When aStringis given the Content-Type is set defaulted to "text/html":
res.send('some html');
When anArrayorObjectis given Express will respond with the JSON representation:
res.send({ user: 'tobi' })res.send([1,2,3])
Finally when aNumberis given without any of the previously mentioned bodies, then a response body string is assigned for you. For example 200 will respond will the text "OK", and 404 "Not Found" and so on.
res.send(200)res.send(404)res.send(500)
res.json([status|body], [body])
Send a JSON response. This method is identical tores.send()when an object or array is passed, however it may be used for explicit JSON conversion of non-objects (null, undefined, etc), though these are technically not valid JSON.
res.json(null)res.json({ user: 'tobi' })res.json(500, { error: 'message' })
res.jsonp([status|body], [body])
Send a JSON response with JSONP support. This method is identical tores.json()however opts-in to JSONP callback support.
res.jsonp(null)// => nullres.jsonp({ user: 'tobi' })// => { "user": "tobi" }res.jsonp(500, { error: 'message' })// => { "error": "message" }
By default the JSONP callback name is simplycallback, however you may alter this with thejsonp callback namesetting. The following are some examples of JSONP responses using the same code:
// ?callback=foores.jsonp({ user: 'tobi' })// => foo({ "user": "tobi" })app.set('jsonp callback name', 'cb');// ?cb=foores.jsonp(500, { error: 'message' })// => foo({ "error": "message" })
res.type(type)
Sets the Content-Type to the mime lookup oftype, or when "/" is present the Content-Type is simply set to this literal value.
res.type('.html');res.type('html');res.type('json');res.type('application/json');res.type('png');
res.format(object)
Performs content-negotiation on the request Accept header field when present. This method usesreq.accepted, an array of acceptable types ordered by their quality values, otherwise the first callback is invoked. When no match is performed the server responds with 406 "Not Acceptable", or invokes thedefaultcallback.
The Content-Type is set for you when a callback is selected, however you may alter this within the callback usingres.set()orres.type()etcetera.
The following example would respond with{ "message": "hey" }when the Accept header field is set to "application/json" or "*/json", however if "*/*" is given then "hey" will be the response.
res.format({'text/plain': function(){res.send('hey');},'text/html': function(){res.send('hey');},'application/json': function(){res.send({ message: 'hey' });}});
In addition to canonicalized MIME types you may also use extnames mapped to these types, providing a slightly less verbose implementation:
res.format({text: function(){res.send('hey');},html: function(){res.send('hey');},json: function(){res.send({ message: 'hey' });}});
res.attachment([filename])
Sets the Content-Disposition header field to "attachment". If afilenameis given then the Content-Type will be automatically set based on the extname viares.type(), and the Content-Disposition's "filename=" parameter will be set.
res.attachment();// Content-Disposition: attachmentres.attachment('path/to/logo.png');// Content-Disposition: attachment; filename="logo.png"// Content-Type: image/png
res.sendfile(path, [options], [fn]])
Transfer the file at the givenpath.
Automatically defaults the Content-Type response header field based on the filename's extension. The callbackfn(err)is invoked when the transfer is complete or when an error occurs.
Options:
maxAgein milliseconds defaulting to 0rootroot directory for relative filenames
This method provides fine-grained support for file serving as illustrated in the following example:
app.get('/user/:uid/photos/:file', function(req, res){var uid = req.params.uid, file = req.params.file;req.user.mayViewFilesFrom(uid, function(yes){if (yes) {res.sendfile('/uploads/' + uid + '/' + file);} else {res.send(403, 'Sorry! you cant see that.');}});});
res.download(path, [filename], [fn])
Transfer the file atpathas an "attachment", typically browsers will prompt the user for download. The Content-Disposition "filename=" parameter, aka the one that will appear in the brower dialog is set topathby default, however you may provide an overridefilename.
When an error has ocurred or transfer is complete the optional callbackfnis invoked. This method usesres.sendfile()to transfer the file.
res.download('/report-12345.pdf');res.download('/report-12345.pdf', 'report.pdf');res.download('/report-12345.pdf', 'report.pdf', function(err){if (err) {// handle error, keep in mind the response may be partially-sent// so check res.headerSent} else {// decrement a download credit etc}});
res.links(links)
Join the givenlinksto populate the "Link" response header field.
res.links({next: '/users?page=2',last: '/users?page=5'});
yields:
Link: </users?page=2>; rel="next", </users?page=5>; rel="last"
res.locals
Response local variables are scoped to the request, thus only available to the view(s) rendered during that request / response cycle, if any. Otherwise this API is identical toapp.locals.
This object is useful for exposing request-level information such as the request pathname, authenticated user, user settings etcetera.
app.use(function(req, res, next){res.locals.user = req.user;res.locals.authenticated = ! req.user.anonymous;next();});
res.render(view, [locals], callback)
Render aviewwith a callback responding with the rendered string. When an error occursnext(err)is invoked internally. When a callback is provided both the possible error and rendered string are passed, and no automated response is performed.
res.render('index', function(err, html){// ...});res.render('user', { name: 'Tobi' }, function(err, html){// ...});
Middleware
basicAuth()
Basic Authentication middleware, populatingreq.userwith the username.
Simple username and password:
app.use(express.basicAuth('username', 'password'));
Callback verification:
app.use(express.basicAuth(function(user, pass){return 'tj' == user & 'wahoo' == pass;}));
Async callback verification, acceptingfn(err, user), in this casereq.userwill be the user object passed.
app.use(express.basicAuth(function(user, pass, fn){User.authenticate({ user: user, pass: pass }, fn);}))
bodyParser()
Request body parsing middleware supporting JSON, urlencoded, and multipart requests. This middleware is simply a wrapper for thejson(),urlencoded(), andmultipart()middleware.
app.use(express.bodyParser());// is equivalent to:app.use(express.json());app.use(express.urlencoded());app.use(express.multipart());
For security sake, it's better to disable file upload if your application doesn't need it. To do this, use only the needed middleware, i.e. don't use thebodyParserandmultipart()middleware:
app.use(express.json());app.use(express.urlencoded());
If your application needs file upload you should set upa strategy for dealing with those files.
compress()
Compress response data with gzip / deflate. This middleware should be placed "high" within the stack to ensure all responses may be compressed.
app.use(express.logger());app.use(press());app.use(express.methodOverride());app.use(express.bodyParser());
cookieParser()
Parses the Cookie header field and populatesreq.cookieswith an object keyed by the cookie names. Optionally you may enabled signed cookie support by passing asecretstring.
app.use(express.cookieParser());app.use(express.cookieParser('some secret'));
cookieSession()
Provides cookie-based sessions, and populatesreq.session. This middleware takes the following options:
keycookie name defaulting toconnect.sesssecretprevents cookie tamperingcookiesession cookie settings, defaulting to{ path: '/', httpOnly: true, maxAge: null }proxytrust the reverse proxy when setting secure cookies (via "x-forwarded-proto")
app.use(express.cookieSession());
To clear a cookie simply assign the session to null before responding:
req.session = null
csrf()
CSRF protection middleware.
By default this middleware generates a token named "_csrf" which should be added to requests which mutate state, within a hidden form field, query-string etc. This token is validated againstreq.csrfToken().
The defaultvaluefunction checksreq.bodygenerated by thebodyParser()middleware,req.querygenerated byquery(), and the "X-CSRF-Token" header field.
This middleware requires session support, thus should be added somewhere belowsession().
directory()
Directory serving middleware, serves the givenpath. This middleware may be paired withstatic()to serve files, providing a full-featured file browser.
app.use(express.directory('public'))app.use(express.static('public'))
This middleware accepts the following options:
hiddendisplay hidden (dot) files. Defaults to false.iconsdisplay icons. Defaults to false.filterApply this filter function to files. Defaults to false.
