📦 DataStorage 数据存储模块
✨ 简介
该模块是一个基于 Unity + Easy Save 的本地数据存储系统，具备：
- ✅ 本地缓存机制（避免频繁磁盘 IO）
- ✅ 自动保存机制（按时间间隔或调用次数）
- ✅ 云同步支持（支持上传 JSON，或导入云端数据）
- ✅ 数据版本控制
- ✅ 类型安全的
DataStorage<T>封装 - ✅ 可调试的 GM 工具接口
📁 使用说明
🔹 1. 定义数据键
在模块初始化之前，使用 DataKeyDic.Register 注册数据键名（通常在 DataStorage<T> 构造时自动完成）：
var playerName = new DataStorage<string>("PlayerName", "Guest");
playerName.Value = "Pius123";
或使用保存回调监听值变化：
var coins = new DataStorage<int>("CoinAmount", 0, (oldVal, newVal) => {
Debug.Log($"金币变化：{oldVal} -> {newVal}");
});
🔹 2. 保存和读取数据
coins.Value = 100; // 保存数据（自动缓存 + 标记待保存）
var coinAmount = coins.Value; // 从缓存读取（或回退至本地/云端）
coins.Save(); // 强制保存（即使值没变）
也可直接使用底层 API 操作(不建议)：
DataManager.Instance.SaveData("Level", 5);
int level = DataManager.Instance.LoadData("Level", 1);
🔹 3. 自动保存逻辑
模块会在以下时机自动保存数据到磁盘（使用 Easy Save）：
- ⏱ 每隔 15 秒（可配置）
- 🔁 累积
SaveData达到 20 次（可配置） - 🚫 App 暂停、退出时
- 📡 数据版本每增加两次触发一次
_saveCallback（用于云上传）
🌐 云同步支持
✅ 导出 JSON 上传云端
DataManager.Instance.AddSaveCallback((json, version, onQuit) => {
// 上传 json 到云端，携带版本 version
});
每次本地数据保存时（根据频率控制）会自动回调此方法。
✅ 从云端导入数据
DataManager.Instance.ImportFromJson(jsonFromServer, versionFromServer);
- 若云端版本 > 本地版本：自动覆盖并保存到本地
- 若云端版本 < 本地版本：会自动触发
_saveCallback上传本地数据覆盖云端
🔧 GM 调试接口（可选）
调用 DataManager.Instance.Init() 可注册 GM 工具按钮：
- 🧹 清空所有数据
- 🗂 打印所有缓存键值对
🧠 数据结构概览
| 类名 | 说明 |
|---|---|
DataManager |
核心数据存储与调度管理（自动保存、版本、缓存） |
DataStorage<T> |
泛型数据封装，提供属性式访问与变更通知 |
DataKeyDic / DataKeyBase |
注册键名与云同步标记支持 |
ES3 |
第三方 Easy Save 工具（需另行导入） |
📝 配置项
| 名称 | 默认值 | 说明 |
|---|---|---|
InitialAutoSaveInterval |
15s |
自动保存时间间隔 |
SaveThreshold |
20次 |
自动保存调用次数阈值 |
DataVersion |
1 |
数据版本号，内部递增 |
🔍 调试建议
- 使用
DebugAllKeys()打印所有持久化键值 - 使用
DebugCache()打印当前缓存数据 - 检查
Log.Info/Error输出（默认已集成日志标记）
📦 依赖项
- Easy Save 3：第三方持久化框架
- Newtonsoft.Json：JSON 序列化与反序列化
- 自定义框架组件（如
SingletonMonoBehaviour、Log、CommonUtils、GMTool等）
📌 注意事项
- 云同步仅同步标记为
CloudSave = true的键 DataStorage<T>会自动触发注册，但手动操作建议提前注册- 非线程安全，不建议多线程并发调用
- 建议在游戏入口或登录成功后初始化模块并导入云数据