Middleware body-parser

Middleware de análisis de cuerpo para Node.js.

Analiza los cuerpos de las peticiones entrantes en un middleware antes de tus manejadores, disponibles bajo la propiedad req.body.

Nota Como la forma de req.body se basa en entrada controlada por el usuario, todas las propiedades y valores en este objeto no son confiables y deben validarse antes de confiar en ellos. Por ejemplo, req.body.foo.toString() puede fallar de varias maneras, por ejemplo la propiedad foo puede no estar ahí o puede no ser una cadena, y toString puede no ser una función y en cambio una cadena u otra entrada del usuario.

Aprende sobre la anatomía de una transacción HTTP en Node.js.

Este módulo no maneja cuerpos multipart, debido a su naturaleza compleja y típicamente grande. Para cuerpos multipart, puedes estar interesado en los siguientes módulos:

Este módulo proporciona los siguientes analizadores:

Analizador de cuerpo JSON
Analizador de cuerpo raw
Analizador de cuerpo de texto
Analizador de cuerpo de formulario URL-encoded

Otros analizadores de cuerpo que podrían interesarte:

body
co-body

Instalación

npm install body-parser

API

// Import all parsers
const bodyParser = require('body-parser');

// Or import individual parsers directly
const json = require('body-parser/json');
const urlencoded = require('body-parser/urlencoded');
const raw = require('body-parser/raw');
const text = require('body-parser/text');

El objeto bodyParser expone varias fábricas para crear middlewares. Todos los middlewares completarán la propiedad req.body con el cuerpo analizado cuando la cabecera de petición Content-Type coincida con la opción type.

Los diversos errores devueltos por este módulo se describen en la sección de errores.

bodyParser.json([options])

Devuelve un middleware que solo analiza json y solo examina las peticiones donde la cabecera Content-Type coincide con la opción type. Este analizador acepta cualquier codificación Unicode del cuerpo y soporta la inflación automática de las codificaciones gzip, br (brotli) y deflate.

Un nuevo objeto body que contiene los datos analizados se completa en el objeto de petición después del middleware (es decir, req.body).

Opciones

La función json toma un objeto opcional options que puede contener cualquiera de las siguientes claves:

defaultCharset

Especifica el conjunto de caracteres por defecto para el contenido json si el charset no está especificado en la cabecera Content-Type de la petición. Por defecto es utf-8.

inflate

Cuando se establece en true, los cuerpos desinflados (comprimidos) serán inflados; cuando es false, los cuerpos desinflados son rechazados. Por defecto es true.

limit

Controla el tamaño máximo del cuerpo de la petición. Si es un número, el valor especifica el número de bytes; si es una cadena, el valor se pasa a la biblioteca bytes para su análisis. Por defecto es '100kb'.

Se recomienda no configurar un límite muy alto y usar el valor por defecto siempre que sea posible. Permitir payloads más grandes aumenta el uso de memoria por los recursos necesarios para decodificación y transformaciones, y también puede provocar tiempos de respuesta más largos a medida que se procesan más datos. Por ‘muy alto’ nos referimos a valores por encima del por defecto, por ejemplo payloads de 5 MB o más ya pueden empezar a introducir estos riesgos. Con los límites por defecto, estos problemas no ocurren.

reviver

La opción reviver se pasa directamente a JSON.parse como segundo argumento. Puedes encontrar más información sobre este argumento en la documentación de MDN sobre JSON.parse.

strict

Cuando se establece en true, solo aceptará arrays y objetos; cuando es false aceptará cualquier cosa que JSON.parse acepte. Por defecto es true.

type

La opción type se usa para determinar qué tipo de medio analizará el middleware. Esta opción puede ser una cadena, un array de cadenas o una función. Si no es una función, la opción type se pasa directamente a la biblioteca type-is y puede ser un nombre de extensión (como json), un tipo mime (como application/json), o un tipo mime con un comodín (como */* o */json). Si es una función, la opción type se llama como fn(req) y la petición se analiza si devuelve un valor verdadero. Por defecto es application/json.

verify

La opción verify, si se proporciona, se llama como verify(req, res, buf, encoding), donde buf es un Buffer del cuerpo bruto de la petición y encoding es la codificación de la petición. El análisis puede abortarse lanzando un error.

bodyParser.raw([options])

