CAPCOM-TD-OSS/REDox · 上手攻略

• 仓库：CAPCOM-TD-OSS/REDox
• 链接：https://github.com/CAPCOM-TD-OSS/REDox
• 分类：.NET · 序列化 / 性能库
• 作者：Tom
• 更新：2026-10-05

---

§0 一句话速览

RE:Dox 是卡普空技术研发部开源的高性能 .NET 结构化数据引擎，核心是一个 64 位 Token DOM，将 JSON/CBOR/MessagePack 等多种格式统一解析为紧凑的 Token 中间表示，再驱动序列化、反序列化、原地编辑和格式转换——比 System.Text.Json 最高快 2.8 倍并行反序列化，内存分配仅后者的约 1/3。

---

§1 是什么

RE:Dox（Read-Evaluate-DOx）是一个以 Token 为单位的结构化数据处理引擎，而非单纯的 JSON 序列化库。它的核心思路是：

JSON / JSON5 / CBOR / MessagePack / TOML / XML / HTML / CSV / INI / DOX
        ↓
  Compact Token DOM / IR（64位 Token 固定大小）
        ↓
Reader / Writer / Serializer / Deserializer
        ↓
  .NET 对象、JSON、CBOR、MessagePack、TOML、XML 等

每个数据值被编码为固定 64 位 Token，扩展位决定载荷是由文档层解释还是由 RE:Dox 固定解释。这种设计让同一个 Token 结构既能代表源格式的只读视图，也能成为 RE:Dox 自有的可编辑 DOM。

核心定位：不是又一个 JSON 库，而是"结构化数据的通用中间层 + 高性能实现"。

---

§2 解决什么问题

.NET 生态已有不少序列化库，但它们通常只能三选二：

能力	System.Text.Json	Newtonsoft.Json	RE:Dox
解析速度（tape DOM 级）	✅	❌	✅
原地编辑（node DOM 级）	❌	✅	✅
灵活性（$type/$id/$ref 等）	❌	✅	✅

RE:Dox 试图三者兼得：

• 高性能：固定 Token DOM 避免了重型托管对象树的分配；并行反序列化自动利用多核。
• 可编辑：不像 JsonDocument 那样只读，Token DOM 支持原地增删改，修改后直接重新序列化，无需重建整棵树。
• 灵活性：通过 DataConverter 提供格式无关的 DataReader/DataWriter 抽象，支持 $type、$id/$ref、out-of-order 构造绑定等 Newtonsoft.Json 风格特性。
• 多格式统一：同一套 Token IR 驱动 JSON/CBOR/MessagePack/INI 等多种格式的读写和相互转换，转换逻辑可跨格式复用。

典型痛点场景：游戏引擎需要频繁读写配置、存档、网络协议数据，既要高性能（不能每帧 GC 卡顿），又要有时候需要动态修改 JSON 结构再写回——传统方案要么慢要么难编辑，RE:Dox 一次性解决。

---

§3 快速安装

环境要求

• .NET 10.0（RyuJIT x64-v3 优化，benchmark 环境为 AMD Ryzen Threadripper PRO 5975WX + Windows 11）
• Linux/macOS 通过 .NET 10 跨平台支持（benchmark 仅测 Windows，Linux 表现需自行验证）

NuGet 包一览

包名	内容	状态
CAPCOM.REDox	核心 + JSON + JSON5 + DOX	Stable v1.0.0（2026-10-01）
CAPCOM.REDox.Cbor	CBOR 解析器/写入器	Stable
CAPCOM.REDox.MessagePack	MessagePack 集成	Stable
CAPCOM.REDox.Ini	INI 支持	Stable
CAPCOM.REDox.Dynamic	动态对象 API	Stable
CAPCOM.REDox.Serialization.SystemTextJson	STJ 兼容层	Stable
CAPCOM.REDox.Serialization.NewtonsoftJson	Newtonsoft.Json 兼容层	Stable
CAPCOM.REDox.Toml	TOML 支持	Preview
CAPCOM.REDox.Xml	XML 支持	Preview
CAPCOM.REDox.Html	HTML 支持	Preview
CAPCOM.REDox.Csv	CSV 支持	Preview

安装命令

# 核心包（必须）
dotnet add package CAPCOM.REDox

