Migrando para o Express 4

Visão Geral

Express 4 é uma alteração de ruptura do Express 3. Isso significa que um aplicativo Express 3 existente não irá funcionar se você atualizar a versão do Express nas suas dependências.

Este artigo cobre:

• Mudanças no Express 4.
• Um exemplo de migração de um aplicativo do Express 3 para o Express 4.
• Fazendo o upgrade para o gerador de aplicativos do Express 4.

Mudanças no Express 4

Existem várias mudanças significativas no Express 4:

• Mudanças no núcleo e sistemas middleware do Express. As dependências no Connect e middlewares integrados foram removidos, de forma que você mesmo deve incluir os middlewares.
• Mudanças no sistema de roteamento.
• Várias outras mudanças.

Consulte também:

• Novos recursos no 4.x.
• Migrando do 3.x para o 4.x.

Mudanças no núcleo e sistemas middleware do Express

O Express 4 não depende mais do Connect, e remove todos os middlewares integrados do seu núcleo, exceto pela função express.static. Isso significa que o Express é agora um framework web de middleware e roteamento independente, e que o versionamento e as liberações do Express não são mais afetadas por atualizações nos middlewares.

Sem os middlewares integrados, você deve incluir explicitamente todos os middlewares necessários para a execução do seu aplicativo. Simplesmente siga esses passos:

1. Instale o módulo: npm install --save <module-name>
2. No seu aplicativo, solicite o módulo: require('module-name')
3. Use o módulo de acordo com sua documentação: app.use( ... )

A tabela a seguir lista os middlewares do Express 3 e suas contrapartes no Express 4.

Aqui está a lista completa de middlewares do Express 4.

Na maioria dos casos, é possível simplesmente substituir a antiga versão 3 do middleware pela sua contraparte do Express4. Para obter detalhes, consulte a documentação do módulo no GitHub.

O app.use aceita parâmetros

Na versão 4 é possível utilizar uma variável de parâmetro para definir o caminho onde as funções do middleware estão carregadas, e em seguida ler o valor do parâmetro a partir do manipulador de rota. Por exemplo:

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

O sistema de roteamento

Os aplicativos agora carregam implicitamente middlewares de roteamento, para que não seja mais necessário se preocupar com a ordem em que os middlewares são carregados no que diz respeito ao middleware router.

A forma como as rotas são definidas são as mesmas, mas o sistema de roteamento possui dois novos recursos para ajudá-lo a organizar suas rotas:

• Um novo método, app.route(), para criar manipuladores de rotas encadeáveis para um caminho de rota.
• Uma nova classe, express.Router, para criar manipuladores de rotas modulares montáveis

O método app.route()

O novo método app.route() permite que sejam criados manipuladores de rotas encadeáveis para um caminho de rota. Como o caminho é especificado em uma localização única, criar rotas modulares é útil, já que reduz redundâncias e erros tipográficos. Para obter mais informações sobre rotas, consulte a documentação do Router() .

Aqui está um exemplo de manipuladores de rotas encadeáveis que são definidos usando a função 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

O outro recurso que ajuda na organização das rotas é uma nova classe, express.Router, que pode ser usada para criar manipuladores de rotas modulares montáveis. Uma instância de Router é um middleware e sistema de roteamento completo; por essa razão ela é frequentemente referida como um “mini-aplicativo”

O seguinte exemplo cria um roteador como um módulo, carrega o middleware nele, define algumas rotas, e monta-o em um caminho no aplicativo principal.

Por exemplo, cria um arquivo roteador chamado birds.js no diretório do aplicativo, com o conteúdo a seguir:

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;

Em seguida, carregue o módulo roteador no aplicativo:

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

O aplicativo será agora capaz de manipular solicitações aos caminhos /birds e /birds/about, e irá chamar o middleware timeLog que é específico para a rota.

Outras mudanças

A seguinte tabela lista outras pequenas, porém importantes, mudanças no Express 4:

Exemplo de migração de aplicativo

Aqui está um eemplo de migração de um aplicativo Express 3 para o Express 4. Os arquivos de interesse são app.js e package.json.

Aplicativo da Versão 3

app.js

Considere um aplicativo do Express v.3 com o seguinte arquivo app.js:

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

O arquivo package.json que acompanha a versão 3 pode parecer com algo assim:

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

Processo

