body-parser

Node.js 请求体解析中间件。

在你的处理器（handlers）之前，此中间件会解析传入的请求体，并将其放在 req.body 属性下。

注意 由于 req.body 的结构基于用户控制的输入，此对象中的所有属性和值均不可信，在使用前应进行验证。例如，req.body.foo.toString() 可能会以多种方式失败，比如 foo 属性可能不存在或不是字符串，并且 toString 可能不是函数，而是一个字符串或其他用户输入。

了解 Node.js 中 HTTP 事务的剖析.

此模块不处理 multipart 请求体，因为它们复杂且通常较大。对于 multipart 请求体，你可能对以下模块感兴趣：

• busboy 和 connect-busboy
• multiparty 和 connect-multiparty
• formidable
• multer

此模块提供以下解析器：

• JSON 请求体解析器
• 原始请求体解析器
• 文本请求体解析器
• URL 编码表单请求体解析器

你可能感兴趣的其他请求体解析器：

• body
• co-body

安装

$ npm install body-parser

API

const bodyParser = require('body-parser')

The bodyParser 对象公开了各种工厂函数来创建中间件。当请求的 Content-Type 头部与 type 选项匹配时，所有中间件都会使用解析后的请求体填充 req.body 属性。

此模块返回的各种错误在错误部分有描述。

bodyParser.json([options])

返回一个中间件，它只解析 json 并只处理 Content-Type 头部与 type 选项匹配的请求。此解析器接受任何 Unicode 编码的请求体，并支持自动解压 gzip、br (brotli) 和 deflate 编码。

中间件处理后，一个包含解析数据的新的 body 对象（即 req.body）会被填充到 request 对象上。

选项

json 函数接受一个可选的 options 对象，该对象可能包含以下任意键：

inflate

当设置为 true 时，被解压（压缩）的请求体将被解压；当设置为 false 时，被解压的请求体将被拒绝。默认为 true。

limit

控制最大请求体大小。如果这是一个数字，则该值指定字节数；如果是一个字符串，该值将被传递给 bytes 库进行解析。默认为 '100kb'。

reviver

reviver 选项会直接作为第二个参数传递给 JSON.parse。你可以在 MDN 关于 JSON.parse 的文档中找到更多关于此参数的信息。

strict

当设置为 true 时，只接受数组和对象；当设置为 false 时，接受任何 JSON.parse 可接受的值。默认为 true。

type

type 选项用于确定中间件将解析的媒体类型。此选项可以是字符串、字符串数组或函数。如果不是函数，type 选项会直接传递给 type-is 库，它可以是扩展名（如 json）、MIME 类型（如 application/json），或带有通配符的 MIME 类型（如 */* 或 */json）。如果是一个函数，type 选项将作为 fn(req) 被调用，如果返回真值，则解析请求。默认为 application/json。

verify

如果提供了 verify 选项，它将作为 verify(req, res, buf, encoding) 被调用，其中 buf 是原始请求体的 Buffer，encoding 是请求的编码。可以通过抛出错误来中止解析。

bodyParser.raw([options])

返回一个中间件，它将所有请求体解析为 Buffer，并且只处理 Content-Type 头部与 type 选项匹配的请求。此解析器支持自动解压 gzip、br (brotli) 和 deflate 编码。

中间件处理后，一个包含解析数据的新 body 对象（即 req.body）会被填充到 request 对象上。这将是一个表示请求体的 Buffer 对象。

选项

raw 函数接受一个可选的 options 对象，该对象可能包含以下任意键：

inflate

当设置为 true 时，被解压（压缩）的请求体将被解压；当设置为 false 时，被解压的请求体将被拒绝。默认为 true。

limit

控制最大请求体大小。如果这是一个数字，则该值指定字节数；如果是一个字符串，该值将被传递给 bytes 库进行解析。默认为 '100kb'。

type

