Esta tradução fornecida pelo StrongLoop / IBM.

Este documento pode estar desatualizado em rela√ß√£o √† documenta√ß√£o em Ingl√™s. Para obter as atualiza√ß√Ķes mais recentes, consulte a documenta√ß√£o em Ingl√™s.

‚úĖ

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

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

Consulte também:

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.

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

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:

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:

Objeto Descrição
Node.js O Express 4 requer o Node.js 0.10.x ou posterior e descartou o suporte ao Node.js 0.8.x.

http.createServer()

O módulo http não é mais necessário, a não ser que você precise trabalhar diretamente com ele (socket.io/SPDY/HTTPS). O aplicativo pode ser iniciado usando a função app.listen().

app.configure()

A função app.configure() foi removida. Use a função process.env.NODE_ENV ou app.get('env') para detectar o ambiente e configurar o aplicativo de acordo com ele.

json spaces

A propriedade de aplicativo json spaces est√° desativada por padr√£o no Express 4.

req.accepted()

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

res.location()

N√£o resolve mais URLs relativas.

req.params

Era uma matriz; agora é um objeto.

res.locals

Era uma função; agora é um objeto.

res.headerSent

Mudado para res.headersSent.

app.route

Agora disponível como app.mountpath.

res.on('header')

Removido.

res.charset

Removido.

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

A funcionalidade é agora limitada a configurar o valor básico do cookie. Use res.cookie() para funcionalidades adicionais.

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

A não ser que precise trabalhar diretamente com o módulo http (socket.io/SPDY/HTTPS), carregá-lo não é necessário, e o aplicativo pode ser iniciado simplesmente desta forma:

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:

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.