Roteamento

O Roteamento refere-se a como os endpoints de uma aplicação (URIs) respondem às requisições do cliente. Para uma introdução ao roteamento, consulte Roteamento básico.

Rotas são definidas utilizando métodos do objeto app do Express que correspondem aos métodos HTTP; por exemplo, app.get() para lidar com requisições GET e app.post() para requisições POST. Para a lista completa, veja app.METHOD. Você também pode utilizar app.all() para lidar com todos os métodos HTTP e app.use() para especificar middleware como funções callback (Veja Usando middlewares para mais detalhes).

Esses métodos de roteamento especificam uma função callback a ser chamada quando a aplicação recebe uma requisição à rota e método HTTP especificados. Em outras palavras, a aplicação “escuta” requisições que se encaixam nas rotas e métodos especificados e, quando há alguma correspondência, chama a função callback especificada.

Na realidade, métodos de roteamento podem possuir mais de uma função callback como argumento. Com múltiplas funções, é importante passar next como argumento da função e chamar next() para passar o controle para a próxima.

O código a seguir é um exemplo de uma rota muito básica.

const express = require('express')
const app = express()

// Responde com 'hello world' quando uma requisição é feita à homepage
app.get('/', (req, res) => {
  res.send('hello world')
})

Métodos de roteamento

Um método de roteamento é derivado a partir de um dos métodos HTTP, e é anexado a uma instância da classe express.

o código a seguir é um exemplo de rotas para a raiz do aplicativo que estão definidas para os métodos GET e POST.

// rota do método GET
app.get('/', (req, res) => {
  res.send('requisição GET à homepage')
})

// rota do método POST
app.post('/', (req, res) => {
  res.send('requisição POST à homepage')
})

O Express suporta métodos que correspondem a todos os métodos de requisição HTTP: get, post, etc. Pra uma lista completa, veja app.METHOD.

Existe um método de roteamento especial, app.all(), que não é derivado de nenhum método HTTP. Este método é usado para carregar funções de middleware em um caminho para todos os métodos de solicitação.

No exemplo a seguir, o manipulador irá ser executado para solicitações para “/secret” se você estiver usando GET, POST, PUT, DELETE, ou qualquer outro método de solicitação HTTP que é suportado no módulo http.

app.all('/secreto', (req, res, next) => {
  console.log('Acessando a área secreta ...')
  next() // passa o controle pro próximo manipulador
})

Caminhos de rota

Caminhos de rota, em combinação com os métodos de solicitação, definem os terminais em que as solicitações podem ser feitas. Caminhos de rota podem ser sequências de caracteres, padrões de sequência, ou expressões regulares.

Aqui estão alguns exemplos de caminhos de rota baseados em sequências de caracteres

Este caminho de rota corresponde a solicitações à rota raiz, /.

app.get('/', (req, res) => {
  res.send('raiz')
})

Este caminho de rota irá corresponder a solicitações ao /ajuda.

app.get('/ajuda', (req, res) => {
  res.send('ajuda')
})

Este caminho de rota irá corresponder a solicitações ao /qualquer.texto.

app.get('/qualquer.texto', (req, res) => {
  res.send('qualquer.texto')
})

Aqui estão alguns exemplos de caminhos de rota baseados em padrões de sequência

Este caminho de rota irá corresponder ao acd e abcd.

app.get('/ab?cd', (req, res) => {
  res.send('ab?cd')
})

Este caminho de rota irá corresponder ao abcd, abbcd, abbbcd, e assim por diante.

app.get('/ab+cd', (req, res) => {
  res.send('ab+cd')
})

Este caminho de rota irá corresponder ao abcd, abxcd, abRANDOMcd, ab123cd, e assim por diante.

app.get('/ab*cd', (req, res) => {
  res.send('ab*cd')
})

Este caminho de rota irá corresponder ao /abe e /abcde.

app.get('/ab(cd)?e', (req, res) => {
  res.send('ab(cd)?e')
})