type 选项用于确定中间件将解析的媒体类型。此选项可以是字符串、字符串数组或函数。如果不是函数，type 选项会直接传递给 type-is 库，它可以是扩展名（如 bin）、MIME 类型（如 application/octet-stream），或带有通配符的 MIME 类型（如 */* 或 application/*）。如果是一个函数，type 选项将作为 fn(req) 被调用，如果返回真值，则解析请求。默认为 application/octet-stream。

verify

如果提供了 verify 选项，它将作为 verify(req, res, buf, encoding) 被调用，其中 buf 是原始请求体的 Buffer，encoding 是请求的编码。可以通过抛出错误来中止解析。

bodyParser.text([options])

返回一个中间件，它将所有请求体解析为字符串，并且只处理 Content-Type 头部与 type 选项匹配的请求。此解析器支持自动解压 gzip、br (brotli) 和 deflate 编码。

中间件处理后，一个包含解析数据的新 body 字符串（即 req.body）会被填充到 request 对象上。这将是一个表示请求体的字符串。

选项

text 函数接受一个可选的 options 对象，该对象可能包含以下任意键：

defaultCharset

如果请求的 Content-Type 头部中未指定字符集，则指定文本内容的默认字符集。默认为 utf-8。

inflate

当设置为 true 时，被解压（压缩）的请求体将被解压；当设置为 false 时，被解压的请求体将被拒绝。默认为 true。

limit

控制最大请求体大小。如果这是一个数字，则该值指定字节数；如果是一个字符串，该值将被传递给 bytes 库进行解析。默认为 '100kb'。

type

type 选项用于确定中间件将解析的媒体类型。此选项可以是字符串、字符串数组或函数。如果不是函数，type 选项会直接传递给 type-is 库，它可以是扩展名（如 txt）、MIME 类型（如 text/plain），或带有通配符的 MIME 类型（如 */* 或 text/*）。如果是一个函数，type 选项将作为 fn(req) 被调用，如果返回真值，则解析请求。默认为 text/plain。

verify

如果提供了 verify 选项，它将作为 verify(req, res, buf, encoding) 被调用，其中 buf 是原始请求体的 Buffer，encoding 是请求的编码。可以通过抛出错误来中止解析。

bodyParser.urlencoded([options])

返回一个中间件，它只解析 urlencoded 请求体，并且只处理 Content-Type 头部与 type 选项匹配的请求。此解析器只接受 UTF-8 编码的请求体，并支持自动解压 gzip、br (brotli) 和 deflate 编码。

中间件处理后，一个包含解析数据的新 body 对象（即 req.body）会被填充到 request 对象上。此对象将包含键值对，其中值可以是字符串或数组（当 extended 为 false 时），或任何类型（当 extended 为 true 时）。

选项

urlencoded 函数接受一个可选的 options 对象，该对象可能包含以下任意键：

extended

“extended” 语法允许将丰富的对象和数组编码为 URL 编码格式，从而在使用 URL 编码时获得类似 JSON 的体验。欲了解更多信息，请参阅 qs 库。

默认为 false。

inflate

当设置为 true 时，被解压（压缩）的请求体将被解压；当设置为 false 时，被解压的请求体将被拒绝。默认为 true。

limit

控制最大请求体大小。如果这是一个数字，则该值指定字节数；如果是一个字符串，该值将被传递给 bytes 库进行解析。默认为 '100kb'。

parameterLimit

parameterLimit 选项控制 URL 编码数据中允许的最大参数数量。如果请求包含的参数超过此值，客户端将收到 413 错误。默认为 1000。

type

type 选项用于确定中间件将解析的媒体类型。此选项可以是字符串、字符串数组或函数。如果不是函数，type 选项会直接传递给 type-is 库，它可以是扩展名（如 urlencoded）、MIME 类型（如 application/x-www-form-urlencoded），或带有通配符的 MIME 类型（如 */x-www-form-urlencoded）。如果是一个函数，type 选项将作为 fn(req) 被调用，如果返回真值，则解析请求。默认为 application/x-www-form-urlencoded。

verify

如果提供了 verify 选项，它将作为 verify(req, res, buf, encoding) 被调用，其中 buf 是原始请求体的 Buffer，encoding 是请求的编码。可以通过抛出错误来中止解析。

defaultCharset

如果内容类型中未指定字符集，则作为解析的默认字符集。必须是 utf-8 或 iso-8859-1。默认为 utf-8。

charsetSentinel

是否让 utf8 参数的值作为字符集选择器优先。它要求表单包含一个名为 utf8 且值为 ✓ 的参数。默认为 false。

interpretNumericEntities

在解析 iso-8859-1 表单时是否解码 ☺ 等数字实体。默认为 false。

