# moonsbe 0.2.0 项目提交说明书

| 项目 | 内容 |
| --- | --- |
| 表单项目名称 | `moonsbe` |
| 项目全称 | moonsbe：SBE 标准消息编解码与 MoonBit 代码生成库 |
| 参赛者 | 马昀昀 |
| 联系方式 | 1498657823@qq.com |
| 项目方向 | MoonBit 标准协议库、跨语言消息互操作、开发者工具 |
| GitHub | [liyun6666/moonsbe](https://github.com/liyun6666/moonsbe) |
| Mooncakes | [liyun6666/moonsbe](https://mooncakes.io/docs/liyun6666/moonsbe)，发布版本 `0.2.0` |
| 项目性质 | 原创 MoonBit 实现，使用上游 Java 参考实现做互通验证 |
| 许可证 | Apache License 2.0 |

## 项目用途

moonsbe 将 SBE XML Schema 编译为 MoonBit 可用的消息布局，提供二进制编解码、类型化代码生成和版本兼容检查。开发者可以复用现有协议定义，将 MoonBit 接入已有 SBE 消息系统。

1. **跨语言服务接入**。MoonBit 网关收到 Java 服务发送的消息后，可用生成的定长视图读取序号和状态，按需解码其余字段，并用同一 Schema 编码响应。
2. **二进制记录排查**。开发者从文件、日志或队列取得有明确边界的 SBE 报文，用 CLI 转换为 JSON，核对模板和字段值并定位截断。
3. **协议升级验收**。团队比较新旧 Schema，在 CI 中执行 Java 与 MoonBit 双向编解码，对照完整字节并保留日志。

## 复审版的改动与验证

| 初审关注项 | 0.2.0 实现与验证 |
| --- | --- |
| 自定义消息头 | 按 `headerType` 读取无符号字段宽度、偏移及扩展计数。Java 互通样例使用带填充的 13 字节头部，另有 `uint32 blockLength` 超过 16 位容量的测试 |
| 扩展组维度 | 按 `dimensionType` 处理条目数、块长、子组数和变长字段数，验证非零扩展计数、错误计数及条目数约束 |
| 版本化复合成员 | 依据 acting version 读取有效成员并保留 Schema 偏移。生成消费测试覆盖版本 0 与版本 1 |
| 可选复合字段 | 通过首个固定标量的空值标记整个字段缺失。Java 对照验证了价格存在和缺失两种报文 |
| 定长字段的静态访问 | 生成代码固化根块数值字段的偏移、宽度和字节序，直接读取原始字节，并检查版本、空值和访问边界 |

官方 Car 报文（207 字节）和两条扩展报文（各 36 字节）均通过 Java 与 MoonBit 的完整字节对照。JavaScript 和 Wasm GC 各通过 44 个测试，手写 MoonBit 共 4,795 行，其中实现 4,031 行、测试 764 行。统计排除了生成代码、上游源码、文档和工具脚本。功能验收记录对应提交 `8652359`。[GitHub Actions 验收记录及附件](https://github.com/liyun6666/moonsbe/actions/runs/43015364825)

本机在同一条 36 字节报文上读取序号，生成的定长视图平均耗时 168.17 ns，完整解码后取字段平均耗时 4.13 µs。完整解码同时处理复合字段、重复组和变长区，测量结果适用于该环境的单字段访问。[测量环境与复现步骤](interoperability.md)

## 从 Mooncakes 安装

在已有 MoonBit 模块中运行以下命令。

```sh
moon add liyun6666/moonsbe@0.2.0
```

在使用该库的 `moon.pkg` 中导入所需包。

```moonbit
import {
  "liyun6666/moonsbe" @sbe,
  "liyun6666/moonsbe/generated/extended" @wire,
}
```

用发布包中的生成类型读取扩展示例消息。以下代码可放进消费模块的测试文件。

```moonbit
///|
test "read a fixed field from an SBE message" {
  let bytes = @sbe.from_hex(
    "000c000000000001000701010101020304000004e2fe08007b02010001002a0178026f6b",
  )
  let view = @wire.Extended::view(bytes)
  assert_eq(view.f_sequence(), 0x01020304UL)
  assert_eq(view.f_status(), Some(123UL))
  let message = @wire.Extended::decode(bytes)
  assert_eq(message.f_note, "ok")
  assert_eq(message.encode(), bytes)
}
```

## 从仓库复现

使用固定 MoonBit 编译器 `v0.10.17+d971670cd`。CLI 与 JavaScript 测试使用 Node.js 22，独立互通验证使用 JDK 24，代码统计使用 ripgrep。

```sh
git clone https://github.com/liyun6666/moonsbe.git
cd moonsbe
moon update
moon test --target js --warn-list=-implicit_impl_as_method --deny-warn
moon test --target wasm-gc -p liyun6666/moonsbe -p liyun6666/moonsbe/examples/extended --warn-list=-implicit_impl_as_method --deny-warn
moon run tools/interop.mbtx
moon run tools/stats.mbtx
```

互通脚本核验上游工具的 SHA-256，重新生成 Java 与 MoonBit 代码，并比较全部解码字段和完整报文。日志和扩展报文位于 `_build/interop-logs`，也可在 CI 附件中下载。

生成定长视图适用于根块的整数、浮点数和数值数组。完整编解码由共享运行时负责。可选复合字段需要首个固定标量作为空值标记，未知变长字段按当前兼容规则处理。已完成外部互通验证的实现为 Java。[完整兼容矩阵](compatibility.md)

## 参考来源与许可证

项目按公开 SBE 规范独立实现。互通验证使用 `aeron-io/simple-binary-encoding` 的 `1.35.0` 版本，引用的 Schema 和 Java 示例保留上游版权声明。本项目与上游参考实现均采用 Apache License 2.0。[SBE 规范](https://www.fixtrading.org/wp-content/uploads/download-manager-files/Simple_Binary_Encoding_V1.0_with_Errata_November_2020.pdf) · [上游参考实现](https://github.com/aeron-io/simple-binary-encoding/tree/1.35.0) · [本项目许可证](../LICENSE)