以下是一个 body-parser 的常用使用案例。
const express = require('express')
const bodyParser = require('body-parser')
const app = express()
// parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded({ extended: false }))
// 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(JSON.stringify(req.body, null, 2))
})
以上代码设置的含义是:项目中所有 Content-Type 是 "application/x-www-form-urlencoded" 或 "application/json" 请求数据都会经过 body-parser 中间件的处理,并设置到 req.body 属性上。
下面就来详细介绍 body-parser 的安装和使用。
安装
$ npm install body-parser
使用也比较简单。
const bodyParser = require('body-parser')
我们是通过调用 bodyParser 对象的方法来获取不同 Content-Type 的数据处理能力的。下面就来介绍。
API
bodyParser 上一共提供了 4 个方法来使用,分别对应 4 种不同类型的请求体数据。
- bodyParser.json([options])
- bodyParser.urlencoded([options])
- bodyParser.text([options])
- bodyParser.raw([options])
其中前 2 种是我们最常使用的。接下来分别介绍。
bodyParser.json([options])
返回能解析 json 数据的中间件,默认匹配 Content-Type 值为 "application/json"(可以通过 options.type 进行控制)。接受任何 Unicode 编码的请求体数据,而且还支持 gzip 和 deflate 压缩算法的自动解压。
解析好的请求体数据会放在 req.body 属性上,无请求体数据则返回一个空对象({})。
Options 选项
这是一个可选参数,不传入则使用默认选项。其他 3 个方法与此类似,在此讲 1 遍后,如果没有特殊情况,后面就不再赘述了。
- type:默认值是 "application/json",表示这个中间件默认匹配的 Content-Type 是 "application/json",这个字段除了接收字符串,还支持接收对象和数组。你也可以自定义,比如设置成 "*/json"(内部是使用 type-is[1] 做匹配的)
- inflate:是否开启自动解压请求体数据的能力,默认为 true(目前支持 支持 gzip 和 deflate 2 中压缩算法)
- limit:控制最大请求正文大小,否则报错。默认值是 '100kb'(内部传递给 bytes[2] 库将其解析成字节数进行判断处理)
- reviver:body-parser 内部默认使用 JSON.parse() 方法将字符串格式化成对象设置到 req.body 上。这个参数就是传递给 JSON.parse() 方法的第 2 个参数,用来自定义解析行为。搞不清楚的同学可以看一下 MDN 上 JSON.parse() 的使用文档[3]
- strict:默认为 true,用来控制内部 JSON.parse() 所接收的字符串是否只能是对象和数组。设置成 false 时表示可以接受任意类型的字符串数据
bodyParser.urlencoded([options])
默认处理 Content-Type 值为 "application/x-www-form-urlencoded" 的请求体数据。
.urlencoded() 中间件还提供了一个布尔参数 urlencoded,用来决定使用哪一个查询解析库来处理请求参数。
- urlencoded为 false 时,内部使用 querystring 库解析
- urlencoded为 true 时,内部使用 qs 库解析
qs 与 querystring 的区别在于:querystring 只能解析简单 key-value 对,qs 则支持嵌套对象的 key-value 对的解析,后者功能会更加强大。
Options 选项
- urlencoded:以上已介绍过。默认为 true(即使用 qs 解析参数),不过已被弃。官方推荐显式传入一个值,这就需要你了解 qs 和 querystring 之间的区别
- parameterLimit:控制 URL 编码数据中允许的最大参数数量,默认是 1000。多于这个值,会向客户端返回 413 响应码
bodyParser.text([options])
默认处理 Content-Type 值为 "text/plain" 的请求体数据。
Options 选项
- defaultCharset:如果请求头中的 Content-Type 头中没有指定字符集,则使用这个字段所指定的文本内容的默认字符集。默认为 "utf-8"。
bodyParser.raw([options])
默认处理 Content-Type 值为 "application/octet-stream" 的请求体数据。
不支持 multipart/form-data
body-parser 并不支持处理 Content-Type 是 "multipart/form-data" 的请求体数据。如果你有这方面的需求,可以参照下面的库进行选择。
- busboy[4] 和 connect-busboy[5]
- multiparty[6] 和 connect-multiparty[7]
- formidable[8]
- multer[9]
express 已内置 body-parser
express 从 v4.17.0 开始[10],已全面内置了 body-parser 功能,你直接可以通过 express().json() / express().raw()/express().text()/ express().urlencoded() 4 个 API。
在内部,这 4 方法其实是 body-parser 借着 express 暴露出来[11]的。也就是说项目中你无需安装 body-parser 依赖了。
const bodyParser = require('body-parser')
exports.json = bodyParser.json
exports.query = require('./middleware/query');
exports.raw = bodyParser.raw
exports.text = bodyParser.text
exports.urlencoded = bodyParser.urlencoded
总结
本文介绍了 Express 中用于解析请求体数据的中间件 body-parser。 其实 Express 在 v4.17.0 中已完整内置了 body-parser 的能力,你可以通过 express() 上的 .json()/.urlencoded()/.text()/.raw() 方法访问到。
就介绍到这里了,希望本文对你有所帮助,感谢阅读,再见。
参考资料
[1]type-is: https://www.npmjs.org/package/type-is#readme
[2]bytes: https://www.npmjs.com/package/bytes
[3]MDN 上 JSON.parse() 的使用文档: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter
[4]busboy: https://www.npmjs.org/package/busboy#readme
[5]connect-busboy: https://www.npmjs.org/package/connect-busboy#readme
[6]multiparty: https://www.npmjs.org/package/multiparty#readme
[7]connect-multiparty: https://www.npmjs.org/package/connect-multiparty#readme
[8]formidable: https://www.npmjs.org/package/formidable#readme
[9]multer: https://www.npmjs.org/package/multer#readme
[10]从 v4.17.0 开始: https://expressjs.com/en/4x/api.html#express.json
[11]body-parser 借着 express 暴露出来: https://github.com/expressjs/express/blob/4.18.2/lib/express.js#L78