depth

depth 选项用于在 extended 为 true 时配置 qs 库的最大深度。这允许你限制被解析的键的数量，有助于防止某些类型的滥用。默认为 32。建议将此值保持尽可能低。

错误

此模块提供的中间件使用 http-errors 模块创建错误。这些错误通常会有一个 status/statusCode 属性，包含建议的 HTTP 响应代码；一个 expose 属性，用于确定 message 属性是否应显示给客户端；一个 type 属性，用于在不匹配 message 的情况下确定错误类型；以及一个 body 属性，如果可用，其中包含已读取的请求体。

以下是常见的错误，尽管由于各种原因也可能出现其他错误。

不支持的内容编码

当请求的 Content-Encoding 头部包含编码但“解压”选项设置为 false 时，将发生此错误。status 属性设置为 415，type 属性设置为 'encoding.unsupported'，charset 属性将设置为不受支持的编码。

实体解析失败

当请求包含中间件无法解析的实体时，将发生此错误。status 属性设置为 400，type 属性设置为 'entity.parse.failed'，body 属性设置为解析失败的实体值。

实体验证失败

当请求包含的实体未能通过定义的 verify 选项的验证时，将发生此错误。status 属性设置为 403，type 属性设置为 'entity.verify.failed'，body 属性设置为验证失败的实体值。

请求已中止

当客户端在读取请求体完成之前中止请求时，将发生此错误。received 属性将设置为请求中止前已接收的字节数，expected 属性设置为预期的字节数。status 属性设置为 400，type 属性设置为 'request.aborted'。

请求实体过大

当请求体大小大于“limit”选项时，将发生此错误。limit 属性将设置为字节限制，length 属性将设置为请求体的长度。status 属性设置为 413，type 属性设置为 'entity.too.large'。

请求大小与内容长度不匹配

当请求的长度与 Content-Length 头部中的长度不匹配时，将发生此错误。这通常发生在请求格式错误时，特别是当 Content-Length 头部是根据字符而不是字节计算时。status 属性设置为 400，type 属性设置为 'request.size.invalid'。

不应设置流编码

当在此中间件之前有代码调用了 req.setEncoding 方法时，将发生此错误。此模块直接处理字节，使用此模块时不能调用 req.setEncoding。status 属性设置为 500，type 属性设置为 'stream.encoding.set'。

流不可读

当此中间件尝试读取请求时，请求不再可读时，将发生此错误。这通常意味着此模块之外的其他中间件已经读取了请求体，并且此中间件也被配置为读取相同的请求。status 属性设置为 500，type 属性设置为 'stream.not.readable'。

参数过多

当请求内容超出 urlencoded 解析器配置的 parameterLimit 时，将发生此错误。status 属性设置为 413，type 属性设置为 'parameters.too.many'。

不支持的字符集 “BOGUS”

当请求的 Content-Type 头部包含字符集参数，但 iconv-lite 模块或解析器不支持它时，将发生此错误。字符集包含在消息中以及 charset 属性中。status 属性设置为 415，type 属性设置为 'charset.unsupported'，charset 属性设置为不受支持的字符集。

不支持的内容编码 “bogus”

当请求的 Content-Encoding 头部包含不支持的编码时，将发生此错误。编码包含在消息中以及 encoding 属性中。status 属性设置为 415，type 属性设置为 'encoding.unsupported'，encoding 属性设置为不受支持的编码。

输入超出深度限制

当使用 bodyParser.urlencoded 且 extended 属性设置为 true，并且输入超出配置的 depth 选项时，将发生此错误。status 属性设置为 400。建议检查 depth 选项并评估是否需要更高的值。当 depth 选项设置为 32（默认值）时，不会抛出此错误。

示例

Express/Connect 顶层通用

此示例演示了将通用 JSON 和 URL 编码解析器添加为顶层中间件，它将解析所有传入请求的请求体。这是最简单的设置。

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)))
})

Express 路由专用

此示例演示了将请求体解析器专门添加到需要它们的路由。通常，这是在 Express 中使用 body-parser 最推荐的方式。

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
})

更改解析器接受的类型

所有解析器都接受一个 type 选项，它允许你更改中间件将解析的 Content-Type。

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' }))

许可证

MIT