Exemplos de caminhos de rota baseados em expressões regulares:

Este caminho de rota irá corresponder a qualquer coisa com um “a” no nome.

app.get(/a/, (req, res) => {
  res.send('/a/')
})

Este caminho de rota irá corresponder a butterfly e dragonfly, mas não a butterflyman, dragonfly man, e assim por diante.

app.get(/.*fly$/, (req, res) => {
  res.send('/.*fly$/')
})

Manipuladores de rota

É possível fornecer várias funções callback que se comportam como middleware para manipular uma solicitação. A única exceção é que estes callbacks podem chamar next('route') para efetuar um bypass nos callbacks restantes. É possível usar este mecanismo para impor pré-condições em uma rota, e em seguida passar o controle para rotas subsequentes se não houveram razões para continuar com a rota atual.

Manipuladores de rota podem estar na forma de uma função, uma matriz de funções, ou combinações de ambas, como mostrado nos seguintes exemplos.

Uma única função callback pode manipular uma rota. Por exemplo:

app.get('/exemplo/a', (req, res) => {
  res.send('A diz olá!')
})

Mais de uma função callback pode manipular uma rota (certifique-se de especificar o objeto next). Por exemplo:

app.get('/exemplo/b', (req, res, next) => {
  console.log('a resposta será enviada para a próxima função ...')
  next()
}, (req, res) => {
  res.send('B diz olá!')
})

Uma matriz de funções callback podem manipular uma rota. Por exemplo:

const cb0 = function (req, res, next) {
  console.log('CB0')
  next()
}
const cb1 = function (req, res, next) {
  console.log('CB1')
  next()
}
const cb2 = function (req, res) {
  res.send('C diz olá!')
}
app.get('/exemplo/c', [cb0, cb1, cb2])

Uma combinação de funções independentes e matrizes de funções podem manipular uma rota. Por exemplo:

const cb0 = function (req, res, next) {
  console.log('CB0')
  next()
}
const cb1 = function (req, res, next) {
  console.log('CB1')
  next()
}
app.get('/example/d', [cb0, cb1], (req, res, next) => {
  console.log('a resposta será enviada pela próxima função ...')
  next()
}, (req, res) => {
  res.send('D diz olá!')
})

Métodos de resposta

Os métodos do objeto de resposta (res) na seguinte tabela podem enviar uma resposta ao cliente, e finalizar o ciclo solicitação-resposta. Se nenhum destes métodos forem chamados a partir de um manipulador de rota, a solicitação do cliente será deixada em suspenso.

app.route()

É possível criar manipuladores de rota encadeáveis para um caminho de rota usando o app.route(). 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: documentação do Router().

Aqui está um exemplo de manipuladores de rotas encadeáveis que são definidos usando app.route().

app.route('/livro')
  .get((req, res) => {
    res.send('Retorna um livro aleatório')
  })
  .post((req, res) => {
    res.send('Adiciona um livro')
  })
  .put((req, res) => {
    res.send('Atualiza o livro')
  })

express.Router

Use a classe express.Router para criar manipuladores de rota modulares e 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 uma função de middleware nele, define algumas rotas, e monta o módulo router em um caminho no aplicativo principal.

Crie um arquivo de roteador com um arquivo chamado passaros.js no diretório do aplicativo, com o seguinte conteúdo:

const express = require('express')
const router = express.Router()
// middleware específico para este roteador
router.use((req, res, next) => {
  console.log('Horário: ', Date.now())
  next()
})
// define a rota da homepage
router.get('/', (req, res) => {
  res.send('Homepage de pássaros')
})
// define a rota 'ajuda'
router.get('/ajuda', (req, res) => {
  res.send('Ajuda sobre pássaros')
})
module.exports = router

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

const passaros = require('./passaros')
// ...
app.use('/passaros', passaros)

O aplicativo será agora capaz de manipular solicitações aos caminhos /passaros e /passaros/ajuda, assim como chamar a função de middleware timeLog que é específica para a rota.