Cette traduction fournie par StrongLoop / IBM.

Il se peut que ce document soit obsolète par rapport à la documentation en anglais. Pour connaître les mises à jour les plus récentes, reportez-vous à la documentation en anglais.

Migration vers Express 4

Présentation

Express 4 est un changement novateur d’Express 3. Cela signifie qu’une application Express 3 existante ne fonctionnera pas si vous mettez à jour la version Express dans les dépendances.

Cet article couvre :

Modifications dans Express 4

De nombreuses modifications importantes ont été faites dans Express 4 :

Voir aussi :

Modification du système principal et middleware d'Express

Express 4 ne dépend plus de Connect, et supprime tous les middleware intégrés de son noyau, sauf la fonction express.static. Cela signifie qu’Express est désormais un canevas Web de routage et de middleware indépendant et que les versions et éditions d’Express ne sont pas affectées par les mises à jour de middleware.

Sans middleware intégré, vous devez explicitement ajouter tous les middleware requis pour exécuter votre application. Procédez comme suit :

  1. Installez le module : npm install --save <module-name>
  2. Dans votre application, demandez le module : require('module-name')
  3. Utilisez le module en fonction de cette documentation: app.use( ... )

La table suivante répertorie le middelware Express 3 et ces équivalents dans 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

Vous trouverez ici la liste complète du middleware Express 4.

Dans la plupart des cas, il vous suffit de remplacer l’ancienne version du middelware 3 par son équivalent Express 4. Pour plus d’informations, consultez la documentation relative au module dans GitHub.

app.use accepte les paramètres

Dans la version 4 vous pouvez utilisez un paramètre variable pour définir le chemin vers lequel les fonctions middleware sont chargées, puis lire la valeur de ce paramètre dans le gestionnaire de routage. Par exemple :


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

Le système de routage

Les applications chargent dorénavant les middleware de routage de manière implicite, ce qui fait que vous n’avez plus à vous soucier de l’ordre dans lequel les middleware sont chargés par rapport au middleware router.

La façon de définir des routes n’a pas changé mais le système de routage possède deux nouvelles fonctions pour vous aider à organiser vos routes :

méthode app.route()

La nouvelle méthode app.route() vous permet de créer des gestionnaires de routage sous forme de chaîne pour un chemin de routage. Etant donné que le chemin est spécifié à une seul emplacement, la création de routes modulaires est utile car elle réduit la redondance et les erreurs. Pour plus d’informations sur les routes, voir la documentation Router().

Voici quelques exemples de gestionnaires de chemin de chaînage définis à l’aide de la fonction app.route().


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

classe express.Router

L’autre fonction qui aide à organiser les routes est une nouvelle classe, express.Router, que vous pouvez utiliser pour créer des gestionnaires de routage modulaires pouvant être montés. Une instance Router est un middleware et un système de routage complet ; pour cette raison, elle est souvent appelée “mini-app”.

L’exemple suivant créé une routeur en tant que module, charge un middleware dans celui-ci, définit des routes et monte le module sur un chemin dans l’application principale.

Par exemple, créez un fichier de routage nommé birds.js dans le répertoire app, avec le contenu suivant :


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;

Puis, chargez le module de routage dans l’application :


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

L’application pourra gérer des demandes dans les chemins /birds et /birds/about, et appellera le middleware timeLog spécifique à la route.

Autres modifications

Le tableau suivant répertorie les autres modifications mineures mais importantes dans Express 4 :

Objet Description
Node.js Express 4 nécessite Node.js 0.10.x ou ultérieur et a abandonné la prise en charge de Node.js 0.8.x.

http.createServer()

Le module http n’est plus nécessaire, à moins que vous ne l’utilisiez directement (socket.io/SPDY/HTTPS). L’application peut être démarrée à l’aide de la fonction app.listen().

app.configure()

La fonction app.configure() a été supprimée. Utilisez la fonction process.env.NODE_ENV ou app.get('env') pour détecter l’environnement et configurer l’application, le cas échéant.

json spaces

La propriété d’application json spaces est désactivée par défaut dans Express 4.

req.accepted()

Use req.accepts(), req.acceptsEncodings(), req.acceptsCharsets() et req.acceptsLanguages().

res.location()

Ne résout plus les adresses URL relatives.

req.params

Anciennement un tableau ; il s’agit dorénavant d’un objet.

res.locals

Anciennement une fonction ; il s’agit dorénavant d’un objet.

res.headerSent

A été modifié en res.headersSent.

app.route

Dorénavant disponible comme app.mountpath.

res.on('header')

Supprimé.

res.charset

Supprimé.

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

Cette fonctionnalité se limite désormais à définir la valeur de cookie de base. Utilisez res.cookie() pour plus de fonctionnalités.

Exemple de migration d'application

Voici un exemple de migration d’une application Express 3 vers Express 4. Les fichiers qui nous intéressent sont app.js et package.json.

Application de la version 3

app.js