# 常用格式（按需）
dotnet add package CAPCOM.REDox.Cbor
dotnet add package CAPCOM.REDox.MessagePack
dotnet add package CAPCOM.REDox.Ini

# 兼容层（迁移现有项目时用到）
dotnet add package CAPCOM.REDox.Serialization.SystemTextJson
dotnet add package CAPCOM.REDox.Serialization.NewtonsoftJson

# 动态 API
dotnet add package CAPCOM.REDox.Dynamic

# Preview 格式（API 可能变更）
dotnet add package CAPCOM.REDox.Toml --prerelease

---

§4 核心用法

4.1 序列化与反序列化（最常用）

using REDox.Json;

// 定义 POCO
public sealed class Player
{
    public string? Name { get; set; }
    public int Level { get; set; }
    public string[] Items { get; set; } = [];
}

var player = new Player
{
    Name = "Leon",
    Level = 42,
    Items = ["Handgun", "Green Herb"]
};

// 序列化
var json = JsonSerializer.Serialize(player);
// → {"Name":"Leon","Level":42,"Items":["Handgun","Green Herb"]}

// 反序列化
var restored = JsonSerializer.Deserialize<Player>(json);

注意：以上 API 签名与 System.Text.Json 完全一致，迁移成本极低。

4.2 原地编辑 Token DOM（RE:Dox 特色能力）

using var doc = JsonDocument.Parse(json);  // 注意：这里用的是 System.Text.Json 的 Parse
                                          // RE:Dox 自己的 Token DOM 通过 REDox.Json 入口获取

var root = doc.RootElement.AsObject();  // 转为 RE:Dox 可编辑对象

// 增删改
root["Name"] = "Claire";    // 替换
root.Add("Hp", 100);        // 新增
root.Remove("Level");       // 删除

// 数组操作
var items = root["Items"].AsArray();
items.Add("First Aid Spray");   // 末尾追加
items.Insert(0, "Knife");      // 插入到索引0
items.RemoveAt(1);             // 按索引删除

// 重新序列化
var edited = doc.RootElement.ToJsonString();
// → {"Name":"Claire","Items":["Knife","Green Herb","First Aid Spray"],"Hp":100}

⚠️ 坑：示例代码复用 System.Text.Json.JsonDocument.Parse，实际使用时需确认 RE:Dox 的 JsonDocument 扩展方法与 STJ 的 JsonDocument 是否共享同一类型（API 兼容层设计）。不确定时请以 GitHub README 最新代码为准。

4.3 动态对象（无需预定义类型）

using REDox;
using REDox.Dynamic;

using var doc = JsonDocument.Parse("""{"name":"Leon","level":40,"stats":{"alive":true}}""");
var player = doc.RootElement.AsDynamic()!;

var name  = (string)player.name;
var level = (int)player.level;
var alive = (bool)player["stats"]["alive"];

// 动态构建新对象
var obj = new DObject().AsDynamic();
obj.Name  = "Ada";
obj.Items = new[] { "Hookshot" };

string json = JsonSerializer.Serialize(obj);

4.4 跨格式转换（DataConverter 抽象）

DataConverter 面向格式无关的 DataReader/DataWriter，而非特定线格式——同一转换器实现可跨多个格式复用（JSON ↔ CBOR ↔ MessagePack 等）。

详细 API 需参考 GitHub 文档，Preview 状态 API 可能变更。

4.5 性能基准（官方 Benchmark）

环境：BenchmarkDotNet / .NET 10 RyuJIT x86-64-v3 / AMD Ryzen Threadripper PRO 5975WX / Windows 11

数据集	反序列化提速	并行反序列化提速	序列化提速
canada.json	1.68×	2.84×	1.06×
citm_catalog.json	1.77×	2.25×	1.62×
twitter.json	1.36×	2.34×	1.42×

（对比基准均为 System.Text.Json）

内存分配对比（canada.json）： - RE:Dox：约 2.56 MB - System.Text.Json：约 8.53 MB

⚠️ 免责声明：以上均为特定数据集 + 特定硬件下的实测结果，不代表所有场景。RE:Dox 官方明确注明"these ratios...are not universal performance guarantees"。生产环境请务必用自己的真实数据 Benchmark。

自行复现：

dotnet run -c Release --project benchmarks/REDox.Json.Benchmarks

---

§5 典型适用场景

