Tento dokument môže byť v porovnaní s dokumentáciou v angličtine zastaralý. Aktuálne informácie nájdete v dokumentácii v angličtine.

Prechod na Express 4

Overview

Express 4 prináša zlomové zmeny oproti Express 3. To znamená, že existujúce Express 3 aplikácie nebudú fungovať po update verzie Express a jej dependencií.

Tento článok pokrýva:

Zmeny v Express 4

Express 4 prináša niekoĺko podstatných zmien:

Pozrite sa taktiež na:

Zmeny Express jadra a middleware systému

Express 4 už nie je závislý na Connect a z jeho jadra boli odstránené všetky vstavané middleware funkcie, okrem express.static funkcie. To znamená, že Express je teraz nezávislým routing a middleware webovým frameworkom a taktiež verzionovanie Express a jeho releasy nie sú ovplyvnené updatami middlewarov.

Terazm bez vstavaných middlewarov, musíte explicitne pridať všetky middleware funkcie, ktoré vaša aplikácia potrebuje k svojmu fungovaniu. Jednoducho pokračujte podľa nasledujúcich krokov:

  1. Nainštalujte požadovaný modul: npm install --save <module-name>
  2. Pridajte vo vašej aplikácii require na daný modul: require('module-name')
  3. Použite modul podľa jeho dokumentácie: app.use( ... )

Nasledujúca tabuľka obsahuje zoznam Express 3 middlewarov a ich varianty v Express 4.

Express 3Express 4
express.bodyParser body-parser + multer
express.compress compression
express.cookieSession cookie-session
express.cookieParser cookie-parser
express.logger morgan
express.session express-session
express.favicon serve-favicon
express.responseTime response-time
express.errorHandler errorhandler
express.methodOverride method-override
express.timeout connect-timeout
express.vhost vhost
express.csrf csurf
express.directory serve-index
express.static serve-static

Tu je kompletný zoznam Express 4 middlewarov.

Vo väčšine prípadov môžete jednoducho nahradiť starý Express 3 middleware jeho Express 4 variantou. Pre viac informácií si pozrite dokumentáciu daného modulu na Github-e.

app.use príjma parameter

Vo verzii 4 môžete použiť voliteľný parameter k definovaniu path-u, kedy sa má middleware funkcia načítať a následne prečítať hodnotu parametra z route handlera. Napr.:


app.use('/book/:id', function(req, res, next) {
  console.log('ID:', req.params.id);
  next();
});

Routing systém

Aplikácia odteraz explicitne načíta routing middleware, takže už sa viac nemusíte starať o to, v akom poradí bude ktorý middleware načítaný s ohľadom na router middleware.

Spôsob, akým definujete route sa nezmenil, ale samotný routing systém má dve nové features k jeho lepšej organizácii:

app.route() metóda

Nová metóda app.route() vám umožňuje vytvárať zreťaziteľné route handlery pre daný route path (cestu). Pretože je path (cesta) špecifikovaný na jednom mieste, tvorba takýchto modulárnych routes je užitočná, kedže znižuje redundanciu a možné preklepy. Pre viac informácií ohľadom route sa pozrite na Router() dokumentáciu.

Tu je príklad zreťazených route handlerov definovaných pomocou app.route() funkcie.


app.route('/book')
  .get(function(req, res) {
    res.send('Get a random book');
  })
  .post(function(req, res) {
    res.send('Add a book');
  })
  .put(function(req, res) {
    res.send('Update the book');
  });

express.Router trieda

Ďalšou novou feature, ktorá napomáha k lepšej organizácii routes, je nová trieda express.Router, ktorú môžete použiť k tvorbe modulárnych, pripojiteľných route handlerov. Router inštancia je kompletný middleware routing systém; z tohto dôvodu je často označovaná aj ako “mini-app”.

Nasledujúci príklad vytvára router ako modul, načítava v ňom middleware, definuje niekoľko routes a pripája tento router na path v hlavnej aplikácii.

Napr., vytvorte v priečinku vašej aplikácie router súbor s názvom birds.js s takýmto obsahom:


var express = require('express');
var router = express.Router();

// middleware specific to this router
router.use(function timeLog(req, res, next) {
  console.log('Time: ', Date.now());
  next();
});
// define the home page route
router.get('/', function(req, res) {
  res.send('Birds home page');
});
// define the about route
router.get('/about', function(req, res) {
  res.send('About birds');
});

module.exports = router;

Potom tento router načítajte vo vašej aplikácii:


var birds = require('./birds');
...
app.use('/birds', birds);

Aplikácia bude odteraz schopná obslúžiť requesty na path-och /birds a /birds/about a zavolá timeLog middleware, ktorý je špecifický pre tento route.

