存档设计经验总结
精华03/18293 浏览开发心得
适用于 UrhoX + serverCloud 的联网游戏项目。
---
一、核心思路：三层分离
存档系统最重要的设计决策是把"运行时状态"、"序列化格式"和"持久化通道"拆成三层，彼此独立演进。
运行时状态（GameState）是一个内存中的全局单例，所有游戏系统只读写它，不直接接触存档。好处是游戏逻辑完全不关心"数据怎么存、存在哪"，降低了耦合度。
序列化模块负责在 GameState 和紧凑格式之间做翻译。每个业务领域一个模块（工会、成员、探索、日志……），各自维护字段映射，互不干扰。
持久化通道（ServerSave / ServerSaveLoad）负责跟云端通信。防抖、合并、重试、容错都封在这一层里。
```
游戏系统 ──→ GameState(内存单例) ←──→ 序列化模块 ←──→ ServerSave(防抖) ←──→ serverCloud
```
这样做的实际收益：中间换过一次云端存储方案，GameState 和所有游戏系统一行没改，只动了 ServerSave 里的几个调用。
---
二、分槽存储
不要把所有数据塞进一个大 JSON。按业务领域切成独立的"存档槽"，每个槽有自己的 key、序列化函数和反序列化函数。
为什么分槽：
1.改了成员数据只重写成员槽，工会配置纹丝不动，减少写入量
2.每个槽体积可控，不容易撞上云端单条 ~13KB 的限制
3.某个槽损坏时不会连带其他数据一起挂
槽的注册方式： 在一个统一的注册表（SLOT_DEFS）里声明每个槽的 key、序列化函数、反序列化函数。新增槽位只需要往注册表加一行，加载和保存逻辑自动覆盖，不用到处改代码。
---
三、大集合分片
成员列表这类"会随游戏进程增长"的数据必须分片。本项目 30 人上限，按每 15 人一个槽切成 members_1 和 members_2。
分片粒度取决于单条配额。先算单个成员序列化后的平均体积，反推每个分片能放多少条，再留 20%~30% 余量应对装备等可选字段膨胀。
日志这类无限增长的数据除了分片还要加 FIFO 上限（本项目 50 条），老条目自动丢弃。
---
四、短键名 + 默认值兜底
序列化用短键名：运行时 `guildName` 存档时写 `gn`，`guildLevel` 写 `gl`。30 个成员的存档光键名就能省 30%~40% 体积，在 13KB 限制下很关键。
**反序列化必须给默认值：** 每个字段都写成 `GameState.guildName = data.gn or "无名工会"` 的形式，没有例外。这样老存档在新版本上加载时，缺失的新字段自动用默认值填充，天然具备向前兼容能力，绝大多数版本迭代不需要写迁移脚本。
只有在数据结构发生破坏性变更时（字段类型变了、嵌套层级改了），才需要引入版本号做显式迁移。项目中成员数据的 `v < 2` 迁移就是这种情况——早期没有 status 字段，升级时自动补 `st = "idle"`。
---
五、防抖写入
每次数据变更不立即写入云端，而是标记对应的槽为"脏"。定时器每 5 秒触发一次，把所有脏槽合并成一次 BatchSet 请求。
```
玩家 5 秒内点了 3 次升级 → guild_core 标脏 3 次（实际只标 1 次）
→ 5 秒后合并成 1 次网络请求写出
```
**inflight + pending 双缓冲：** 如果上一次 BatchSet 还没返回，新的脏标记存到 pending 队列。inflight 完成后再把 pending 发出去。任意时刻最多两次网络调用在路上，既不丢数据，也不乱序。
**generation 计数器：** 每次 flush 递增 generation，旧的 inflight 回调发现 generation 不匹配时自动失效，防止过期回调干扰新状态。
---
六、断线快照
防抖有一个盲区：玩家在定时器触发之前断线，脏数据就丢了。
检测到断线或关闭时立即执行一次 flush——先拍当前状态的快照（序列化），再以最高优先级排队写入。快照用的是断线那一刻的状态，不等 inflight 回来，确保数据是最新的。
---
七、容错加载
加载时每个槽的反序列化都包在 pcall 里。某个槽解析失败就打日志、用默认值填充、继续加载其他槽。日志槽坏了不影响角色数据，不会让整个游戏无法启动。
加载顺序有依赖关系的要先加载被依赖方。所有槽加载完成后统一执行"加载后逻辑"（跨日检测、过期清理等），不在单个槽的反序列化里各自处理。
---
八、货币和配额走专用通道
金币（Money）和门票（Quota）不走 Score 槽位，走云端提供的专用原子操作接口。
原因是这类数值型资源需要原子性的加减操作（防止并发导致余额错乱），云端的 Money:Add / Money:Cost 和 Quota:Add 自带原子保证和负数校验，比自己在 JSON 里存一个数字再手动加减安全得多。
操作时注意：修改金币后不需要标脏（因为不走 Score 槽），而是直接调用 Money/Quota 的云端接口。但 GameState 里的缓存值要同步更新，保持运行时状态的一致性。
---
九、新增字段的标准流程
给现有槽加字段只需要 4 步，不需要写迁移逻辑：
1. GameState 加字段和默认值
2. resetAll() 加重置
3. 对应模块的 serialize() 加序列化（用短键名）
4. 对应模块的 deserialize() 加反序列化（带 `or 默认值`）
新增一个全新槽位需要多改几处：创建序列化模块、注册到 SLOT_DEFS、在 Shared 里加 key 常量、在 ServerSaveLoad 的 BatchGet 里加一行、GameState 里加字段。但整体流程是机械的，不容易出错。
---
十、端到端验证
存档 bug 往往滞后暴露。写一组自动化测试覆盖完整的往返流程：
1. 填充已知数据到 GameState
2. 序列化 → 写入云端
3. 清空 GameState
4. 从云端读取 → 反序列化
5. 逐字段 deepEqual 比对
准备多组测试数据：新手空档、中期半满、满编极端、故意缺字段的旧版模拟。每次改动序列化逻辑后跑一遍，防止回归。
---
- ## 设计检查清单
- - 运行时状态和持久化是否分层（GameState vs ServerSave）
- - 是否按业务领域分槽，单槽体积是否在配额内
- - 大集合是否分片，是否有增长上限
- - 序列化是否用短键名，反序列化是否每个字段都有默认值
- - 写入是否防抖合并，是否有 inflight/pending 双缓冲
- - 断线时是否有快照 flush
- - 加载是否 pcall 容错，单槽失败不影响全局
- - 货币/配额是否走专用原子接口
- - 是否有端到端往返测试