# 独立互通验收与适用场景

## 0.2.1 的 SBE 1.0 复审用例

运行 `moon run --deny-warn tools/conformance.mbtx`。除 MoonBit 和 Node.js 外，需要 JDK 24、Maven 和 ripgrep。脚本下载并核对官方套件与 XSD 的 SHA-256，用原始 `schema1.xml` 至 `schema3.xml` 和 `test1.json` 至 `test3.json` 构造输入。Schema 和计划文件按上游字节保留。旧版 Java 源码用 `javac --release 8` 编译。

| 用例 | 本次实测 |
| --- | --- |
| 旧版订单传输 | 官方套件注入 62 字节 `NewOrderSingle`，MoonBit 核对账户、合约、价格、数量等全部字段，独立重新编码与 Java 完全一致。 |
| 固定字段演进 | 官方套件注入 66 字节带 `MinQty` 的新版本，原 schema2 读取新增字段，原 schema1 读到相同旧字段，并跳过多出的固定区。 |
| 新版订单变长区 | 官方套件注入 88 字节含 `ComplianceText` 的新版订单，原 schema3 全字段解码正确，重新编码逐字节一致。 |
| SBE 1.0 §4.7.5 | 本项目按规范定义 `data` 成员及 UTF-16 `SecurityDesc`。字符“股票🚀”报文为 24 字节，空文本报文为 14 字节，使用原 XML 与 Java 标准字符集双向核对。 |

四份 XML 均通过 FIX 1.0 XSD 校验。官方套件覆盖的是三条请求和早期读取场景，响应计划留在完整标准验收范围。脚本以原始注入报文作字节对照，保留旧注入器将样例中的空 StopPx 转成零尾数的行为。真实空值由 MoonBit 单元测试另行核对。

1.35.0 参考工具对变长载荷名要求 `varData`，规范第 4.7.5 节示例使用 `data`。该用例在同一份 XML 上使用 MoonBit CLI、官方 XSD 和独立 Java `ByteBuffer`、`Charset` 对照，保持原样。Java 字节、MoonBit 字节、字段 JSON 及每步日志在 `_build/interop-logs/sbe10`。[固定来源](../interop/UPSTREAM.md)

## 实际集成场景

1. **跨语言消息交换**。现有 Java 或 C++ 系统使用 SBE Schema 定义消息。MoonBit 程序引用同一 Schema 生成的类型，读取消息字段或产生可被对端解码的二进制消息。
2. **已有二进制记录读取**。调用方从日志、队列或抓取文件取得一条消息的边界，库检查模板和编码范围后解码，CLI 将字段导出为便于检查的 JSON。
3. **消息定义升级验收**。开发者比较新旧 Schema，检查固定字段追加、值域变化、重复组与变长字段变化，再用两种语言的实现做对照测试，将日志保存到 CI。

上述流程面向采用 SBE 的开发团队。项目当前使用公开参考数据完成互通，尚无外部用户采用记录。

## 固定输入

使用上游 `1.35.0` 标签的 `example-schema.xml`、`common-types.xml` 和 `ExampleUsingGeneratedStub.java`。Schema 原有 XInclude 保留。参考工具 `sbe-all-1.35.0.jar` 的 SHA-256 为以下值。

```text
d11f4bb7c71322e3538613b2da18b11625be400465b29a09db80bc9785cea3ab
```

官方 Car Schema 含 45 字节固定区、复合字段、常量字段、枚举、位集合、3 项 fuelFigures、2 项 performanceFigures 及每项 3 个 acceleration 子项，还含 ASCII 与 UTF-8 长度前缀数据。

## 一条命令复现

```sh
moon run tools/interop.mbtx
```

脚本使用 MoonBit `.mbtx` 编写，执行以下检查并逐步记录标准输出、错误输出与退出码。

| 检查 | 判定方式 |
| --- | --- |
| 参考工具完整性 | 先核验下载 JAR 的 SHA-256 |
| Java 编码 | 用固定上游工具生成 Java codec，运行未修改的上游示例编码器 |
| Java → MoonBit | MoonBit 解码 Java 产生的完整消息，将全部 JSON 字段与仓库预期值比较 |
| MoonBit → Java | MoonBit 从独立输入 JSON 编码，Java 参考编码器产生期望字节并逐字节比较 |
| Java 字段遍历 | Java 生成解码器读取完整消息并遍历嵌套重复组和可变数据 |
| 生成器 | 从同一 Schema 生成并编译 MoonBit 类型适配器 |
| 独立消费包 | examples/typed 检查定长视图、记录、枚举和嵌套字段，再编码由 Java 校验 |
| 扩展 Schema | Java 分别编码有价格和空价格的两条大端报文，MoonBit 解码并比较全部 JSON 字段。Java 解码 MoonBit 独立编码的报文并逐字节比较 |

## 本地实测结果

2026 年 11 月 11 日复审版完整本地运行通过。Car 消息连同 8 字节头部为 207 字节，Java 编码、MoonBit 编码和生成类型消费包编码得到相同消息字节，其 SHA-256 如下。

```text
0e1649c2f5a2719b2d10c2a9dc6e1aa962d8523fb8c4531052dbdad65528bfe2
```

两条 36 字节扩展报文均通过双向验收。自编样例使用 13 字节头部、4 字节组维度、版本化价格成员和空值标记。Java 对照程序使用上游生成的头部与组维度接口设置扩展计数，并遍历完整消息。MoonBit 的生成消费测试另覆盖版本 0 报文、错误计数以及跨越固定块边界的读取。

本地运行环境为 Windows、MoonBit 0.1.20261023、moonc v0.10.17 和 JDK 24.0.1。每次运行清理旧成功标记，失败会停止并保留已产生的日志。

日志位于 `_build/interop-logs`。GitHub Actions 将日志、Java 消息、MoonBit 消息和解码 JSON 归档为 `moonsbe-interop-evidence`。完整测试范围与限制见 compatibility.md。

## 定长字段访问测量

```sh
moon bench examples/extended --target js --release --warn-list=-implicit_impl_as_method --deny-warn
```

2026 年 11 月 11 日在 Windows、Intel Core i7-13650HX、Node.js 22.20.0 和固定 MoonBit 工具链上，用同一条 36 字节报文读取 `sequence`。输入预先加载，完整解码路径预热后开始测量。定长路径每次新建视图并取一个字段。

| 路径 | 平均耗时 |
| --- | ---: |
| 生成类型完整解码后取字段 | 4.13 µs |
| 生成的定长视图取字段 | 168.17 ns |

测量覆盖该环境下的单字段访问。完整解码同时校验和构建其余字段，包含重复组和变长数据，两条路径的工作量不同。