Ostatné zmeny

Nasledujúca tabuľka obsahuje zoznam drobných, ale dôležitých zmien v Express 4:

Objekt Popis
Node.js Express 4 si vyžaduje Node.js 0.10.x a vyšší a už nepodporuje Node.js 0.8.x.

http.createServer()

http modul už nie je potrebný, pokiaľ s ním nepotrebujete priamo pracovať (socket.io/SPDY/HTTPS). Aplikáciu dokážete naštartovať pomocou app.listen() funkcie.

app.configure()

Funkcia app.configure() bola odstránená. Pre detekciu environment nastavení a nastavenia aplikácie použite process.env.NODE_ENV alebo funkciu app.get('env').

json spaces

Aplikačná property json spaces je defaultne v Express 4 vypnutá.

req.accepted()

Používajte req.accepts(), req.acceptsEncodings(), req.acceptsCharsets() a req.acceptsLanguages().

res.location()

Už viac nevyhodnocuje relatívne URLky.

req.params

Bolo pôvodne pole, teraz je objektom.

res.locals

Bola pôvodne funkcia, teraz je objekt.

res.headerSent

Zmenená na res.headersSent.

app.route

Teraz dostupná ako app.mountpath.

res.on('header')

Zmazané.

res.charset

Zmazané.

res.setHeader('Set-Cookie', val)

Funkcionalita je odteraz obmedzená na nastavenie základnej hodnoty cookie. Pre pridanú funkcionalitu používajte res.cookie().

Príklad migrácie aplikácie

Tu je príklad migrácie Express 3 aplikácie na Express 4. Súbory, ktoré vás môžu zaujímať sú app.js a package.json.

Applikácia vo verzii 3

app.js

Majme takúto Express v.3 aplikáciu s takýmto app.js súborom:


var express = require('express');
var routes = require('./routes');
var user = require('./routes/user');
var http = require('http');
var path = require('path');

var app = express();

// all environments
app.set('port', process.env.PORT || 3000);
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'jade');
app.use(express.favicon());
app.use(express.logger('dev'));
app.use(express.methodOverride());
app.use(express.session({ secret: 'your secret here' }));
app.use(express.bodyParser());
app.use(app.router);
app.use(express.static(path.join(__dirname, 'public')));

// development only
if ('development' == app.get('env')) {
  app.use(express.errorHandler());
}

app.get('/', routes.index);
app.get('/users', user.list);

http.createServer(app).listen(app.get('port'), function(){
  console.log('Express server listening on port ' + app.get('port'));
});

package.json

Sprievodný package.json pre verziu 3 by vyzeral nejak takto:


{
  "name": "application-name",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "3.12.0",
    "jade": "*"
  }
}

Proces

Proces migrácie začnite nainštalovaním všetkých potrebných middlewarov pre vašu Express 4 aplikáciu a updatom Express a Jade na ich prislúchajúce najnovšie verzie nasledujúcim príkazom:


$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest jade@latest --save

V app.js vykonajte tieto zmeny:

  1. Vstavané Express middleware funkcie express.favicon, express.logger, express.methodOverride, express.session, express.bodyParser a express.errorHandler už nie sú dostupné na express objekte. Musíte nainštalovať a načítať ich prislúchajúce alternatívy v aplikácii manuálne.

  2. Už viac nepotrebujete načítať app.router funkciu. Nieje validným Express 4 app objektom, preto zmažte nasledujúci kód app.use(app.router);.

  3. Uistite sa, že middleware funkcie sú načítané v správnom poradí - načítajte errorHandler až po načítaní app routes.

Aplikácia vo verzii 4

package.json

Spustením kódu vyššie, npm príkaz updatne package.json nasledovne:


{
  "name": "application-name",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "body-parser": "^1.5.2",
    "errorhandler": "^1.1.1",
    "express": "^4.8.0",
    "express-session": "^1.7.2",
    "jade": "^1.5.0",
    "method-override": "^2.1.2",
    "morgan": "^1.2.2",
    "multer": "^0.1.3",
    "serve-favicon": "^2.0.1"
  }
}

app.js

Potom zmažte nesprávny kód, načítajte potrebné middlewary a vykonajte ďalšie potrebné zmeny. Súbor app.js bude potom vyzerať takto:


var http = require('http');
var express = require('express');
var routes = require('./routes');
var user = require('./routes/user');
var path = require('path');

var favicon = require('serve-favicon');
var logger = require('morgan');
var methodOverride = require('method-override');
var session = require('express-session');
var bodyParser = require('body-parser');
var multer = require('multer');
var errorHandler = require('errorhandler');

var app = express();

