koa-body 使用指南与技术文档

koa-body 是一个功能全面的 Koa 中间件，专为处理诸如 multipart/form-data, application/x-www-form-urlencoded, 和 application/json 等请求体设计，其功能与 Express 的中间件 multer 类似。

安装指南

要安装 koa-body，只需通过 npm 运行以下命令：

npm install koa-body

确保您的 Node.js 版本在 7.6.0 或更高版本，因为 Koa 需要支持 async/await。

项目使用说明

快速启动

首先，安装所需的依赖：

npm install koa koa-body

接着，在你的应用中使用 koa-body：

const Koa = require('koa');
const { koaBody } = require('koa-body');
const app = new Koa();

app.use(koaBody());
app.use(async ctx => {
  ctx.body = `请求体: ${JSON.stringify(ctx.request.body)}`;
});

app.listen(3000);

你可以通过发送 POST 请求测试它，例如使用 curl：

curl -i http://localhost:3000/users -d "name=test"

与 koa-router 结合使用

为了更精细地控制何时解析请求体，可以将其与 koa-router 搭配使用：

const Koa = require('koa');
const router = require('koa-router')();
const { koaBody } = require('koa-body');

router.post('/users', koaBody(), async ctx => {
  ctx.body = JSON.stringify(ctx.request.body);
});

const app = new Koa();
app.use(router.routes());

app.listen(3000);

处理非标准文本体类型（如 XML）

对于像 XML 这样的不受支持的文本类型，可以直接访问 ctx.request.body，无需特别配置：

const Koa = require('koa');
const { koaBody } = require('koa-body');
const convert = require('xml-js'); // 假定已安装 xml-js 库

const app = new Koa();

app.use(koaBody());
app.use(async ctx => {
  const obj = convert.xml2js(ctx.request.body);
  ctx.body = `请求体: ${JSON.stringify(obj)}`;
});

app.listen(3000);

API 使用文档

koa-body 提供了多种可自定义的选项来满足不同的需求，主要包括但不限于：

• patchNode: 是否将请求体挂载到 Node.js 的原生 req 对象，默认为 false。
• patchKoa: 是否将请求体挂载到 Koa 的请求对象，默认为 true。
• jsonLimit: JSON 请求体的最大字节限制，默认是 '1mb'。
• formLimit: 表单请求体的最大字节限制，默认是 '56kb'。
• multipart: 是否启用解析多部分表单数据，默认为 false。
• urlencoded: 是否解析 URL 编码的请求，默认为 true。
• text: 是否解析文本类型的请求，默认为 true。
• options 还包含更多从 raw-body 和 formidable 继承过来的设置。

文件上传支持

上传的文件可以通过 ctx.request.files 访问。

注意事项

当需要访问未解析的原始请求体时，例如为了签名验证，可以开启 includeUnparsed 选项，并使用特定的符号或自定义访问器来获取原始内容。

通过以上内容，开发者应能够了解并高效利用 koa-body 来处理各种类型的请求体，提升基于 Koa 的应用程序的灵活性和功能性。记得查阅官方文档以获取最新信息和详细配置。