Comece o processo de migração instalando os middlewares necessários para o aplicativo Express 4 e atualizando o Express e o Pug para as suas respectivas versões mais recentes com o seguinte comando:

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

Faça as seguintes alterações no app.js:

1. As funções de middleware integradas do Express express.favicon, express.logger, express.methodOverride, express.session, express.bodyParser e express.errorHandler não estão mais disponíveis no objeto express. É preciso instalar manualmente as alternativas e carregá-las no aplicativo.

2. Não é mais necessário carregar a função app.router. Ela não é um objeto válido para aplicativos Express 4, portanto remova o código do app.use(app.router);.

3. Certifique-se deque as funções de middleware sejam carregadas na ordem correta - carregar a errorHandler após carregar as rotas de aplicativo.

Aplicativo da Versão 4

package.json

A execução do comando npm acima irá atualizar o package.json como a seguir:

{
  "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

Em seguida, remova o código inválido, carregue o middleware necessário e faça outras alterações conforme necessárias. O arquivo app.js irá parecer com isso:

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

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

Execute o aplicativo

O processo de migração está concluído, e o aplicativo é agora um aplicativo Express 4. Para confirmar, inicie o aplicativo usando o seguinte comando:

$ node .

Carregue http://localhost:3000 e veja a página inicial sendo renderizada pelo Express 4.

Fazendo o upgrade para o gerador de aplicativos do Express 4

A ferramenta de linha de comandos para gerar um aplicativo Express ainda é a express, mas para fazer o upgrade para a nova versão , é preciso desinstalar o gerador de aplicativos Express 3 e, em seguida, instalar o novo express-generator.

Instalação

Se já tiver o gerador de aplicativos do Express 3 instalado no seu sistema, é preciso desinstalá-lo:

$ npm uninstall -g express

Dependendo de como os seus privilégios de arquivos e diretórios estão configurados, pode ser necessário executar este comando com sudo.

Agora instale o novo gerador:

$ npm install -g express-generator

Dependendo de como os seus privilégios de arquivos e diretórios estão configurados, pode ser necessário executar este comando com sudo.

Agora o comando express no seu sistema está atualizado para o gerador do Express 4.

Mudanças no gerador de aplicativos

As opções e o uso do comando permanecem em grande parte as mesmas, com as seguintes exceções:

• Foi removida a opção --sessions.
• Foi removida a opção --jshtml.
• Foi incluída a opção --hogan para suportar o Hogan.js.

Exemplo

Execute o seguinte comando para criar um aplicativo do Express 4:

$ express app4

Se olhar o conteúdo do arquivo app4/app.js, você verá que todas as funções de middleware (exceto express.static) que são requeridas pelo aplicativo estão a carregadas como módulos independentes, e o middleware de router não está mais explicitamente carregado no aplicativo.

Você irá também notar que o arquivo app.js é agora um módulo do Node.js, ao invés do aplicativo independente gerado pelo antigo gerador.

Após instalar as dependências, inicie o aplicativo usando o seguinte comando:

$ npm start

Se olhar o script de inicialização npm no arquivo package.json, você irá notar que o comando real que inicia o aplicativo é o node ./bin/www, que antes era node app.js no Express 3.

Como o arquivo app.js que foi gerado pelo gerador do Express 4 é agora um módulo do Node.js, ele não pode mais ser iniciado independentemente como um aplicativo (a não ser que modifique o código). O módulo deve ser carregado em um arquivo Node.js e iniciado através do arquivo Node.js. O arquivo Node.js é ./bin/www neste caso.

Nem o diretório bin e nem o arquivo sem extensão www são obrigatórios para a criação ou inicialização de um aplicativo Express. Eles são apenas sugestões feitas pelo gerador, portanto fique a vontade para modificá-los para adequá-los às suas necessidades.

Se livre do diretório www e mantenha as coisas “da maneira do Express 3”, exclua a linha que diz module.exports = app; no final do arquivo app.js, em seguida cole o seguinte código em seu lugar:

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

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

Assegure-se de carregar o módulo debug em cima do arquivo app.js usando o seguinte código:

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

Em seguida, mude o "start": "node ./bin/www" no arquivo package.json para "start": "node app.js".

Você agora moveu a funcionalidade do ./bin/www de volta para o app.js. Esta mudança não é recomendada, mas o exercício ajuda você a entender como o arquivo ./bin/www funciona, e porque o arquivo app.js não é mais iniciado por conta própria.