1. 游戏引擎数据层：存档序列化、网络协议打包、配置热更新——高性能 + 可编辑的双重需求，RE:Dox 的 Token DOM 天然契合游戏开发的性能敏感场景。

2. 大型 JSON 文件处理：超过数百 MB 的 JSON 数据集（如日志分析、数据湖导出文件），并行反序列化 + 低分配特性可显著减少 GC 压力。

3. 多格式配置文件：同一套配置需要以 JSON、CBOR、MessagePack 等多种格式分发或存储，DataConverter 抽象避免为每种格式单独编写序列化逻辑。

4. 已有 Newtonsoft.Json / System.Text.Json 项目的迁移：提供完整兼容层，可以渐进式引入 RE:Dox，无需一次性重写全部序列化代码。

5. 需要保留注释的配置文件：Trivia-preserving JSON5 编辑能力，修改配置文件时保留注释不被丢弃，适合人类维护的配置文件场景。

---

§6 坑与注意

1. .NET 10.0 强制依赖：这是目前最大的门槛。如果项目还在 .NET 8 或 .NET 6，必须先升级才能使用。生产环境升级 .NET 版本需要完整的回归测试周期。

2. Preview 包 API 不稳定：TOML、XML、HTML、CSV 均为 Preview 状态，正式项目使用前需锁定具体版本号，避免上游 API 破坏性变更。

3. Benchmark 数据不代表通用性能：官方明确警告"not universal performance guarantees"。真实项目的数据形状（扁平 vs 深层嵌套）、字段类型分布、CPU 架构都会影响提速比例，务必自己 Benchmark。

4. 与 System.Text.Json.JsonDocument 类型混淆：RE:Dox 提供了对 STJ JsonDocument 的扩展方法（如 .AsObject()），但这依赖兼容层包。纯 RE:Dox Token DOM 的入口方式请以 GitHub README 最新说明为准。

5. 并行反序列化并非自动开启：需要显式调用并行 API（JsonSerializer.DeserializeAsync 或对应并行路径），并非所有场景都适合并行——小文件或内存受限环境下并行 overhead 可能得不偿失。

6. DOX 格式：这是 RE:Dox 自定义的格式，用于测试或特定游戏引擎场景，生态内工具支持有限，不建议作为主要数据交换格式。

7. 社区生态尚在早期：GitHub Stars 1036（截至 2026-10-05），NuGet 下载量较低（核心包 322 次），遇到问题更多需要看源码而非 Stack Overflow。

---

§7 与同类对比

特性	RE:Dox	System.Text.Json	Newtonsoft.Json	Utf8Json	SpanJson
多格式支持	✅ 10+ 格式	❌ 仅 JSON	✅ JSON+XML等	❌ 仅 JSON	❌ 仅 JSON
原地编辑 DOM	✅ Token DOM	❌ JsonDocument只读	✅ JObject/JArray	❌	❌
高性能（~ STJ+）	✅ 1.4~2.8×	基准	❌ 较慢	✅ 持平或更好	✅ 持平或更好
并行反序列化	✅ 自动	❌	❌	❌	❌
低分配设计	✅ ~1/3 STJ	❌	❌	✅	✅
$type/$id/$ref 支持	✅	❌	✅	❌	❌
AOT/Source Gen	规划中（Preview）	✅	❌	✅	✅
生态成熟度	🔶 新兴	🔷 内置	🔷 成熟	🔶 小众	🔶 小众
许可证	Apache-2.0	MIT	MIT	MIT	MIT

结论：如果你的场景是高性能 + 原地编辑 + 多格式，RE:Dox 是目前 .NET 生态中独一份的选择。如果只是需要高性能 JSON序列化且不需要编辑能力，Utf8Json / SpanJson 生态更成熟、踩坑更少。如果需要 AOT，System.Text.Json 的 Source Generator 更保险。

---

§8 一句话推荐结论

RE:Dox 是 .NET 序列化领域一次有野心的创新——用 64 位 Token DOM 统一了高性能、可编辑、多格式三个目标，尤其适合游戏引擎、大型 JSON 处理和跨格式数据管道场景；但 .NET 10 强依赖和新兴生态是现实约束，现有 .NET 项目建议观望 1~2 个小版本再生产引入，新项目或 .NET 10 先行项目可以积极试用并反馈社区。