Devuelve un middleware que analiza todos los cuerpos como un Buffer y solo examina las peticiones donde la cabecera Content-Type coincide con la opción type. Este analizador soporta la inflación automática de las codificaciones gzip, br (brotli) y deflate.

Un nuevo objeto body que contiene los datos analizados se completa en el objeto de petición después del middleware (es decir, req.body). Este será un objeto Buffer del cuerpo.

Opciones

La función raw toma un objeto opcional options que puede contener cualquiera de las siguientes claves:

inflate

Cuando se establece en true, los cuerpos desinflados (comprimidos) serán inflados; cuando es false, los cuerpos desinflados son rechazados. Por defecto es true.

limit

Se recomienda no configurar un límite muy alto y usar el valor por defecto siempre que sea posible. Permitir payloads más grandes aumenta el uso de memoria por los recursos necesarios para decodificación y transformaciones, y también puede provocar tiempos de respuesta más largos a medida que se procesan más datos. Por ‘muy alto’ nos referimos a valores por encima del por defecto, por ejemplo payloads de 5 MB o más ya pueden empezar a introducir estos riesgos. Con los límites por defecto, estos problemas no ocurren.

type

La opción type se usa para determinar qué tipo de medio analizará el middleware. Esta opción puede ser una cadena, un array de cadenas o una función. Si no es una función, la opción type se pasa directamente a la biblioteca type-is y puede ser un nombre de extensión (como bin), un tipo mime (como application/octet-stream), o un tipo mime con un comodín (como */* o application/*). Si es una función, la opción type se llama como fn(req) y la petición se analiza si devuelve un valor verdadero. Por defecto es application/octet-stream.

verify

bodyParser.text([options])

Devuelve un middleware que analiza todos los cuerpos como una cadena y solo examina las peticiones donde la cabecera Content-Type coincide con la opción type. Este analizador soporta la inflación automática de las codificaciones gzip, br (brotli) y deflate.

Una nueva cadena body que contiene los datos analizados se completa en el objeto de petición después del middleware (es decir, req.body). Esta será una cadena del cuerpo.

Opciones

La función text toma un objeto opcional options que puede contener cualquiera de las siguientes claves:

defaultCharset

Especifica el conjunto de caracteres por defecto para el contenido de texto si el charset no está especificado en la cabecera Content-Type de la petición. Por defecto es utf-8.

inflate

Cuando se establece en true, los cuerpos desinflados (comprimidos) serán inflados; cuando es false, los cuerpos desinflados son rechazados. Por defecto es true.

limit

Se recomienda no configurar un límite muy alto y usar el valor por defecto siempre que sea posible. Permitir payloads más grandes aumenta el uso de memoria por los recursos necesarios para decodificación y transformaciones, y también puede provocar tiempos de respuesta más largos a medida que se procesan más datos. Por ‘muy alto’ nos referimos a valores por encima del por defecto, por ejemplo payloads de 5 MB o más ya pueden empezar a introducir estos riesgos. Con los límites por defecto, estos problemas no ocurren.

type

La opción type se usa para determinar qué tipo de medio analizará el middleware. Esta opción puede ser una cadena, un array de cadenas o una función. Si no es una función, la opción type se pasa directamente a la biblioteca type-is y puede ser un nombre de extensión (como txt), un tipo mime (como text/plain), o un tipo mime con un comodín (como */* o text/*). Si es una función, la opción type se llama como fn(req) y la petición se analiza si devuelve un valor verdadero. Por defecto es text/plain.

verify

bodyParser.urlencoded([options])

Devuelve un middleware que solo analiza cuerpos urlencoded y solo examina las peticiones donde la cabecera Content-Type coincide con la opción type. Este analizador acepta solo las codificaciones UTF-8 e ISO-8859-1 del cuerpo y soporta la inflación automática de las codificaciones gzip, br (brotli) y deflate.

Un nuevo objeto body que contiene los datos analizados se completa en el objeto de petición después del middleware (es decir, req.body). Este objeto contendrá pares clave-valor, donde el valor puede ser una cadena o un array (cuando extended es false), o cualquier tipo (cuando extended es true).

Opciones

La función urlencoded toma un objeto opcional options que puede contener cualquiera de las siguientes claves:

extended

La sintaxis “extended” permite que objetos ricos y arrays sean codificados en el formato URL-encoded, permitiendo una experiencia similar a JSON con URL-encoded. Para más información, por favor consulta la biblioteca qs.

Por defecto es false.

inflate

Cuando se establece en true, los cuerpos desinflados (comprimidos) serán inflados; cuando es false, los cuerpos desinflados son rechazados. Por defecto es true.

limit

Se recomienda no configurar un límite muy alto y usar el valor por defecto siempre que sea posible. Permitir payloads más grandes aumenta el uso de memoria por los recursos necesarios para decodificación y transformaciones, y también puede provocar tiempos de respuesta más largos a medida que se procesan más datos. Por ‘muy alto’ nos referimos a valores por encima del por defecto, por ejemplo payloads de 5 MB o más ya pueden empezar a introducir estos riesgos. Con los límites por defecto, estos problemas no ocurren.

parameterLimit

La opción parameterLimit controla el número máximo de parámetros permitidos en los datos URL-encoded. Si una petición contiene más parámetros que este valor, se devolverá un 413 al cliente. Por defecto es 1000.

type

La opción type se usa para determinar qué tipo de medio analizará el middleware. Esta opción puede ser una cadena, un array de cadenas o una función. Si no es una función, la opción type se pasa directamente a la biblioteca type-is y puede ser un nombre de extensión (como urlencoded), un tipo mime (como application/x-www-form-urlencoded), o un tipo mime con un comodín (como */x-www-form-urlencoded). Si es una función, la opción type se llama como fn(req) y la petición se analiza si devuelve un valor verdadero. Por defecto es application/x-www-form-urlencoded.

