expressjs.com/pt-br/guide/writing-middleware.md

layout, title, description, menu, order, redirect_from

layout	title	description	menu	order	redirect_from
page	Escrevendo middlewares para uso em aplicativos do Express	Learn how to write custom middleware functions for Express.js applications, including examples and best practices for enhancing request and response handling.	guide	2

Escrevendo middlewares para uso em aplicativos do Express

Visão Geral

Middleware functions are functions that have access to the [request object](/{{ page.lang }}/5x/api.html#req) (req), the [response object](/{{ page.lang }}/5x/api.html#res) (res), and the next function in the application's request-response cycle. A próxima função middleware é comumente denotada por uma variável chamada next.

Funções de middleware podem executar as seguintes tarefas:

• Executar qualquer código.
• Fazer mudanças nos objetos de solicitação e resposta.
• Encerrar o ciclo de solicitação-resposta.
• Chamar o próximo middleware na pilha.

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.

O exemplo a seguir mostra os elementos de uma chamada de função de middleware:

Caminho (rota) para o qual a função de middleware é aplicada.

A função de middleware.

Argumento de retorno de chamada para a função de middleware, chamado de "next" por convenção.

HTTP response argument to the middleware function, called "res" by convention.

HTTP request argument to the middleware function, called "req" by convention.

O método HTTP para o qual a função de middleware é aplicada.

Starting with Express 5, middleware functions that return a Promise will call next(value) when they reject or throw an error. next will be called with either the rejected value or the thrown Error.

Exemplo

Aqui está um exemplo de um simples aplicativo "Hello World" do Express, para o qual serão definidas duas funções de middleware: The remainder of this article will define and add three middleware functions to the application: one called myLogger that prints a simple log message, one called requestTime that displays the timestamp of the HTTP request, and one called validateCookies that validates incoming cookies.

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

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(3000)

Middleware function myLogger

Aqui está um exemplo simples de uma função de middleware chamada "myLogger". Esta função apenas imprime "LOGGED" quando uma solicitação para o aplicativo passa por ela. A função de middleware é designada para uma variável chamada `myLogger`.

const myLogger = function (req, res, next) {
  console.log('LOGGED')
  next()
}

Observe a chamada acima para `next()`. A chamada desta função chama a próxima função de middleware no aplicativo. A função `next()` não faz parte do Node.js ou da API Express, mas é o terceiro argumento que é passado para a função de middleware. A função `next()` poderia ter qualquer nome, mas por convenção ela é sempre chamada de "next". Para evitar confusão, sempre use esta convenção.

Para carregar a função de middleware, chame app.use(), especificando a função de middleware. Por exemplo, o código a seguir carrega a função de middleware do myLogger antes da rota para o caminho raiz (/).

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

const myLogger = function (req, res, next) {
  console.log('LOGGED')
  next()
}

app.use(myLogger)

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(3000)

Sempre que o aplicativo recebe uma chamada, ele imprime a mensagem "LOGGED" no terminal.

A ordem de carregamento do middleware é importante: funções de middleware que são carregadas primeiro também são executadas primeiro.

Se myLogger é carregada após a rota para o caminho raiz, a chamada nunca chegará a ela e o aplicativo não imprimirá "LOGGED", pois o manipulador de rota do caminho raiz encerra o ciclo de solicitação-resposta.

A função de middleware myLogger simplesmente imprime uma mensagem, e em seguida passa a solicitação para a próxima função de middleware na pilha chamando a função next().

Middleware function requestTime

O próximo exemplo inclui uma propriedade chamada requestTime ao objeto da solicitação. Iremos chamar esta função de middleware de "requestTime".

const requestTime = function (req, res, next) {
  req.requestTime = Date.now()
  next()
}

O aplicativo agora usa a função de middleware requestTime. Além disso, a função de retorno de chamada do caminho raiz usa a propriedade que a função de middleware inclui no req (o objeto da solicitação).

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

const requestTime = function (req, res, next) {
  req.requestTime = Date.now()
  next()
}

app.use(requestTime)

app.get('/', (req, res) => {
  let responseText = 'Hello World!<br>'
  responseText += `<small>Requested at: ${req.requestTime}</small>`
  res.send(responseText)
})

app.listen(3000)

Ao fazer uma solicitação para a raiz do aplicativo, o aplicativo agora exibe o registro de data e hora da sua solicitação no navegador.

Middleware function validateCookies

Finally, we'll create a middleware function that validates incoming cookies and sends a 400 response if cookies are invalid.

Here's an example function that validates cookies with an external async service.

async function cookieValidator (cookies) {
  try {
    await externallyValidateCookie(cookies.testCookie)
  } catch {
    throw new Error('Invalid cookies')
  }
}

Here, we use the cookie-parser middleware to parse incoming cookies off the req object and pass them to our cookieValidator function. The validateCookies middleware returns a Promise that upon rejection will automatically trigger our error handler.

const express = require('express')
const cookieParser = require('cookie-parser')
const cookieValidator = require('./cookieValidator')

const app = express()

async function validateCookies (req, res, next) {
  await cookieValidator(req.cookies)
  next()
}

app.use(cookieParser())

app.use(validateCookies)

// error handler
app.use((err, req, res, next) => {
  res.status(400).send(err.message)
})

app.listen(3000)

Note how `next()` is called after `await cookieValidator(req.cookies)`. This ensures that if `cookieValidator` resolves, the next middleware in the stack will get called. If you pass anything to the `next()` function (except the string `'route'` or `'router'`), Express regards the current request as being an error and will skip any remaining non-error handling routing and middleware functions.

Como você tem acesso ao objeto da solicitação, ao objeto de resposta, à próxima função de middleware na pilha, e à API completa do Node.js, as possibilidades com as funções de middleware são ilimitadas.

Para obter mais informações sobre middlewares no Express, consulte: [Usando middlewares no Express](/{{ page.lang }}/guide/using-middleware.html).

Configurable middleware

If you need your middleware to be configurable, export a function which accepts an options object or other parameters, which, then returns the middleware implementation based on the input parameters.

File: my-middleware.js

module.exports = function (options) {
  return function (req, res, next) {
    // Implement the middleware function based on the options object
    next()
  }
}

The middleware can now be used as shown below.

const mw = require('./my-middleware.js')

app.use(mw({ option1: '1', option2: '2' }))

Refer to cookie-session and compression for examples of configurable middleware.