Skip to content

序列化 ​

jsMind v2 的序列化层把内存里的 JmMind 对象转成文件格式,以及反向读回。核心文件:

文件职责
src/serialization/serializer.tsJmMindSerializer 接口——serialize / deserialize / validate / getFormatName
src/serialization/json.tsv2 格式的完整实现:JmMindJsonSerializer,对应 format: "jsmind_v2"
src/serialization/freemind.tsFreeMind XML 格式兼容
src/serialization/serializer-factory.ts`jsMind.Serializer.create('json'
src/serialization/validation.tsvalidateMindData()——22 个错误码的结构校验,读写分离(不依赖序列化器)

另见序列化 API 参考。完整的磁盘 schema 不在本页展开,仍保留在仓库的 docs/requirements/v2-data-format.md 中。本站的数据格式页面仍在编写中。

1. 接口 ​

ts
interface JmMindSerializer {
    serialize(mind: JmMind): unknown;
    deserialize(data: unknown): JmMind;
    validate(data: unknown): boolean;
    getFormatName(): string;
}

用 jsMind.Serializer.create('json') 获取实例,不直接 new。

2. JSON 序列化 ​

磁盘格式 ​

format: "jsmind_v2"。扁平表:nodes 是 Record<string, SerializedNode>,父子关系通过 id 引用(parent / children)表达,edges 只存树之外的额外关系。

完整 schema 见 docs/requirements/v2-data-format.md。

serialize ​

ts
const serializer = jsMind.Serializer.create('json');
const doc = serializer.serialize(mind);
// → { format: "jsmind_v2", meta: {...}, root: "root", nodes: {...}, edges: {...} }

走 JmMind._nodes / JmMind._edges 逐个序列化。parent / children 存的是 id 引用,不是对象。节点样式 node.style 存在就写,不存在就省略——不写默认值,让接收方(主题)来填。

deserialize ​

ts
const json = JSON.parse(fs.readFileSync('map.json', 'utf8'));
const mind = serializer.deserialize(json);

内部调 validateMindData(),校验不通过抛 JsMindError(带 errors 数组),不会静默产出一个半残的 mind。校验失败不修改任何状态——抛异常之前什么都没发生。

validate ​

ts
serializer.validate(data)  // → true | false

validate 属于 JmMindSerializer 接口,只返回布尔值。JSON 序列化器的实现类 JmMindJsonSerializer 另外提供 check 方法,它不属于该接口。需要同时拿到错误列表时,使用 check:

ts
// 仅属于 JmMindJsonSerializer,不属于 JmMindSerializer 接口
jsonSerializer.check(data)  // → { valid: boolean, errors: JmValidationIssue[] }

每个错误带 code(稳定标识,如 E_FORMAT)、path(文档内位置)、message(给人看的文案)。

3. FreeMind 序列化 ​

JmMindFreeMindSerializer 兼容 FreeMind XML 格式。与 JSON 序列化器共用同一个 JmMindSerializer 接口。通过 factory 获取:jsMind.Serializer.create('freemind')。

4. 校验层 ​

validateMindData(data: unknown) 独立于序列化器——它不依赖 JmMind,只吃解析后的 JSON 对象。这意味着:

  • CLI 的 jsmind validate 不需要初始化 mind 就能跑
  • 序列化器和 CLI 共用同一套校验逻辑
  • 校验失败不是抛异常,是回 { valid: false, errors: [...] }

22 个错误码分四类:结构完整性(E_FORMAT/E_META/E_NODES_MISSING等)、引用完整性(E_NODE_PARENT_MISSING/E_ROOT_MISSING等)、一致性(E_PARENT_CHILD_MISMATCH)、取值合法性(E_SIDE/E_TONE/E_CONTENT_TYPE等)。完整列表见 v2-data-format.md 第 9 节。

5. autofix ​

已发布的 2.x CLI 尚未提供 --autofix。当前命令只有 jsmind validate <file> [--json]:只报告问题,不修改文件。

格式规范描述了未来的 --autofix:加该选项才写入,且绝不静默——必须输出改动清单。修复原则:宁可位置不对也不丢数据(孤儿节点挂 root)、不重建 children 顺序、不修改 content。详细规则见 v2-data-format.md 第 10 节。

本文档由 AI 协助生成 / This documentation was prepared with AI assistance