一个全功能的koa body解析器中间件。支持multipart, urlencoded 和 json 格式的请求体。提供与Express - multer 的bodyParser相同的功能。
安装
npm install koa-body
特性
- 能处理如下请求
- multipart/form-data
- application/x-www-form-urlencoded
- application/json
- application/json-patch+json
- application/vnd.api+json
- application/csp-report
- text/xml
- 对Node或Koa进行合并配置
- 文件上传
- 对报文主体body、报文字段fileds和文件大小限制
快速开始
npm install koa koa-body # 注意,Koa需要Node.js 7.6.0+来支持async/await
index.js
const Koa = require('koa');
const { koaBody } = require('koa-body');
const app = new Koa();
app.use(koaBody());
app.use((ctx) => {
ctx.body = `Request Body: ${JSON.stringify(ctx.request.body)}`;
});
app.listen(3000);
node index.js
curl -i http://localhost:3000/users -d "name=test"
输出:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 29
Date: Wed, 03 May 2017 02:09:44 GMT
Connection: keep-alive
Request Body: {"name":"test"}%
与koa-router一起使用
通常情况下,最好只在需要时解析body主体,如果使用支持中间件组合的路由器,我们可以只为某些路由注入报文主体body。
const Koa = require('koa');
const app = new Koa();
const router = require('koa-router')();
const { koaBody } = require('koa-body');
router.post('/users', koaBody(), (ctx) => {
console.log(ctx.request.body);
// => POST body
ctx.body = JSON.stringify(ctx.request.body);
});
app.use(router.routes());
app.listen(3000);
console.log('curl -i http://localhost:3000/users -d "name=test"');
与不支持文本body的类型一起使用
对于不支持文本报文主体body的类型,例如text/xml,您可以在ctx.request.body
中使用未解析的请求主体。对于文本内容类型,不需要includeUnparsed
设置。
// xml-parse.js:
const Koa = require('koa');
const { koaBody } = require('koa-body');
const convert = require('xml-js');
const app = new Koa();
app.use(koaBody());
app.use((ctx) => {
const obj = convert.xml2js(ctx.request.body);
ctx.body = `Request Body: ${JSON.stringify(obj)}`;
});
app.listen(3000);
node xml-parse.js
curl -i http://localhost:3000/users -H "Content-Type: text/xml" -d '<?xml version="1.0"?><catalog id="1"></catalog>'
输出:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 135
Date: Tue, 09 Jun 2020 11:17:38 GMT
Connection: keep-alive
Request Body: {"declaration":{"attributes":{"version":"1.0"}},"elements":[{"type":"element","name":"catalog","attributes":{"id":"1"}}]}%
配置项
可选的koa-body。四种自定义选项,其他的来自于raw-body 和 formidable。
- patchNode 【Boolean】将请求体(request body)合并到Node的
ctx.req
,默认false。 - patchKoa 【Boolean】将请求体(request body)合并到Koa的
ctx.request
,默认false。 - jsonLimit 【String | Int】JSON类型请求体body(request body)的字节限制,默认1mb(如果是Int类型则表示字节数,即b)。
- formLimit 【String | Int】表单(form)类型请求体body(request body)的字节限制,默认56kb(如果是Int类型则表示字节数,即b)。
- textLimit 【String | Int】文本(text)类型请求体body(request body)的字节限制,默认56kb(如果是Int类型则表示字节数,即b)。
- encoding 【String】设置请求体body的编码,默认为utf-8。
- multipart 【Boolean】解析多部分主体(multipart bodies),默认为false。(译者注:上传文件时设置为true)
- urlencoded 【Boolean】解析url编码体(urlencoded bodies ),默认为true。(译者注:GET请求)
- text【Boolean】解析文本主体(text bodies),比如XML,默认为true。
- json【Boolean】解析JSON主体(JSON bodies),默认为true。
- jsonStrict【Boolean】切换co-body的严格模式,如果设置为true -只解析数组或对象,默认为true。
- includeUnparsed【Boolean】切换co-body的
returnRawBody
配置项;如果设置为true,当编码表单和JSON请求原始的,未解析的请求体将使用Symbol(参见详细信息)附加到ctx.request.body
,默认为false。 - formidable【Object】传递给多部分解析器的配置项。(参见详细信息)
- onError 【Function】自定义错误处理函数。如果抛出错误,可以自定义响应。函数结构为
onError(error, context)
,默认抛出错误。 - parsedMethods 【String[]】 声明将解析报文主体的HTTP方法,默认[‘POST’, ‘PUT’, ‘PATCH’]
关于parsedMethods
参见http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.3
- GET、HEAD和DELETE请求没有定义请求体的语义,但这并不意味着它们在某些使用场景中无效。
- 缺省情况下,koa-body是严格的,只解析POST、PUT和PATCH请求
- 您可以使用枚举或字符串数组来设置该字段,例如,
HttpMethodEnum.PATCH
文件支持
上传的文件可以通过ctx.request.files
访问。
关于未解析请求体的说明
一些应用程序需要对请求体进行加密验证,例如来自slack或stripe的webhook。如果koa-body的选项中includeUnparsed为true,则可以访问未解析的body。启用后,从unparsed = require('koa-body/unparsed.js')
中导入用于访问请求主体的symbol,或者使用unparsed = symbol .for('unparsedBody')
定义您自己的访问器。然后使用ctx.request.body[unparsed]
获取未解析的正文。
formidable字段的部分配置项
formidable的全部配置项请参看 node-formidable
- maxFields 【Int】限制querystring解析器解码的字段数(url查询字段),默认为1000。
- maxFieldsSize 【Int】 限制所有字段(文件除外)所占用的总内存量,单位为字节。如果超过此值,则触发’error’事件,默认为2mb (2 * 1024 * 1024)
- uploadDir 【String】 设置用于上传文件的目录,默认为Node.js的
os.tmpDir()
。 - keepExtensions 【Boolean】 写入
uploadDir
的文件将保留原始文件的扩展名,默认为false。 - hashAlgorithm 【String】 如果你想为传入文件计算总和,将其设置为’sha1’或’md5’,默认为false。
- multiples 【Boolean】 是否支持多文件上传,默认true。
- onFileBegin 【Function】 文件开始上传之前的自定义回调函数。此函数由node-formidable直接调用。文件在存储到磁盘前将被重命名。查看文档。