GFramework/.qoder/repowiki/zh/content/游戏功能模块/序列化器.md

序列化器

**本文引用的文件** - [JsonSerializer.cs](file://GFramework.Game/serializer/JsonSerializer.cs) - [ISerializer.cs](file://GFramework.Game.Abstractions/serializer/ISerializer.cs) - [SettingsSystem.cs](file://GFramework.Game/setting/SettingsSystem.cs) - [SettingsPersistence.cs](file://GFramework.Game/setting/SettingsPersistence.cs) - [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs) - [README.md（GFramework.Game）](file://GFramework.Game/README.md) - [game-api.md（docs）](file://docs/api-reference/game-api.md) - [architecture-patterns.md（docs）](file://docs/best-practices/architecture-patterns.md)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 组件详解
6. 依赖关系分析
7. 性能与优化
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向GFramework的序列化子系统，聚焦于JsonSerializer的JSON序列化实现，系统性阐述ISerializer接口的设计理念、类型处理机制、在游戏开发中的典型应用场景（数据持久化、网络传输、配置管理），以及性能优化策略（缓存、延迟加载、内存管理）。同时提供配置选项、API参考与实践示例，并总结最佳实践、错误处理与兼容性注意事项。

项目结构

围绕序列化能力，相关代码主要分布在以下模块：

• 抽象层：ISerializer接口定义
• 实现层：JsonSerializer基于Newtonsoft.Json的具体实现
• 应用层：设置系统与持久化服务，展示序列化在“配置管理”场景中的使用
• 文档与示例：README与API文档中给出的使用示例、自定义转换器与版本化序列化方案

graph TB
subgraph "抽象层"
IS["ISerializer 接口"]
end
subgraph "实现层"
JS["JsonSerializer 实现<br/>基于 Newtonsoft.Json"]
end
subgraph "应用层"
SS["SettingsSystem<br/>应用设置"]
SP["SettingsPersistence<br/>加载/保存设置"]
SM["SettingsModel<br/>数据与应用器注册"]
end
subgraph "文档与示例"
DOC["GFramework.Game/README.md<br/>使用示例/自定义转换器/版本化"]
API["docs/api-reference/game-api.md<br/>API参考"]
BP["docs/best-practices/architecture-patterns.md<br/>错误处理/最佳实践"]
end
IS --> JS
SS --> SM
SP --> SM
SS --> JS
SP --> JS
DOC --> JS
API --> JS
BP --> SS

图表来源

• ISerializer.cs
• JsonSerializer.cs
• SettingsSystem.cs
• SettingsPersistence.cs
• SettingsModel.cs
• README.md（GFramework.Game）
• game-api.md（docs）
• architecture-patterns.md（docs）

章节来源

• JsonSerializer.cs
• ISerializer.cs
• README.md（GFramework.Game）

核心组件

• ISerializer接口：定义统一的序列化与反序列化抽象，面向字符串格式的通用契约，便于替换不同实现（如JSON、MessagePack等）。
• JsonSerializer实现：封装Newtonsoft.Json，提供类型安全的Serialize/Deserialize方法；在反序列化失败时抛出异常以明确失败原因。
• 设置系统与持久化：通过SettingsSystem/SettingsPersistence/SettingsModel展示序列化在“配置管理”中的典型流程：加载、应用、保存、批量处理与事件通知。

章节来源

• ISerializer.cs
• JsonSerializer.cs
• SettingsSystem.cs
• SettingsPersistence.cs
• SettingsModel.cs

架构总览

下图展示了序列化器在“设置系统”中的角色与交互路径：设置模型提供数据与应用器，持久化服务负责读写存储，系统负责应用设置并发出事件，序列化器贯穿其中用于数据的序列化与反序列化。

sequenceDiagram
participant Ctx as "上下文/系统"
participant Model as "SettingsModel"
participant Persist as "SettingsPersistence"
participant Storage as "IStorage"
participant Ser as "JsonSerializer"
participant Sys as "SettingsSystem"
Ctx->>Persist : LoadAsync<T>()
Persist->>Storage : ExistsAsync(key)
alt 存在
Persist->>Storage : ReadAsync<T>(key)
Storage-->>Persist : T 实例
Persist-->>Ctx : T 实例
else 不存在
Ctx->>Model : GetData<T>()
Model-->>Ctx : 新建 T 实例
end
Ctx->>Sys : ApplyAll()/Apply<T>()
Sys->>Model : TryGet(type, out section)
Sys->>Ser : Deserialize<T>(json) 或直接使用实例
Sys-->>Ctx : 发送 SettingsAppliedEvent
Ctx->>Persist : SaveAsync<T>(section)
Persist->>Ser : Serialize<T>(section)
Persist->>Storage : WriteAsync(key, section)
Persist-->>Ctx : 发送 SettingsSavedEvent

图表来源

• SettingsSystem.cs
• SettingsPersistence.cs
• SettingsModel.cs
• JsonSerializer.cs

组件详解

ISerializer接口设计

• 设计目标：提供统一的序列化抽象，屏蔽具体实现细节，便于扩展多种格式（JSON、MessagePack、Protocol Buffers等）。
• 关键点：
  • 泛型方法Serialize/Deserialize确保类型安全。
  • 作为IUtility的子接口，融入GFramework的工具体系。
  • 与存储系统、设置系统解耦，便于替换实现。

章节来源

• ISerializer.cs

JsonSerializer实现

• 功能要点：
  • Serialize：将任意对象序列化为JSON字符串。
  • Deserialize：将JSON字符串反序列化为指定类型对象；若解析失败返回空值则抛出异常，明确失败语义。
• 与Newtonsoft.Json的关系：直接委托其SerializeObject/DeserializeObject，保持与该生态一致的特性与行为。
• 类型处理机制：
  • 支持Newtonsoft.Json的特性（如自定义转换器、忽略/包含属性、类型名处理等）。
  • 通过Converters集合扩展对特定类型（如Vector2、Color、Godot Resource）的序列化支持。

章节来源

• JsonSerializer.cs
• README.md（GFramework.Game）

设置系统中的序列化应用

• SettingsModel：维护两类设置集合（数据设置与应用器设置），提供GetData/RegisterApplicator/TryGet/All等方法，支撑设置系统的统一管理。
• SettingsPersistence：负责设置的加载、保存、删除、批量处理与存在性检查，内部通过IStorage进行读写，并在关键节点发送事件。
• SettingsSystem：负责应用设置（TryApply），在应用前后发送事件，捕获异常并向上抛出，保证错误可见性与可恢复性。

章节来源

• SettingsModel.cs
• SettingsPersistence.cs
• SettingsSystem.cs

API参考与使用示例

• 基础API
  • Serialize(T value)：序列化为JSON字符串。
  • Deserialize(string data)：从JSON字符串反序列化为T。
• 使用示例与扩展
  • README中提供了自定义转换器（Vector2/Color/Godot Resource）与版本化序列化（VersionedData+迁移）的完整示例。
  • API参考文档给出了Serialize/Deserialize/File/Async/Compressed等常见用法的片段。

章节来源

• JsonSerializer.cs
• README.md（GFramework.Game）
• game-api.md（docs）

类图（接口与实现）

classDiagram
class ISerializer {
+Serialize<T>(value) string
+Deserialize<T>(data) T
}
class JsonSerializer {
+Serialize<T>(value) string
+Deserialize<T>(data) T
}
class SettingsSystem {
-ISettingsModel _model
+ApplyAll() Task
+Apply<T>() Task
+Apply(Type) Task
+Apply(IEnumerable<Type>) Task
}
class SettingsPersistence {
-IStorage _storage
+LoadAsync<T>() Task<T>
+SaveAsync<T>(section) Task
+ExistsAsync<T>() Task<bool>
+DeleteAsync<T>() Task
+SaveAllAsync(allData) Task
+LoadAllAsync(knownTypes) Task<IDictionary<Type,ISettingsData>>
}
class SettingsModel {
-Dictionary<Type, IApplyAbleSettings> _applicators
-Dictionary<Type, ISettingsData> _dataSettings
+GetData<T>() T
+RegisterApplicator<T>(applicator) ISettingsModel
+GetApplicator<T>() T?
+TryGet(type, out section) bool
+All() IEnumerable<ISettingsSection>
}
ISerializer <|.. JsonSerializer
SettingsSystem --> SettingsModel : "使用"
SettingsPersistence --> SettingsModel : "读取/写入"
SettingsSystem --> JsonSerializer : "可能参与序列化"
SettingsPersistence --> JsonSerializer : "可能参与序列化"

图表来源

• ISerializer.cs
• JsonSerializer.cs
• SettingsSystem.cs
• SettingsPersistence.cs
• SettingsModel.cs

依赖关系分析

• 耦合与内聚
  • ISerializer与JsonSerializer之间为接口与实现的清晰分离，内聚度高、耦合度低。
  • SettingsSystem/SettingsPersistence/SettingsModel形成稳定的协作关系，序列化器作为可选组件被间接使用。
• 外部依赖
  • JsonSerializer依赖Newtonsoft.Json；通过Converters扩展实现自定义类型序列化。
• 循环依赖
  • 当前结构未见循环依赖迹象，各模块职责边界清晰。

章节来源

• JsonSerializer.cs
• ISerializer.cs
• SettingsSystem.cs
• SettingsPersistence.cs
• SettingsModel.cs

性能与优化

• 缓存机制
  • 存储层提供缓存包装（CachedStorage），可显著降低频繁读取带来的IO开销；序列化器本身未内置缓存，但可在上层结合缓存策略使用。
• 延迟加载与懒初始化
  • SettingsModel的GetData()采用“首次缺失创建”的策略，避免不必要的实例化。
• 内存管理
  • 使用Converters扩展自定义类型序列化，减少中间对象的创建与拷贝。
  • 对大对象或高频序列化场景，建议结合压缩（README中给出压缩思路）与批量写入（SettingsPersistence的SaveAllAsync）。
• 版本化与兼容性
  • README中提供版本化序列化与迁移方案，避免因字段变更导致的反序列化失败。

章节来源

• README.md（GFramework.Game）
• README.md（GFramework.Game）
• SettingsPersistence.cs

故障排查指南

• 反序列化失败
  • JsonSerializer在反序列化返回空值时会抛出异常，提示“无法反序列化数据”。应检查JSON格式、类型匹配与转换器配置。
• 设置应用异常
  • SettingsSystem在应用设置时捕获异常并发送事件，同时向上抛出，便于定位问题。建议在业务层捕获并记录上下文信息。
• 错误恢复策略
  • 参考最佳实践文档中的错误处理与恢复策略，优先尝试从备份存储恢复，最后回退到默认数据，确保系统可用性。

章节来源

• JsonSerializer.cs
• SettingsSystem.cs
• architecture-patterns.md（docs）

结论

GFramework的序列化子系统以ISerializer为抽象核心，JsonSerializer提供简洁可靠的JSON实现，并通过Converters扩展满足游戏开发中的复杂类型需求。在“设置系统”中，序列化器与设置模型、持久化服务、系统协作良好，覆盖了配置管理的全生命周期。结合缓存、延迟加载、版本化与错误恢复策略，可在保证易用性的同时兼顾性能与稳定性。

附录

配置选项与扩展点

• Newtonsoft.Json设置
  • README示例展示了如何配置Formatting、NullValueHandling、DefaultValueHandling与TypeNameHandling等。
• 自定义转换器
  • README提供了Vector2/Color/Godot Resource的转换器示例，可直接扩展到更多类型。
• 版本化与迁移
  • README提供了VersionedData与迁移接口的实现思路，便于跨版本兼容。

章节来源

• README.md（GFramework.Game）

API参考摘要

• ISerializer
  • Serialize(T value)：序列化为字符串
  • Deserialize(string data)：反序列化为T
• JsonSerializer
  • 基于Newtonsoft.Json的实现，支持Converters扩展
• SettingsSystem/SettingsPersistence/SettingsModel
  • 提供设置的加载、应用、保存、批量处理与事件通知

章节来源

• ISerializer.cs
• JsonSerializer.cs
• SettingsSystem.cs
• SettingsPersistence.cs
• SettingsModel.cs
• game-api.md（docs）