@bigworm/bigworm-envelope

前后端统一数据交互协议库，TypeScript/JavaScript 实现，与后端 Java bigworm-envelope 数据结构完全对齐。零运行时依赖，提供 ESM / CJS / UMD 三种构建格式。

安装

npm install @bigworm/bigworm-envelope

数据结构

Envelope（报文容器）
  ├── header: EnvelopeHeader  extends Map<string, Entity>
  └── body:   EnvelopeBody    extends Map<string, Entity>

Entity（业务实体节点）
  ├── data: Data              extends Map<string, any>
  └── dataSets: Map<string, DataSet>

DataSet（数据集，Array-like）
  └── Data[]

| 类 | 继承 | 职责 | |---|---|---| | Envelope | — | 报文容器，包含 header 和 body | | EnvelopeHeader | Map<string, Entity> | 报文头，存储元数据（状态码、消息、token 等） | | EnvelopeBody | Map<string, Entity> | 报文体，存储业务数据 | | Entity | — | 业务对象节点，包含属性（Data）和子表（DataSet） | | Data | Map<string, any> | 键值对容器，提供强类型读写方法 | | DataSet | Array-like | 多行数据集合 |

快速开始

import { Envelope } from '@bigworm/bigworm-envelope'

const envelope = new Envelope()

// 设置 header
envelope.header().entity().data()
  .setStringItem('success', 'true')
  .setStringItem('message', '操作成功')

// 设置 body（属性 + 子表）
envelope.body().entity().data()
  .setStringItem('userId', '10001')
  .setStringItem('userName', '张三')
  .setIntegerItem('age', 25)

// 子表
const orders = new DataSet()
orders.fromJSON([
  { orderId: 'ORD001', amount: '999.99' },
  { orderId: 'ORD002', amount: '199.00' }
])
envelope.body().entity().setDataSet('orders', orders)

// 序列化
console.log(envelope.toPrettyJsonString())

输出：

{
  "header": {
    "default": { "success": "true", "message": "操作成功" }
  },
  "body": {
    "default": {
      "userId": "10001",
      "userName": "张三",
      "age": 25,
      "orders": [
        { "orderId": "ORD001", "amount": "999.99" },
        { "orderId": "ORD002", "amount": "199.00" }
      ]
    }
  }
}

API 详解

Envelope

| 方法 | 说明 | |------|------| | header() | 获取报文头（链式调用，不存在则自动创建） | | body() | 获取报文体（链式调用） | | getHeader() / getBody() | 传统 getter | | setHeader(h) / setBody(b) | 传统 setter，返回 this | | toJSON() | 转为 JS 对象（供 JSON.stringify 使用） | | fromJSON(obj) | 从 JS 对象填充，返回 this | | toJsonString() | 序列化为紧凑 JSON 字符串 | | toPrettyJsonString() | 序列化为格式化 JSON 字符串（调试用） | | toString() | 同 toPrettyJsonString() | | fromJsonString(str) | 从 JSON 字符串填充，返回 this |

EnvelopeHeader / EnvelopeBody

两者 API 完全对称：

| 方法 | 说明 | |------|------| | entity() | 获取默认节点（节点名 "default"，不存在时自动创建） | | entity(name) | 获取指定名称节点（不存在时自动创建） | | getEntity(name) | 获取指定节点（不存在返回 undefined） | | setEntity(name, entity) | 设置节点，返回 this | | toJSON() / fromJSON(obj) | 序列化 / 反序列化 |

Entity

| 方法 | 说明 | |------|------| | data() | 获取属性数据（链式） | | getData() | 获取属性数据（传统） | | setData(data) | 设置属性数据，返回 this | | setDataSet(name, dataset) | 设置子表，返回 this | | getDataSet(name) | 获取子表，不存在返回 null | | getDataSetNames() | 获取所有子表名称 string[] | | hasDataSet(name) | 判断子表是否存在 | | toJSON() / fromJSON(obj) | 序列化（属性和子表扁平化） / 反序列化 | | toJsonString() / fromJsonString(str) | JSON 字符串序列化 / 反序列化 |

Data（属性读写）

所有 set*Item 方法均返回 this，支持链式调用。

写入：

| 方法 | 说明 | |------|------| | setStringItem(key, value) | 写字符串 | | setIntegerItem(key, value) | 写整数 | | setFloatItem(key, value) | 写浮点数 | | setNumberItem(key, value) | 同 setFloatItem（别名） | | setBooleanItem(key, value) | 写布尔值 | | setItem(key, value) | 写任意值 | | setDateItem(key, value) | 写日期（格式 YYYYMMDD） | | setDateTimeItem(key, value) | 写日期时间（格式 YYYYMMDDHHMMSS） |

读取（含自动类型转换，转换失败返回默认值而非抛出异常）：

| 方法 | 返回类型 | 说明 | |------|---------|------| | getStringItem(key) | string | 不存在返回 "" | | getIntegerItem(key) | number | 自动转 Integer | | getFloatItem(key) | number | 自动转 Float | | getNumberItem(key) | number | 同 getFloatItem | | getBooleanItem(key) | boolean | true/yes/1 → true | | getItem(key) | any | 原始值 | | getDateItem(key) | Date \| null | 格式 YYYYMMDD | | getDateTimeItem(key) | Date \| null | 格式 YYYYMMDDHHMMSS |

Map 工具方法：

