@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' });
}

解析流程

1. RawBody - 读取原始数据流，处理 gzip/deflate 解压
2. TextBody - 按字符集编码转换为文本（如 UTF-8、GBK）
3. Body - 根据 Content-Type 选择解析器，返回解析结果
4. 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 格式解析