Examinons une application Express v.3 avec le fichier app.js suivant :


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

Voici à quoi ressemble le fichier package.json qui accompagne la version 3 :


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

Processus

Commencez le processus de migration en installant le middleware requis pour l’application Express 4 et en mettant à jour Express et Pug vers leur version la plus récente respective à l’aide de la commande suivante :


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

Apportez les modifications suivantes à app.js :

  1. Les fonctions Express Middleware intégrées express.favicon, express.logger, express.methodOverride, express.session, express.bodyParser et express.errorHandler ne sont plus disponibles sur l’objet express. Vous devez installer leurs fonctions alternatives manuellement et les charger dans l’application.

  2. Vous ne devez plus charger la fonction app.router. Il ne s’agit pas d’un objet d’application Express 4 valide. Supprimez le code app.use(app.router);.

  3. Assurez-vous que les fonctions middleware sont chargées dans l’ordre correct - chargez errorHandler après avoir chargé les routes d’application.

Application de la version 4

package.json

Le fait d’exécuter la commande npm ci-dessus mettra à jour package.json comme suit :


{
  "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",
    "pug": "^2.0.0-beta6",
    "method-override": "^2.1.2",
    "morgan": "^1.2.2",
    "multer": "^0.1.3",
    "serve-favicon": "^2.0.1"
  }
}

app.js

Puis, supprimez le code non valide, chargez les middleware requis et procédez aux autres changements, le cas échéant. Voici à quoi ressemble le fichier app.js :


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', 'pug');
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'));
});

A mois que vous deviez utiliser le module http (socket.io/SPDY/HTTPS) directement, vous n’avez pas à le charger et l’application peut être démarrée comme suit :

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

Exécutez l'application

Le processus de migration est terminé et l’application est désormais une application Express 4. Pour confirmer, démarrez l’application en utilisant la commande suivante :


$ node .

Chargez http://localhost:3000 et voyez comment la page d’accueil est générée par Express 4.

Mise à niveau vers le générateur d'applications Express 4

L’outil de ligne de commande qui permet de générer une application Express est toujours express, mais pour effectuer la mise à niveau vers la nouvelle version, vous devez désinstaller le générateur d’applications Express 3 puis installer la nouvelle version d’express-generator.

Installation

Si le générateur d’applications Express 3 est installé sur votre système, vous devez le désinstaller :


$ npm uninstall -g express

En fonction de la configuration de vos privilèges de fichier et de répertoire, vous devrez exécuter cette commande avec sudo.A présent, installez le nouveau générateur :


$ npm install -g express-generator

En fonction de la configuration de vos privilèges de fichier et de répertoire, vous devrez exécuter cette commande avec sudo.

Désormais, la commande express sur votre système est mise à jour vers le générateur Express 4.

Modifications du générateur d'applications

Les options et les syntaxe de commande restent généralement identiques, avec les exceptions suivantes :

Exemple

Exécutez la commande suivante pour créer une application Express 4 :


$ express app4

Si vous examinez le contenu du fichier app4/app.js, vous remarquerez que toutes les fonctions middleware (sauf express.static) qui sont requises pour l’application sont chargées en tant que modules indépendants, et le middleware router n’est plus chargé explicitement dans l’application.

Vous noterez également que le fichier app.js est désormais un module Node.js, contrairement à l’application autonome qui a été générée par l’ancien générateur.

Après avoir installé les dépendances, démarrez l’application en utilisant la commande suivante :


$ npm start

Si vous examinez le script de démarrage npm dans le fichier package.json, vous remarquerez dorénavant que la commande qui démarre l’application est node ./bin/www alors qu’il s’agissait de node app.js dans Express 3.

Puisque le fichier app.js qui a été généré par le générateur Express 4 est désormais un module Node.js, il ne peut plus être démarré indépendamment en tant qu’application (sauf si vous modifiez le code). Le module doit être chargé dans un fichier Node.js et démarré via le fichier Node.js. Dans cet exemple, le fichier Node.js est ./bin/www.

Ni le répertoire bin ni le fichier www sans extension n’est obligatoire pour créer une application Express ou démarrer celle-ci. Ce ne sont ici que des suggestions faites par le générateur, donc n’hésitez pas à les modifier si besoin.

Pour se débarrasser du répertoire www et garder la présentation d’Express 3, supprimez la ligne module.exports = app; à la fin du fichier app.js, puis collez le code suivant à la place :


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

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

Assurez-vous d’avoir chargé le module debug en haut du fichier app.js à l’aide du code suivant :


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

Ensuite, modifiez "start": "node ./bin/www" dans le fichier package.json en "start": "node app.js".

Vous avez à présent déplacé la fonctionnalité depuis ./bin/www de nouveau dans app.js. Cette modification n’est pas recommandée, mais l’exercice vous aide à comprendre le mode de fonctionnement du fichier ./bin/www et la raison pour laquelle le fichier app.js ne se lance plus seul.