Objeto Request

El objeto req representa la petición HTTP y tiene propiedades para el query string de la petición, parámetros, body, headers HTTP, etc. En esta documentación y por convención, el objeto siempre se denomina req (y la respuesta HTTP es res) pero su nombre real lo determinan los parámetros de la función de callback en la que estás trabajando.

Por ejemplo:

app.get('/user/:id', (req, res) => {
  res.send(`user ${req.params.id}`);
});

Pero también podrías tener:

app.get('/user/:id', (request, response) => {
  response.send(`user ${request.params.id}`);
});

El objeto req es una versión mejorada del propio objeto request de Node y soporta todos los campos y métodos integrados.

Propiedades

El objeto req contiene una serie de propiedades que proporcionan información sobre la solicitud HTTP, como encabezados, parámetros de consulta, y más.

req.app

Esta propiedad contiene una referencia a la instancia de la aplicación Express que está usando el middleware.

Si sigues el patrón en el que creas un módulo que simplemente exporta una función middleware y la cargas con require() en tu archivo principal, entonces el middleware puede acceder a la instancia de Express vía req.app

Por ejemplo:

app.get('/viewdirectory', require('./mymiddleware.cjs'));

import mymiddleware from './mymiddleware.mjs';

app.get('/viewdirectory', mymiddleware);

Y el módulo middleware en sí:

module.exports = (req, res) => {
  res.send(`The views directory is ${req.app.get('views')}`);
};

export default (req, res) => {
  res.send(`The views directory is ${req.app.get('views')}`);
};

req.baseUrl

La ruta URL en la que se montó una instancia de router.

La propiedad req.baseUrl es similar a la propiedad mountpath del objeto app, excepto que app.mountpath devuelve el patrón o patrones de ruta coincidentes.

Por ejemplo:

const greet = express.Router();

greet.get('/jp', (req, res) => {
  console.log(req.baseUrl); // /greet
  res.send('Konnichiwa!');
});

app.use('/greet', greet); // load the router on '/greet'

Incluso si usas un patrón de ruta o un conjunto de patrones de ruta para cargar el router, la propiedad baseUrl devuelve el string coincidente, no el patrón o patrones. En el siguiente ejemplo, el router greet se carga en dos patrones de ruta.

app.use(['/gre:"param"t', '/hel{l}o'], greet); // load the router on '/gre:"param"t' and '/hel{l}o'

Cuando se hace una petición a /greet/jp, req.baseUrl es “/greet”. Cuando se hace una petición a /hello/jp, req.baseUrl es “/hello”.

req.body

Contiene pares clave-valor de los datos enviados en el body de la petición. Por defecto, es undefined, y se rellena cuando usas middleware de parseo de body como express.json() o express.urlencoded().

El siguiente ejemplo muestra cómo usar middleware de parseo de body para rellenar req.body.

const express = require('express');

const app = express();

app.use(express.json()); // for parsing application/json
app.use(express.urlencoded({ extended: true })); // for parsing application/x-www-form-urlencoded

app.post('/profile', (req, res, next) => {
  console.log(req.body);
  res.json(req.body);
});

import express from 'express';

const app = express();

app.use(express.json()); // for parsing application/json
app.use(express.urlencoded({ extended: true })); // for parsing application/x-www-form-urlencoded

app.post('/profile', (req, res, next) => {
  console.log(req.body);
  res.json(req.body);
});

req.cookies

Cuando usas el middleware cookie-parser, esta propiedad es un objeto que contiene las cookies enviadas por la petición. Si la petición no contiene cookies, por defecto es {}.

// Cookie: name=tj
console.dir(req.cookies.name);
// => "tj"

Si la cookie ha sido firmada, tienes que usar req.signedCookies.

Para más información, problemas o dudas, consulta cookie-parser.

req.fresh

Cuando la respuesta sigue “fresca” en el caché del cliente se devuelve true, de lo contrario se devuelve false para indicar que el caché del cliente ahora está stale y debería enviarse la respuesta completa.

Cuando un cliente envía el header de petición Cache-Control: no-cache para indicar una petición de recarga end-to-end, este módulo devolverá false para hacer transparente el manejo de estas peticiones.

Más detalles sobre cómo funciona la validación de caché se pueden encontrar en la Especificación de Caché HTTP/1.1.

console.dir(req.fresh);
// => true

req.host

Contiene el host derivado del encabezado HTTP Host.