| 方法 | 说明 | |------|------| | isEmpty() | 是否为空 | | containsKey(key) | 是否包含指定 key | | containsValue(value) | 是否包含指定 value | | keys() | 返回所有 key 数组 | | values() | 返回所有 value 数组 | | element(index) | 按索引获取 {key, value} | | elements | 所有条目的 {key, value}[] | | toJSON() / fromJSON(obj) | 序列化 / 反序列化 | | toJsonString() / fromJsonString(str) | JSON 字符串序列化 / 反序列化 |

DataSet（多行数据）

| 方法 | 说明 | |------|------| | setRow(data) | 追加一行 Data，返回 this | | getRow(index) | 获取指定行，不存在返回 null | | delRow(index) | 删除指定行，返回 this | | length | 行数 | | toArray() | 转为 Record<string, any>[]（普通对象数组） | | toJSON() | 转为 Record<string, any>[]（供 JSON.stringify） | | fromJSON(json) | 从数组填充，返回 this | | toJsonString() / fromJsonString(str) | JSON 字符串序列化 / 反序列化 |

工具类

EnvelopeUtil — 快捷读写

支持具名函数和命名空间两种调用方式：

import { get, put, getBean, putBean, getList, putList, EnvelopeUtil } from '@bigworm/bigworm-envelope'

// 快捷读写 entity 默认节点的属性
put(entity, 'userId', '10001')
const userId = get(entity, 'userId')      // string（不存在返回 ""）

// Bean ↔ Entity（驼峰命名，无转换）
putBean(entity, userObj)                  // userObj 写入 entity 属性
const user = getBean<UserVO>(entity)      // entity 属性读到 UserVO

// List ↔ Entity 子表
putList(entity, 'orders', orderList)      // orderList 写入 orders 子表
const orders = getList<OrderVO>(entity, 'orders')

// 命名空间方式等价
EnvelopeUtil.put(entity, 'userId', '10001')
EnvelopeUtil.getBean<UserVO>(entity)

仅支持驼峰命名（无 snake_case 转换）。

TypeCastUtil — 类型转换

支持具名函数和命名空间两种调用方式，转换失败返回默认值而非抛出异常：

import { stringToInteger, objectToBoolean, dateToString, TypeCastUtil } from '@bigworm/bigworm-envelope'

// String → 其他
stringToInteger('123')           // 123
stringToFloat('99.99')           // 99.99
stringToBoolean('yes')           // true（支持 true/yes/1）
stringToDate('20260108')         // Date
stringToDateTime('20260108153045') // Date

// Object → 其他（智能转换，支持多种输入类型）
objectToInteger('45.7')          // 45
objectToFloat(true)              // 1
objectToBoolean('1')             // true

// 其他 → String
numberToString(123)              // "123"
floatToString(99.99, 2)          // "99.99"
dateToString(new Date())         // "20260108"
dateTimeToString(new Date())     // "20260108153045"

// 命名空间方式等价
TypeCastUtil.stringToInteger('123')

DateUtil — 日期工具

import { formatDate, parseDate, getNow, isDate, compareDate, DateUtil, DateEnum } from '@bigworm/bigworm-envelope'

// 格式化
formatDate(new Date(), DateEnum.YYYYMMDD)           // "20260108"
formatDate(new Date(), DateEnum.YYYYMMDD_BYSEP)     // "2026-01-08"
formatDate(new Date(), DateEnum.YYYYMMDDHHMMSS)     // "20260108153045"

// 解析
parseDate('20260108', DateEnum.YYYYMMDD)            // Date
parseDate('2026-01-08', DateEnum.YYYYMMDD_BYSEP)   // Date

// 当前时间
getNow(DateEnum.YYYYMMDDHHMMSS)                     // "20260108153045"

// 校验
isDate('20260108', DateEnum.YYYYMMDD)               // true
isDate('2026-02-30', DateEnum.YYYYMMDD_BYSEP)       // false

// 比较（返回 1 / 0 / -1）
compareDate(date1, date2)

LoggerUtil — 日志工具

import { LoggerUtil, Logger, LogLevel } from '@bigworm/bigworm-envelope'

const logger = LoggerUtil.getLogger('MyModule')

logger.trace('...')
logger.debug('...')
logger.info('...')
logger.warn('...')
logger.error('...')

// 全局日志级别控制
Logger.setLevel(LogLevel.WARN)    // 生产环境只输出 WARN / ERROR
Logger.setLevel(LogLevel.SILENT)  // 关闭所有日志
// 可选值：TRACE | DEBUG | INFO | WARN | ERROR | SILENT

JsonUtil — JSON 与 Envelope 互转

import { jsonString2envelop, envelop2jsonString, prettyPrint, JsonUtil } from '@bigworm/bigworm-envelope'

const envelope = jsonString2envelop('{"header":{...},"body":{...}}')
const str      = envelop2jsonString(envelope)
const pretty   = prettyPrint(envelope)

构建格式

| 格式 | 目录 | 场景 | Tree-shaking | |------|------|------|---| | ESM | dist/esm/（含 .d.ts） | Vite / Webpack / 现代工具 | ✅ | | CJS | dist/cjs/ | Node.js / Jest | — | | UMD | dist/umd/ | 浏览器 <script> 标签 | — |

构建 & 测试

npm run build        # ESM + CJS + UMD
npm run build:all    # 构建并压缩（发布前使用）

npm test             # 运行所有测试
npm run test:watch   # 监听模式
npm run test:coverage # 覆盖率报告