// all environments
app.set('port', process.env.PORT || 3000);
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'jade');
app.use(favicon(__dirname + '/public/favicon.ico'));
app.use(logger('dev'));
app.use(methodOverride());
app.use(session({ resave: true,
                  saveUninitialized: true,
                  secret: 'uwotm8' }));
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
app.use(multer());
app.use(express.static(path.join(__dirname, 'public')));

app.get('/', routes.index);
app.get('/users', user.list);

// error handling middleware should be loaded after the loading the routes
if ('development' == app.get('env')) {
  app.use(errorHandler());
}

var server = http.createServer(app);
server.listen(app.get('port'), function(){
  console.log('Express server listening on port ' + app.get('port'));
});

Pokiaľ nepotrebujete priamo pracovať s http modulom (socket.io/SPDY/HTTPS), nie je nutné ho načítať a aplikáciu môžete jednoducho naštartovať týmto spôsobom:

app.listen(app.get('port'), function(){
  console.log('Express server listening on port ' + app.get('port'));
});

Spustite aplikáciu

Proces migrácie je kompletný a aplikácia je teraz Express 4 aplikáciou. Pre overenie spustite aplikáciu pomocou nasledujúceho príkazu:


$ node .

Načítajte v prehliadači http://localhost:3000 a pozrite si domovskú stránku aplikácie vyrendrovanú pomocou Express 4.

Prechod na Express 4 app generátor

Tento command-line tool slúžiaci na generovanie Express aplikácie je stále express, ale k tomu, aby ste vykonali upgrade na novú verziu musíte najprv pôvodný Express 3 app generátor odinštalovať a potom nainštalovať nový express-generator.

Inštalácia

Ak už máte Express 3 app generátor na vašom systéme nainštalovaný, musíte ho najskôr odinštalovať:


$ npm uninstall -g express

V závislosti od toho, ako sú nakonfigurované vaše oprávnenia k súborom a priečinkom, môže byť potrebné spustiť tento príkaz pomocou sudo.

Teraz nainštalujte nový generátor:


$ npm install -g express-generator

V závislosti od toho, ako sú nakonfigurované vaše oprávnenia k súborom a priečinkom, môže byť potrebné spustiť tento príkaz pomocou sudo.

Teraz je príkaz express aktualizovaný na vašom systéme na Express 4 generátor.

Zmeny app generátora

Prepínače a použitia príkazu zostali prevažne rovnaké, okrem nasledujúcich výnimiek:

Príklad

K vytvoreniu Express 4 aplikácie spustite nasledujúci príkaz:


$ express app4

Ak sa pozriete na obsah app4/app.js súboru, všimnete si, že všetky middleware funkcie (okrem express.static), ktoré sú potrebné pre aplikáciu, sú načítané ako samostatné, nezávislé moduly a router middleware už nie je v aplikácii explicitne načítaný.

Taktiež si všimnite, že súbor app.js je odteraz Node.js modulom, v porovnaní so standalone aplikáciou vygenerovanou starým generátorom.

Po nainštalovaní závislostí spustite aplikáciu pomocou nasledujúceho príkazu:


$ npm start

Ak sa pozriete na npm start skript v package.json súbore, všimnete si, že aktuálny príkaz pre spustenie aplikácie je node ./bin/www, ktorý bol v Express 3 pôvodne node app.js.

Pretože súbor app.js, ktorý bol vygenerovaný Express 4 generátorom je odteraz Node.js modul, už nemôže byť viacej spustený nezávisle ako aplikácia (pokiaľ nezmeníte kód). Modul musí byť načítaný a spustený ako Node.js súbor. Node.js súbor je v tomto prípade./bin/www.

Priečinok bin ani bezpríponový súbor www nie sú povinné k vytvoreniu ani spusteniu aplikácie. Sú len návrhom vyrobeným generátorom, takže ich môzete zmeniť podľa vašich potrieb.

Ak sa chcete zbaviť www priečinka a ponechať to v starom “Express 3 formáte”, zmažte riadok module.exports = app; na konci app.js súboru a namiesto neho vložte nasledujúci kód:


app.set('port', process.env.PORT || 3000);

var server = app.listen(app.get('port'), function() {
  debug('Express server listening on port ' + server.address().port);
});

Uistite sa, že ste načítali debug modul, v hornej časti vášho app.js súboru, použitím nasledujúceho kódu:


var debug = require('debug')('app4');

Ďalej zmeňte v súbore package.json riadok "start": "node ./bin/www" na "start": "node app.js".

Týmto ste presunuli funkcionalitu ./bin/www späť do app.js. Táto zmena sa neodporúča, ale toto cvičenie vám pomôže porozumieť ako ./bin/www súbor pracuje a prečo app.js už viac nie je možné samostatne spustiť.