11 KiB
数据存储系统
**本文档引用文件** - [storage.md](file://doc/core/common/storage.md) - [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts) - [config.json](file://assets/resources/config.json) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts) - [BoxSet.ts](file://assets/script/game/common/config/BoxSet.ts) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts) - [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts) - [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)目录
本地数据持久化机制
本游戏项目采用Oops Framework提供的本地存储模块，该模块封装了Cocos Creator引擎的sys.localStorage对象，实现了跨平台的本地数据存储功能。存储系统不仅支持基础的增删改查操作，还集成了数据加密和多用户数据区分功能，确保玩家数据的安全性和独立性。
系统通过oops.storage接口提供统一的数据访问方法，所有数据最终存储在设备本地，同时支持与云端数据同步的混合存储策略。本地存储主要用于保存玩家配置、语言设置、游戏进度等关键数据，确保即使在离线状态下也能正常访问游戏内容。
Section sources
初始化与用户数据区分
初始化本地存储加密
本地存储加密通过oops.storage.init()方法进行初始化，该方法需要传入加密密钥和初始化向量（IV）两个参数。在项目启动时，系统会从配置文件中读取加密参数并完成初始化。
sequenceDiagram
participant 游戏启动
participant Root组件
participant 存储系统
participant 配置文件
游戏启动->>Root组件 : onLoad()
Root组件->>配置文件 : 加载config.json
配置文件-->>Root组件 : 返回配置数据
Root组件->>存储系统 : oops.storage.init(key, vi)
存储系统-->>Root组件 : 初始化完成
Diagram sources
区分用户数据
通过oops.storage.setUser()方法可以为不同用户设置唯一标识，从而实现多账号数据隔离。系统使用用户ID作为数据存储的命名空间，避免不同账号之间的数据覆盖问题。
当用户登录时，系统会调用此方法设置当前用户ID，后续的所有数据操作都将基于该用户ID进行。这对于支持多账号切换的游戏尤为重要，确保每个玩家的游戏进度和设置都能独立保存。
Section sources
基本操作方法
本地存储系统提供了一套完整的数据操作API，包括设置、获取、删除和清空等基本操作。
设置数据
使用oops.storage.set(key, value)方法可以将指定键值对保存到本地存储中。该方法接受两个参数：键名和值。值可以是字符串、数字、布尔值或对象等数据类型。
flowchart TD
A[开始] --> B["oops.storage.set(key, value)"]
B --> C{数据类型检查}
C --> |基本类型| D[直接存储]
C --> |对象类型| E[JSON序列化]
E --> F[加密处理]
F --> G[保存到localStorage]
G --> H[结束]
Diagram sources
获取数据
通过oops.storage.get(key)方法可以从本地存储中读取指定键的数据。如果键不存在，则返回null。该方法会自动处理数据的解密和反序列化过程，向调用者返回原始数据类型。
删除数据
oops.storage.remove(key)方法用于删除指定键的数据。执行后，该键对应的数据将从本地存储中永久移除。
清空存储
oops.storage.clear()方法会清空当前用户的所有本地存储数据。这是一个危险操作，通常只在用户注销或重置游戏时使用。
Section sources
调试与发布模式差异
本地存储系统在调试模式和发布模式下表现出不同的行为特征，这是为了平衡开发效率和生产环境安全性的设计。
调试模式
在调试模式下，系统不会对存储数据进行加密，所有数据以明文形式保存。这一设计便于开发者调试时直接查看和修改存储内容，提高了开发效率。开发者可以通过浏览器的开发者工具直接查看localStorage中的数据内容。
发布模式
在发布模式下，系统会自动启用数据加密功能。所有写入本地存储的数据都会经过加密处理，读取时再进行解密。这种机制有效防止了玩家通过直接修改存储文件来作弊的行为，保护了游戏的公平性。
加密算法基于项目配置文件中定义的密钥和IV参数，确保了加密过程的一致性和安全性。
graph TB
A[数据操作] --> B{运行模式}
B --> |调试模式| C[明文存储]
B --> |发布模式| D[加密存储]
C --> E[便于调试]
D --> F[防止篡改]
Diagram sources
数据安全策略
加密机制
系统采用对称加密算法保护本地存储数据，加密密钥和IV参数定义在assets/resources/config.json配置文件中。这种集中管理的方式便于统一维护和更新加密参数。
项目依赖crypto-es库实现加密功能，这是一个轻量级的JavaScript加密库，支持多种加密算法。通过在package.json中声明依赖，确保了加密库的版本一致性。
防篡改机制
除了数据加密外，系统还通过用户ID区分机制防止数据篡改。每个用户的数据都有独立的存储空间，避免了通过修改用户ID来访问他人数据的可能性。
对于关键数据，系统建议采用双重保护策略：既在本地加密存储，又在云端备份。当检测到本地数据异常时，可以从云端恢复，确保玩家数据不丢失。
Section sources
存储需求与应用示例
碰撞分组配置存储
BoxSet.ts文件定义了游戏中的碰撞分组配置，这些配置数据可以通过本地存储系统进行持久化保存。玩家可以自定义碰撞规则，系统将这些设置保存到本地，确保每次启动游戏时都能恢复个性化配置。
classDiagram
class BoxSet {
+SKILL_TAG : number
+ATK_RANGE : number
+DEFAULT : number
+MONSTER : number
+HERO : number
+PLAYER : number
+BOSS : number
+BOX_WIDTH : number
+BOX_HEIGHT : number
}
class StorageManager {
+setCollisionConfig(config)
+getCollisionConfig()
+saveToLocalStorage()
+loadFromLocalStorage()
}
StorageManager --> BoxSet : "使用"
Diagram sources
游戏进度管理
系统通过SingletonModuleComp.ts管理游戏核心数据，包括玩家金币、英雄列表和出战阵容等。这些数据在游戏运行时存储在内存中，同时定期同步到本地存储。
当玩家完成游戏或退出应用时，系统会自动保存当前进度。下次启动游戏时，先从本地存储加载数据，再根据需要从云端同步最新状态，实现了本地与云端的数据一致性。
Section sources
异常处理与最佳实践
数据序列化
在存储复杂数据类型时，需要先进行序列化处理。系统推荐使用JSON.stringify()将对象转换为字符串，然后再调用存储方法。读取数据时，使用JSON.parse()进行反序列化。
flowchart LR
A[原始数据] --> B[JSON.stringify]
B --> C[加密]
C --> D[存储]
D --> E[读取]
E --> F[解密]
F --> G[JSON.parse]
G --> H[恢复数据]
Diagram sources
异常处理
在进行数据操作时，必须考虑各种异常情况，如存储空间不足、数据损坏、加密失败等。系统建议采用try-catch结构包裹存储操作，并提供相应的错误处理机制。
对于关键数据的保存操作，建议实现事务性处理：先写入临时位置，验证成功后再替换原数据，确保数据完整性。
Section sources
跨设备同步与本地缓存
云端同步机制
系统实现了本地存储与微信云开发的集成，通过WxCloudApi.ts提供的接口实现数据云端同步。在微信客户端环境下，游戏启动时会自动从云端加载最新数据；在非微信环境下，则使用本地调试数据。
sequenceDiagram
participant 客户端
participant 云端
participant 本地存储
客户端->>云端 : login()
云端-->>客户端 : 用户数据
客户端->>本地存储 : 保存云端数据
本地存储-->>客户端 : 确认
客户端->>云端 : save(gameData)
云端-->>客户端 : 保存结果
Diagram sources
本地缓存协调
系统采用"本地优先，云端同步"的策略。日常游戏过程中主要使用本地存储，定期或在关键节点将数据同步到云端。这样既保证了游戏性能，又实现了数据备份。
当玩家在不同设备上登录同一账号时，系统会优先使用云端最新数据，然后与本地数据进行合并，确保游戏进度的一致性。对于冲突数据，采用"最后写入获胜"的策略。
Section sources