npm koa-body

一个全功能的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直接调用。文件在存储到磁盘前将被重命名。查看文档。