@zenweb/body

@zenweb/body - 请求内容解析

zenweb 模块 - 解析 HTTP POST 请求内容（JSON、表单、文本、二进制等）

安装

npm install @zenweb/body

快速开始

import { Context, Post, Body, ObjectBody, BodyHelper, $body } from 'zenweb';

export class Controller {
  // 直接获取解析后的数据
  @Post()
  post(body: Body) {
    console.log(body.type); // 内容类型，如 'json'
    console.log(body.data); // 解析后的数据
  }

  // 获取对象形式的数据
  @Post()
  form(obj: ObjectBody) {
    console.log(obj.name, obj.age);
  }

  // 类型转换与校验
  @Post()
  async validate(helper: BodyHelper) {
    const { name, age } = await helper.get({
      name: 'string',    // 字符串类型
      age: '!int',       // 必填，整数类型
    });
  }
}

// 在非注入上下文中使用
async function outsideDI() {
  const data = await $body.data();
  const { name } = await $body.get({ name: 'string' });
}

解析流程

• RawBody - 读取原始数据流，处理 gzip/deflate 解压
• TextBody - 按字符集编码转换为文本（如 UTF-8、GBK）
• Body - 根据 Content-Type 选择解析器，返回解析结果
• ObjectBody - 将 Body.data 转为对象形式（仅 JSON/表单）

可注入对象

对象	作用域	说明
RawBody	request	原始 Buffer，已解压
TextBody	request	解码后的文本字符串
Body	request	解析后的数据，含 type、parser 属性
ObjectBody	request	对象形式，仅支持 JSON 和表单
BodyHelper	request	类型转换与校验，继承 @zenweb/helper

全局函数

在非注入上下文中通过 AsyncLocalStorage 访问：

await $getRawBody()    // Buffer | undefined
await $getTextBody()   // string | undefined
await $getObjectBody() // ObjectBody 实例
$body                  // BodyHelper 代理

配置项

配置项	类型	默认值	说明
encoding	string	'utf-8'	默认字符集编码
limit	number	1048576	内容大小限制 (bytes)，默认 1MB
inflate	boolean	true	支持 gzip/deflate 压缩传输
textTypes	string[]	['text/*', 'xml', '+xml']	文本类型匹配规则
parses	BodyParserClass[]	[JSONParser, URLEncodedParser]	解析器列表

自定义解析器

import { Injectable } from '@zenweb/inject';
import body, { TextBodyParser, JSONParser, URLEncodedParser } from '@zenweb/body';

@Injectable('singleton')
export class XMLParser extends TextBodyParser {
  objected = false;              // 不能转为 ObjectBody
  types = ['xml', '+xml'];       // 匹配的 Content-Type

  parse(text: string) {
    return parseXML(text);       // 自定义解析逻辑
  }
}

// 注册
$initCore().setup(body({
  parses: [JSONParser, URLEncodedParser, XMLParser]
}));

指定解析器

强制使用特定解析器处理请求：

import { useBodyParser, JSONParser } from '@zenweb/body';

router.post('/api', useBodyParser(JSONParser), handler);

错误类型

模块抛出 http-errors，包含 type 字段：

状态码	type	说明
400	json.parse-error	JSON 解析失败
400	decode.failed	编码转换失败
400	objected.only	非 JSON/表单格式转 ObjectBody
413	entity.too.large	超过大小限制
415	json.strict	JSON 必须是对象或数组
415	charset.unsupported	不支持的字符集

扩展模块

• @zenweb/xml-body - XML 格式解析