verify

defaultCharset

El charset por defecto para analizar, si no se especifica en el content-type. Debe ser utf-8 o iso-8859-1. Por defecto es utf-8.

charsetSentinel

Si se permite que el valor del parámetro utf8 tome precedencia como selector de charset. Requiere que el formulario contenga un parámetro llamado utf8 con un valor de ✓. Por defecto es false.

interpretNumericEntities

Si se deben decodificar entidades numéricas como ☺ al analizar un formulario iso-8859-1. Por defecto es false.

depth

La opción depth se usa para configurar la profundidad máxima de la biblioteca qs cuando extended es true. Esto te permite limitar la cantidad de claves que se analizan y puede ser útil para prevenir ciertos tipos de abuso. Por defecto es 32. Se recomienda mantener este valor lo más bajo posible.

Errores

Los middlewares proporcionados por este módulo crean errores usando el módulo http-errors. Los errores típicamente tendrán una propiedad status/statusCode que contiene el código de respuesta HTTP sugerido, una propiedad expose para determinar si la propiedad message debe mostrarse al cliente, una propiedad type para determinar el tipo de error sin comparar contra message, y una propiedad body que contiene el cuerpo leído, si está disponible.

Los siguientes son los errores comunes creados, aunque cualquier error puede aparecer por diversas razones.

content encoding unsupported

Este error ocurrirá cuando la petición tenía una cabecera Content-Encoding que contenía una codificación pero la opción “inflation” estaba establecida en false. La propiedad status se establece en 415, la propiedad type se establece en 'encoding.unsupported', y la propiedad charset se establecerá en la codificación que no está soportada.

entity parse failed

Este error ocurrirá cuando la petición contenía una entidad que no pudo ser analizada por el middleware. La propiedad status se establece en 400, la propiedad type se establece en 'entity.parse.failed', y la propiedad body se establece en el valor de la entidad que falló al analizarse.

entity verify failed

Este error ocurrirá cuando la petición contenía una entidad que no pudo pasar la verificación por la opción verify definida. La propiedad status se establece en 403, la propiedad type se establece en 'entity.verify.failed', y la propiedad body se establece en el valor de la entidad que falló la verificación.

request aborted

Este error ocurrirá cuando la petición es abortada por el cliente antes de que la lectura del cuerpo haya terminado. La propiedad received se establecerá en el número de bytes recibidos antes de que la petición fuera abortada y la propiedad expected se establece en el número de bytes esperados. La propiedad status se establece en 400 y la propiedad type se establece en 'request.aborted'.

request entity too large

