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.O Express é uma estrutura web de roteamento e middlewares que tem uma funcionalidade mínima por si só: Um aplicativo do Express é essencialmente uma série de chamadas de funções de middleware.
Funções de Middleware são funções que tem acesso
ao objeto de solicitação
(req
), o objeto de resposta
(res
), e a próxima função de middleware no ciclo
solicitação-resposta do aplicativo. A próxima função middleware é
comumente denotada por uma variável chamada next
.
Funções de middleware podem executar as seguintes tarefas:
Se a atual função de middleware não terminar o ciclo de
solicitação-resposta, ela precisa chamar next()
para passar o controle para a próxima função de middleware. Caso
contrário, a solicitação ficará suspensa.
Um aplicativo Express pode usar os seguintes tipos de middleware:
É possível carregar middlewares de nível de roteador e de nível do aplicativo com um caminho de montagem opcional. É possível também carregar uma série de funções de middleware juntas, o que cria uma sub-pilha do sistema de middleware em um ponto de montagem.
Vincule middlewares de nível do aplicativo a uma instância do
objeto app usando as funções
app.use()
e app.METHOD()
, onde
METHOD
é o método HTTP da solicitação que a função
de middleware manipula (como GET, PUT, ou POST) em letras minúsculas.
Este exemplo mostra uma função de middleware sem um caminho de montagem. A função é executada sempre que o aplicativo receber uma solicitação.
var app = express();
app.use(function (req, res, next) {
console.log('Time:', Date.now());
next();
});
Este exemplo mostra uma função de middleware montada no caminho
/user/:id
. A função é executada para qualquer tipo
de solicitação HTTP no caminho /user/:id
.
app.use('/user/:id', function (req, res, next) {
console.log('Request Type:', req.method);
next();
});
Este exemplo mostra uma rota e sua função
manipuladora (sistema de middleware). A função manipula solicitações
GET ao caminho /user/:id
.
app.get('/user/:id', function (req, res, next) {
res.send('USER');
});
Aqui está um exemplo de carregamento de um série de funções de
middleware em um ponto de montagem, com um caminho de montagem.
Ele
ilustra uma sub-pilha de middleware que imprime informações de
solicitação para qualquer tipo de solicitação HTTP no caminho /user/:id
.
app.use('/user/:id', function(req, res, next) {
console.log('Request URL:', req.originalUrl);
next();
}, function (req, res, next) {
console.log('Request Type:', req.method);
next();
});
Manipuladores de rota permitem a você definir várias rotas para
um caminho. O exemplo abaixo define duas rotas para solicitações GET
no caminho /user/:id
. A segunda rota não irá
causar nenhum problema, mas ela nunca será chamada pois a primeira
rota termina o ciclo solicitação-resposta.
Este exemplo mostra uma sub-pilha de middleware que manipula
solicitações GET no caminho /user/:id
.
app.get('/user/:id', function (req, res, next) {
console.log('ID:', req.params.id);
next();
}, function (req, res, next) {
res.send('User Info');
});
// handler for the /user/:id path, which prints the user ID
app.get('/user/:id', function (req, res, next) {
res.end(req.params.id);
});
Para pular o restante das funções de middleware de uma pilha de
middlewares do roteador, chame next('route')
para passar o controle para a próxima rota.
NOTA: O next('route')
irá
funcionar apenas em funções de middleware que são carregadas usando
as funções app.METHOD()
ou router.METHOD()
.
Este exemplo mostra uma sub-pilha de middleware que manipula
solicitações GET no caminho /user/:id
.
app.get('/user/:id', function (req, res, next) {
// if the user ID is 0, skip to the next route
if (req.params.id == 0) next('route');
// otherwise pass the control to the next middleware function in this stack
else next(); //
}, function (req, res, next) {
// render a regular page
res.render('regular');
});
// handler for the /user/:id path, which renders a special page
app.get('/user/:id', function (req, res, next) {
res.render('special');
});
Middlewares de nível de roteador funcionam da mesma forma que
os middlewares de nível do aplicativo, mas estão vinculados a uma
instância do express.Router()
.
var router = express.Router();
Carregue os middlewares de nível de roteador usando as funções router.use()
e router.METHOD()
.
O seguinte código de exemplo replica o sistema de middleware que é mostrado acima para o middleware de nível do aplicativo, usando um middleware de nível de roteador:
var app = express();
var router = express.Router();
// a middleware function with no mount path. This code is executed for every request to the router
router.use(function (req, res, next) {
console.log('Time:', Date.now());
next();
});
// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path
router.use('/user/:id', function(req, res, next) {
console.log('Request URL:', req.originalUrl);
next();
}, function (req, res, next) {
console.log('Request Type:', req.method);
next();
});
// a middleware sub-stack that handles GET requests to the /user/:id path
router.get('/user/:id', function (req, res, next) {
// if the user ID is 0, skip to the next router
if (req.params.id == 0) next('route');
// otherwise pass control to the next middleware function in this stack
else next(); //
}, function (req, res, next) {
// render a regular page
res.render('regular');
});
// handler for the /user/:id path, which renders a special page
router.get('/user/:id', function (req, res, next) {
console.log(req.params.id);
res.render('special');
});
// mount the router on the app
app.use('/', router);
Middlewares de manipulação de erros sempre levam quatro argumentos. Você deve fornecer quatro argumentos para identificá-lo como uma
função de middleware de manipulação de erros. Mesmo se você não
precisar usar o objeto next
, você deve
especificá-lo para manter a assinatura. Caso contrário, o objeto
next
será interpretado como um middleware comum e
a manipulação de erros falhará.
Defina funções de middleware de manipulação de
erros da mesma forma que outras funções de middleware, exceto que com
quatro argumentos ao invés de três, especificamente com a assinatura
(err, req, res, next)
):
app.use(function(err, req, res, next) {
console.error(err.stack);
res.status(500).send('Something broke!');
});
Para obter detalhes sobre middleware de manipulação de erros, consulte Manipulação de erros.
Desde a versão 4.x, o Express não depende mais do Connect. Com
exceção da express.static
, todas as funções de
middleware que eram previamente incluídas com o Express estão agora
em módulos separados. Visualize a lista
de funções de middleware.
A única função de middleware integrada no Express é a
express.static
. Esta função é baseada no
serve-static,
e é responsável por entregar os ativos estáticos de um aplicativo do
Express.
O argumento root
especifica o diretório raiz
a partir do qual entregar os ativos estáticos.
O objeto opcional options
pode ter as
seguintes propriedades:
Propriedade | Descrição | Tipo | Padrão |
---|---|---|---|
dotfiles |
Opção para entregar dotfiles. Os valores possíveis são “allow”, “deny”, e “ignore” | Sequência de caracteres | “ignore” |
etag |
Ativa ou desativa a geração de etag | Booleano | true |
extensions |
Configura os fallbacks de extensão de arquivo | Matriz | [] |
index |
Envia o arquivo de índice do diretório. Configure false para desativar a indexação de diretórios. |
Variado | “index.html” |
lastModified |
Configura o cabeçalho Last-Modified para a última data de modificação do arquivo no sistema operacional. Os valores possíveis são true ou false . |
Booleano | true |
maxAge |
Configura a propriedade max-age do cabeçalho Cache-Control, em milissegundos ou uma sequência de caracteres no formato ms | Número | 0 |
redirect |
Redireciona para o “/” final quando o caminho do arquivo é um diretório. | Booleano | true |
setHeaders |
Função para configurar cabeçalhos HTTP para entregar com o arquivo. | Função |
Aqui está um exemplo de uso da função de middleware express.static
com um objeto options elaborado:
var options = {
dotfiles: 'ignore',
etag: false,
extensions: ['htm', 'html'],
index: false,
maxAge: '1d',
redirect: false,
setHeaders: function (res, path, stat) {
res.set('x-timestamp', Date.now());
}
}
app.use(express.static('public', options));
É possível ter mais do que um diretório estático por aplicativo:
app.use(express.static('public'));
app.use(express.static('uploads'));
app.use(express.static('files'));
Para obter mais detalhes sobre a função serve-static
e suas opções, consulte: documentação doserve-static.
Use middlewares de terceiros para incluir funcionalidades aos aplicativos do Express
Instale o módulo Node.js para a funcionalidade requerida, em seguida carregue-a no seu aplicativo no nível do aplicativo ou no nível de roteador.
O exemplo a seguir ilustra a instalação e carregamento da
função de middleware para análise sintática de cookies cookie-parser
.
$ npm install cookie-parser
var express = require('express');
var app = express();
var cookieParser = require('cookie-parser');
// load the cookie-parsing middleware
app.use(cookieParser());
Para obter uma lista parcial de funções de middleware de terceiros que são comumente utilizadas com o Express, consulte: Middleware de Terceiros.