企业官网建设流程全解析

REDox可变Token DOM实战:免重建JSON文档的插入/删除/修改完全教程

【免费下载链接】REDoxHigh-performance, token-based structured data engine for .NET. A core component of REX, the technology behind CAPCOM's next-generation game engine.项目地址: https://gitcode.com/gh_mirrors/redox/REDox

REDox（RE:Dox）是卡普空为下一代游戏引擎 REX 技术打造的 .NET 高性能结构化数据引擎。它的核心亮点之一就是可变 Token DOM：解析 JSON 后，你可以直接在同一个文档上完成插入、删除、修改操作，而无需销毁文档再重新解析。对于需要频繁编辑 JSON 配置、日志、游戏数据的 .NET 开发者来说，这是一份难得的免重建编辑完全教程。

为什么需要"免重建"的 JSON 编辑？

传统 .NET 生态里编辑 JSON 只有两个不理想的选择：

REDox 的 Token DOM 同时拿到两者之长：把 JSON 解析成紧凑定长的 Token 序列（内部 IR），再通过 DElement 这样的轻量句柄定位到具体 Token 做原地编辑。文档本身不重建，分配极低——官方基准测试中 canada.json 反序列化仅分配约2.56 MB（System.Text.Json 约 8.53 MB）。

30 秒上手：解析出可编辑文档

用 NuGet 安装核心包后，一行代码即可得到可变文档：

dotnet add package CAPCOM.REDox

using REDox.Json; using var doc = JsonDocument.Parse(json); // 解析为 Token DOM var root = doc.RootElement.AsObject(); // 拿到根对象句柄

解析入口在 JsonDocument.cs，底层 Token 结构定义于 DToken.cs 与 DTokenKind.cs。

修改已有属性：一行赋值原地替换

获取属性后直接赋值即可替换原值，Token 序列就地更新，不产生新文档：

root["Name"] = "Claire"; // 替换字符串 root["Level"] = 43; // 替换数字

赋值逻辑实现在 DObject.cs 的索引器与SetValue方法中。

插入与删除属性：Add / Remove 实战

对象（Object）的属性增删非常直观：

• 插入新属性：root.Add("Hp", 100);
• 删除属性：root.Remove("Level");（返回 bool 表示是否命中）
• 嵌套容器：root.AddObject("Profile")、root.AddArray("Tags")可一步创建子对象/子数组

相关 API 位于 DObject.cs（Add）与 L173-L187（Remove）。

数组编辑三板斧：Add、Insert、RemoveAt

对数组（Array）元素，REDox 提供三类操作，全部作用在原文档上：

var items = root["Items"].AsArray(); items.Add("First Aid Spray"); // 末尾追加 items.Insert(0, "Knife"); // 指定位置插入 items.RemoveAt(1); // 按下标删除

• 追加：DArray.cs 的Add
• 按位插入：DArray.cs 的Insert(index, value)
• 按位删除：DArray.cs 的RemoveAt，还支持 L287 的RemoveRange(index, count)批量删除

键值对无序集合可改用DMap：其Add、Insert、RemoveAt、SetKey等 API 见 DMap.cs。

进阶：ReplaceWith 跨类型整体替换

最强大的编辑 API 是ReplaceWith——把任意节点（属性、数组元素、甚至根节点）整体替换为另一种类型，例如把对象换成标量、把字符串换成数组：

root["Name"].ReplaceWith(42); // 属性值改为数字 items[0].ReplaceWith("was-object"); // 数组元素整体替换 doc.RootElement.AsValue().ReplaceWith(new[] {1,2,3}); // 连根节点都能换

实现位于 DValue.cs。这意味着你可以在同一份文档中自由重构结构，而不必担心"类型不匹配需重建"的问题。

编辑安全机制：Version 快照与 Dispose

REDox 的编辑句柄（DElement/DValue）都携带文档版本号：文档每次重置或释放（Dispose）都会递增版本，旧句柄再操作会抛出ObjectDisposedException，防止悬空访问。核心逻辑可参考 Document.cs 中的Reset与Dispose，以及DElement内嵌的Version字段（DElement.cs）。

💡 实践建议：编辑完成后用doc.RootElement.ToJsonString()输出结果，using语句会自动归还 Token 内存池。

JSON5 用户必看：注释与空行也能存活

如果你的数据源是带注释的 JSON5（配置文件中非常常见），REDox 的编辑还能保留注释、空行等 Trivia，重新编码时原样输出，不会像多数解析器那样"洗掉"注释。Trivia 编辑 API 见 DTrivia.cs 与 DTriviaCollection.cs，解析入口在 Json5Document.cs。

关键源码速查清单

总结

• REDox 的可变 Token DOM让你在不重建 JSON 文档的前提下完成插入、删除、修改，兼顾磁带 DOM 的速度与节点 DOM 的可编辑性
• 对象用Add/Remove/ 赋值，数组用Add/Insert/RemoveAt，跨类型重构用ReplaceWith
• 版本号机制保证编辑句柄安全，Dispose后自动归还内存池
• 支持 JSON5 注释保留，适合编辑带注释的配置文件

如果你正在为"改一个字段就要重解析整份 JSON"而烦恼，REDox 的 Token DOM 编辑模型值得立刻尝试。

【免费下载链接】REDoxHigh-performance, token-based structured data engine for .NET. A core component of REX, the technology behind CAPCOM's next-generation game engine.项目地址: https://gitcode.com/gh_mirrors/redox/REDox