Cuando el ajuste trust proxy no evalúa a false, esta propiedad obtendrá en su lugar el valor del campo de header X-Forwarded-Host. Este header puede ser establecido por el cliente o por el proxy.

Si hay más de un header X-Forwarded-Host en la petición, se usa el valor del primer header. Esto incluye un único header con valores separados por comas, en el que se usa el primer valor.

// Host: "example.com:3000"
console.dir(req.host);
// => 'example.com:3000'

// Host: "[::1]:3000"
console.dir(req.host);
// => '[::1]:3000'

req.hostname

Contiene el nombre del host derivado del header HTTP Host.

Cuando el ajuste trust proxy no evalúa a false, esta propiedad obtendrá en su lugar el valor del campo de header X-Forwarded-Host. Este header puede ser establecido por el cliente o por el proxy.

Si hay más de un header X-Forwarded-Host en la petición, se usa el valor del primer header. Esto incluye un único header con valores separados por comas, en el que se usa el primer valor.

// Host: "example.com:3000"
console.dir(req.hostname);
// => 'example.com'

req.ip

Contiene la dirección IP remota de la petición.

Cuando el ajuste trust proxy no evalúa a false, el valor de esta propiedad se deriva de la entrada más a la izquierda en el header X-Forwarded-For. Este header puede ser establecido por el cliente o por el proxy.

console.dir(req.ip);
// => "127.0.0.1"

req.ips

Cuando el ajuste trust proxy no evalúa a false, esta propiedad contiene un array de direcciones IP especificadas en el header de petición X-Forwarded-For. De lo contrario, contiene un array vacío. Este header puede ser establecido por el cliente o por el proxy.

Por ejemplo, si X-Forwarded-For es client, proxy1, proxy2, req.ips sería ["client", "proxy1", "proxy2"], donde proxy2 es el más downstream.

// normal request, or `trust proxy` disabled (the default)
console.dir(req.ips);
// => []

// app.set('trust proxy', true) and
// request header `X-Forwarded-For: client, proxy1, proxy2`
console.dir(req.ips);
// => ['client', 'proxy1', 'proxy2']

req.method

Contiene un string correspondiente al método HTTP de la petición: GET, POST, PUT, etc.

app.use((req, res, next) => {
  console.dir(req.method);
  // => 'GET'
  next();
});

req.originalUrl

Esta propiedad es muy similar a req.url; sin embargo, retiene la URL original de la petición, permitiéndote reescribir req.url libremente para propósitos de enrutamiento interno. Por ejemplo, la funcionalidad de “montaje” de app.use() reescribirá req.url para eliminar el punto de montaje.

// GET /search?q=something
console.dir(req.originalUrl);
// => "/search?q=something"

req.originalUrl está disponible tanto en objetos middleware como router, y es una combinación de req.baseUrl y req.url. Considera el siguiente ejemplo:

// GET 'http://www.example.com/admin/new?sort=desc'
app.use('/admin', (req, res, next) => {
  console.dir(req.originalUrl); // '/admin/new?sort=desc'
  console.dir(req.baseUrl); // '/admin'
  console.dir(req.path); // '/new'
  next();
});

req.params

Esta propiedad es un objeto que contiene propiedades mapeadas a los “parámetros” de ruta con nombre. Por ejemplo, si tienes la ruta /user/:name, entonces la propiedad “name” está disponible como req.params.name. Este objeto por defecto es Object.create(null) cuando se usan rutas de string, pero permanece como un objeto estándar con un prototipo normal cuando la ruta se define con una expresión regular.

// GET /user/tj
console.dir(req.params.name);
// => "tj"

Las propiedades correspondientes a parámetros comodín son arrays que contienen segmentos de ruta separados por /:

app.get('/files/*file', (req, res) => {
  console.dir(req.params.file);
  // GET /files/note.txt
  // => [ 'note.txt' ]
  // GET /files/images/image.png
  // => [ 'images', 'image.png' ]
});

Cuando usas una expresión regular para la definición de la ruta, los grupos de captura se proporcionan como claves enteras usando req.params[n], donde n es el n^th grupo de captura.

app.use(/^\/file\/(.*)$/, (req, res) => {
  // GET /file/javascripts/jquery.js
  console.dir(req.params[0]);
  // => "javascripts/jquery.js"
});