Este error ocurrirá cuando el tamaño del cuerpo de la petición es mayor que la opción “limit”. La propiedad limit se establecerá en el límite de bytes y la propiedad length se establecerá en la longitud del cuerpo de la petición. La propiedad status se establece en 413 y la propiedad type se establece en 'entity.too.large'.

request size did not match content length

Este error ocurrirá cuando la longitud de la petición no coincide con la longitud de la cabecera Content-Length. Esto típicamente ocurre cuando la petición está mal formada, habitualmente cuando la cabecera Content-Length fue calculada basándose en caracteres en vez de bytes. La propiedad status se establece en 400 y la propiedad type se establece en 'request.size.invalid'.

stream encoding should not be set

Este error ocurrirá cuando algo llamó al método req.setEncoding antes de este middleware. Este módulo opera directamente solo sobre bytes y no se puede llamar req.setEncoding cuando se usa este módulo. La propiedad status se establece en 500 y la propiedad type se establece en 'stream.encoding.set'.

stream is not readable

Este error ocurrirá cuando la petición ya no es legible cuando este middleware intenta leerla. Esto típicamente significa que algo distinto a un middleware de este módulo ya leyó el cuerpo de la petición y el middleware también fue configurado para leer la misma petición. La propiedad status se establece en 500 y la propiedad type se establece en 'stream.not.readable'.

too many parameters

Este error ocurrirá cuando el contenido de la petición excede el parameterLimit configurado para el analizador urlencoded. La propiedad status se establece en 413 y la propiedad type se establece en 'parameters.too.many'.

unsupported charset “BOGUS”

Este error ocurrirá cuando la petición tenía un parámetro charset en la cabecera Content-Type, pero el módulo iconv-lite no lo soporta O el analizador no lo soporta. El charset está contenido en el mensaje así como en la propiedad charset. La propiedad status se establece en 415, la propiedad type se establece en 'charset.unsupported', y la propiedad charset se establece en el charset que no está soportado.

unsupported content encoding “bogus”

Este error ocurrirá cuando la petición tenía una cabecera Content-Encoding que contenía una codificación no soportada. La codificación está contenida en el mensaje así como en la propiedad encoding. La propiedad status se establece en 415, la propiedad type se establece en 'encoding.unsupported', y la propiedad encoding se establece en la codificación que no está soportada.

La entrada excedió la profundidad

Este error ocurre cuando se usa bodyParser.urlencoded con la propiedad extended establecida en true y la entrada excede la opción depth configurada. La propiedad status se establece en 400. Se recomienda revisar la opción depth y evaluar si requiere un valor más alto. Cuando la opción depth se establece en 32 (valor por defecto), el error no se lanzará.

Ejemplos

Genérico de nivel superior Express/Connect

Este ejemplo demuestra cómo añadir un analizador JSON y URL-encoded genérico como middleware de nivel superior, el cual analizará los cuerpos de todas las peticiones entrantes. Esta es la configuración más simple.

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

// parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded());

// parse application/json
app.use(bodyParser.json());

app.use(function (req, res) {
  res.setHeader('Content-Type', 'text/plain');
  res.write('you posted:\n');
  res.end(String(JSON.stringify(req.body, null, 2)));
});

Específico de ruta Express

Este ejemplo demuestra cómo añadir analizadores de cuerpo específicamente a las rutas que los necesitan. En general, esta es la forma más recomendada de usar body-parser con Express.

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

// create application/json parser
const jsonParser = bodyParser.json();

// create application/x-www-form-urlencoded parser
const urlencodedParser = bodyParser.urlencoded();

// POST /login gets urlencoded bodies
app.post('/login', urlencodedParser, function (req, res) {
  if (!req.body || !req.body.username) res.sendStatus(400);
  res.send('welcome, ' + req.body.username);
});

// POST /api/users gets JSON bodies
app.post('/api/users', jsonParser, function (req, res) {
  if (!req.body) res.sendStatus(400);
  // create user in req.body
});

Cambiar el tipo aceptado para los analizadores

Todos los analizadores aceptan una opción type que te permite cambiar el Content-Type que el middleware analizará.

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

// parse various different custom JSON types as JSON
app.use(bodyParser.json({ type: 'application/*+json' }));

// parse some custom thing into a Buffer
app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }));

// parse an HTML body into a string
app.use(bodyParser.text({ type: 'text/html' }));

Licencia

MIT