139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# 📦 DataStorage 数据存储模块
|
||
|
||
## ✨ 简介
|
||
|
||
该模块是一个基于 Unity + Easy Save 的本地数据存储系统，具备：
|
||
|
||
- ✅ 本地缓存机制（避免频繁磁盘 IO）
|
||
- ✅ 自动保存机制（按时间间隔或调用次数）
|
||
- ✅ 云同步支持（支持上传 JSON，或导入云端数据）
|
||
- ✅ 数据版本控制
|
||
- ✅ 类型安全的 `DataStorage<T>` 封装
|
||
- ✅ 可调试的 GM 工具接口
|
||
|
||
------
|
||
|
||
## 📁 使用说明
|
||
|
||
### 🔹 1. 定义数据键
|
||
|
||
在模块初始化之前，使用 `DataKeyDic.Register` 注册数据键名（通常在 `DataStorage<T>` 构造时自动完成）：
|
||
|
||
```c#
|
||
var playerName = new DataStorage<string>("PlayerName", "Guest");
|
||
playerName.Value = "Pius123";
|
||
```
|
||
|
||
或使用保存回调监听值变化：
|
||
|
||
```c#
|
||
var coins = new DataStorage<int>("CoinAmount", 0, (oldVal, newVal) => {
|
||
Debug.Log($"金币变化：{oldVal} -> {newVal}");
|
||
});
|
||
```
|
||
|
||
### 🔹 2. 保存和读取数据
|
||
|
||
```c#
|
||
coins.Value = 100; // 保存数据（自动缓存 + 标记待保存）
|
||
var coinAmount = coins.Value; // 从缓存读取（或回退至本地/云端）
|
||
coins.Save(); // 强制保存（即使值没变）
|
||
```
|
||
|
||
也可直接使用底层 API 操作(不建议)：
|
||
|
||
```c#
|
||
DataManager.Instance.SaveData("Level", 5);
|
||
int level = DataManager.Instance.LoadData("Level", 1);
|
||
```
|
||
|
||
### 🔹 3. 自动保存逻辑
|
||
|
||
模块会在以下时机自动保存数据到磁盘（使用 Easy Save）：
|
||
|
||
- ⏱ 每隔 15 秒（可配置）
|
||
- 🔁 累积 `SaveData` 达到 20 次（可配置）
|
||
- 🚫 App 暂停、退出时
|
||
- 📡 数据版本每增加两次触发一次 `_saveCallback`（用于云上传）
|
||
|
||
------
|
||
|
||
## 🌐 云同步支持
|
||
|
||
### ✅ 导出 JSON 上传云端
|
||
|
||
```c#
|
||
DataManager.Instance.AddSaveCallback((json, version, onQuit) => {
|
||
// 上传 json 到云端，携带版本 version
|
||
});
|
||
```
|
||
|
||
每次本地数据保存时（根据频率控制）会自动回调此方法。
|
||
|
||
### ✅ 从云端导入数据
|
||
|
||
```c#
|
||
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>` 会自动触发注册，但手动操作建议提前注册
|
||
- 非线程安全，不建议多线程并发调用
|
||
- 建议在游戏入口或登录成功后初始化模块并导入云数据 |