Los grupos de captura nombrados en expresiones regulares se comportan como parámetros de ruta nombrados. Por ejemplo, el grupo de la expresión /^\/file\/(?<path>.*)$/ está disponible como req.params.path.

Si necesitas hacer cambios a una clave en req.params, usa el manejador app.param. Los cambios son aplicables solo a parámetros ya definidos en la ruta path.

Cualquier cambio hecho al objeto req.params en un middleware o manejador de ruta se reiniciará.

req.path

Contiene la parte path de la URL de la petición.

// example.com/users?sort=desc
console.dir(req.path);
// => "/users"

req.protocol

Contiene el string de protocolo de la petición: http o (para peticiones TLS) https.

Cuando el ajuste trust proxy no evalúa a false, esta propiedad usará el valor del campo de header X-Forwarded-Proto si está presente. Este header puede ser establecido por el cliente o por el proxy.

console.dir(req.protocol);
// => "http"

req.query

Esta propiedad es un objeto que contiene una propiedad por cada parámetro del query string en la ruta. Cuando query parser está deshabilitado, es un objeto vacío {}, de lo contrario es el resultado del query parser configurado.

El valor de esta propiedad puede configurarse con el ajuste de aplicación query parser para que funcione como tu aplicación lo necesite. Un parser de query string muy popular es el módulo qs, y este se usa por defecto. El módulo qs es muy configurable con muchos ajustes, y puede ser deseable usar ajustes diferentes a los por defecto para rellenar req.query:

const qs = require('qs');
app.set('query parser', (str) =>
  qs.parse(str, {
    /* custom options */
  })
);

import qs from 'qs';

app.set('query parser', (str) =>
  qs.parse(str, {
    /* custom options */
  })
);

Consulta la documentación del ajuste de aplicación query parser para otras opciones de personalización.

req.res

Esta propiedad contiene una referencia al objeto response que se relaciona con este objeto de solicitud.

app.get('/', (req, res) => {
  console.dir(req.res === res);
  // => true
  res.send('OK');
});

req.route

Contiene la ruta coincidente actualmente (un objeto Route). Por ejemplo:

app.get('/user/{:id}', (req, res) => {
  console.dir(req.route, { depth: null });
  res.send('GET');
});

Ejemplo de salida del fragmento anterior:

Route {
  path: '/user/{:id}',
  stack: [
    Layer {
      handle: [Function (anonymous)],
      keys: [],
      name: '<anonymous>',
      params: undefined,
      path: undefined,
      slash: false,
      matchers: [ [Function: match] ],
      method: 'get'
    }
  ],
  methods: [Object: null prototype] { get: true }
}

req.secure

Una propiedad Boolean que es true si se ha establecido una conexión TLS. Equivalente a lo siguiente:

req.protocol === 'https';

req.signedCookies

Cuando usas el middleware cookie-parser, esta propiedad contiene las cookies firmadas enviadas por la petición, sin firmar y listas para usar. Las cookies firmadas residen en un objeto diferente para mostrar la intención del desarrollador; de lo contrario, podría producirse un ataque malicioso sobre los valores de req.cookie (que son fáciles de falsificar). Ten en cuenta que firmar una cookie no la hace “oculta” ni cifrada; sino que simplemente evita la manipulación (porque el secreto usado para firmar es privado).

Si no se envían cookies firmadas, la propiedad por defecto es {}.

// Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
console.dir(req.signedCookies.user);
// => "tobi"

Para más información, problemas o dudas, consulta cookie-parser.

req.stale

Indica si la petición está “stale,” y es lo opuesto a req.fresh. Para más información, consulta req.fresh.

console.dir(req.stale);
// => true

req.subdomains

Un array de subdominios en el nombre de dominio de la petición.

// Host: "tobi.ferrets.example.com"
console.dir(req.subdomains);
// => ["ferrets", "tobi"]

La propiedad de aplicación subdomain offset, que por defecto es 2, se usa para determinar el inicio de los segmentos de subdominio. Para cambiar este comportamiento, cambia su valor usando app.set.

req.xhr

Una propiedad Boolean que es true si el campo de header X-Requested-With de la petición es “XMLHttpRequest”, indicando que la petición fue emitida por una librería de cliente como jQuery.

console.dir(req.xhr);
// => true

Métodos

El objeto req también contiene una serie de métodos que pueden usarse para realizar varias tareas relacionadas con la solicitud HTTP, como verificar el tipo de contenido, recuperar valores de encabezado, y más.

req.accepts()

Comprueba si los tipos de contenido especificados son aceptables, basándose en el campo de header HTTP Accept de la petición. El método devuelve la mejor coincidencia, o si ninguno de los tipos de contenido especificados es aceptable, devuelve false (en cuyo caso, la aplicación debería responder con 406 "Not Acceptable").

El valor de type puede ser un solo string de tipo MIME (como “application/json”), un nombre de extensión como “json”, una lista delimitada por comas, o un array. Para una lista o array, el método devuelve la mejor coincidencia (si la hay).

// Accept: text/html
req.accepts('html');
// => "html"

// Accept: text/*, application/json
req.accepts('html');
// => "html"
req.accepts('text/html');
// => "text/html"
req.accepts(['json', 'text']);
// => "json"
req.accepts('application/json');
// => "application/json"

// Accept: text/*, application/json
req.accepts('image/png');
req.accepts('png');
// => false

// Accept: text/*;q=.5, application/json
req.accepts(['html', 'json']);
// => "json"

Para más información, o si tienes problemas o dudas, consulta accepts.

req.acceptsCharsets()

Devuelve el primer conjunto de caracteres aceptado de los conjuntos de caracteres especificados, basándose en el campo de header HTTP Accept-Charset de la petición. Si ninguno de los conjuntos de caracteres especificados es aceptado, devuelve false.

// Accept-Charset: utf-8, iso-8859-1;q=0.5
req.acceptsCharsets('utf-8', 'iso-8859-1');
// => 'utf-8'

req.acceptsCharsets('us-ascii');
// => false

Para más información, o si tienes problemas o dudas, consulta accepts.

req.acceptsEncodings()

Devuelve la primera codificación aceptada de las codificaciones especificadas, basándose en el campo de header HTTP Accept-Encoding de la petición. Si ninguna de las codificaciones especificadas es aceptada, devuelve false.

// Accept-Encoding: gzip, deflate
req.acceptsEncodings('gzip', 'deflate');
// => 'gzip'

req.acceptsEncodings('br');
// => false

Para más información, o si tienes problemas o dudas, consulta accepts.

req.acceptsLanguages()

Devuelve el primer idioma aceptado de los idiomas especificados, basándose en el campo de header HTTP Accept-Language de la petición. Si ninguno de los idiomas especificados es aceptado, devuelve false.

Si no se proporciona un argumento lang, entonces req.acceptsLanguages() devuelve todos los idiomas del header HTTP Accept-Language como un Array.

// Accept-Language: en;q=0.8, es
req.acceptsLanguages('en', 'es');
// => 'es'

req.acceptsLanguages();
// => ['es', 'en']

Para más información, o si tienes problemas o dudas, consulta accepts.

Fuente de Express (5.x): request.js línea 172

Fuente de Accepts (2.0): index.js línea 195

req.get()

Devuelve el campo de header HTTP de petición especificado (coincidencia insensible a mayúsculas y minúsculas). Los campos Referrer y Referer son intercambiables.

req.get('Content-Type');
// => "text/plain"

req.get('content-type');
// => "text/plain"

req.get('Something');
// => undefined

Alias como req.header(field).

req.is()

Devuelve el tipo de contenido coincidente si el campo de header HTTP “Content-Type” de la petición entrante coincide con el tipo MIME especificado por el parámetro type. Si la petición no tiene body, devuelve null. De lo contrario devuelve false.

// With Content-Type: text/html; charset=utf-8
req.is('html'); // => 'html'
req.is('text/html'); // => 'text/html'
req.is('text/*'); // => 'text/*'

// When Content-Type is application/json
req.is('json'); // => 'json'
req.is('application/json'); // => 'application/json'
req.is('application/*'); // => 'application/*'

// Using arrays
// When Content-Type is application/json
req.is(['json', 'html']); // => 'json'

// Using multiple arguments
// When Content-Type is application/json
req.is('json', 'html'); // => 'json'

req.is('html'); // => false
req.is(['xml', 'yaml']); // => false
req.is('xml', 'yaml'); // => false

Para más información, o si tienes problemas o dudas, consulta type-is.

req.range()

Parser del header Range.

Se devolverá un array de rangos o números negativos indicando un error de parseo.

• -2 señala un string de header mal formado
• -1 señala un rango insatisfacible

// parse header from request
const range = req.range(1000);

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach((r) => {
    // do something with r.start and r.end
  });
}