pixelheros/.qoder/repowiki/zh/content/数据管理/本地存储管理.md

本地存储管理

**本文档引用文件** - [config.json](file://assets/resources/config.json) - [Oops.ts](file://extensions/oops-plugin-framework/assets/core/Oops.ts) - [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts) - [StorageManager.ts](file://extensions/oops-plugin-framework/assets/core/common/storage/StorageManager.ts) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts) - [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts) - [Main.ts](file://assets/script/Main.ts)

目录

1. 简介
2. 项目结构
3. 核心配置项解析
4. 本地数据加密机制
5. 配置加载与初始化流程
6. 本地缓存与云端数据策略
7. 性能与网络配置
8. 故障处理机制
9. 结论

简介

本文档深入解析基于 Cocos 引擎的 heros 项目中的本地存储机制。重点围绕 config.json 文件中的核心配置项，包括 version、package、localDataKey、localDataIv、httpServer、httpTimeout 和 frameRate 的作用、加载时机及使用场景。文档详细阐述了基于 crypto-es 库的本地数据加密存储方案的设计思路，以及如何通过 localDataKey 和 localDataIv 实现数据保护。同时，分析了本地缓存与云端数据的优先级策略，以及在离线模式下的容错处理机制。

Section sources

• config.json

项目结构

项目采用模块化设计，主要结构如下：

• assets/resources/config.json：核心配置文件，包含游戏版本、包名、加密密钥、网络地址等全局配置。
• assets/script/：存放所有 TypeScript 脚本，其中 game/initialize/ 是游戏初始化逻辑的核心。
• extensions/oops-plugin-framework/：项目所依赖的 Oops 框架，提供了本地存储、网络、ECS 等核心功能的封装。
• assets/resources/language/json/：多语言资源文件。
• build-templates/wechatgame/cloud_functions/：微信云函数相关配置。

Section sources

• config.json
• Main.ts

核心配置项解析

config.json 文件位于 assets/resources/ 目录下，是整个游戏的配置中心。其 config 对象下的各个字段具有明确的用途。

{
    "config": {
        "version": "1.0.0",
        "package": "com.oops.game",
        "localDataKey": "oops",
        "localDataIv": "framework",
        "httpServer": "http://192.168.0.150/main/",
        "httpTimeout": 10000,
        "frameRate": 60
    }
}

• version: 标识当前游戏的版本号。此信息可用于版本控制、热更新判断以及与云端数据进行兼容性校验。
• package: 定义游戏的包标识符，遵循反向域名命名规则。在发布到应用商店或进行平台集成时，此标识符必须全局唯一。
• localDataKey: 本地数据加密所使用的密钥（Key）。该密钥与 localDataIv 一起，作为 crypto-es 库进行 AES 加密的参数，确保存储在用户设备上的数据安全。
• localDataIv: 本地数据加密所使用的初始化向量（Initialization Vector）。它增加了加密的随机性，即使相同的数据在不同时间加密，其密文也会不同，从而提高安全性。
• httpServer: 指定 HTTP 请求的服务器基础地址。所有通过 oops.http 模块发起的请求，其 URL 都会以此地址为前缀。
• httpTimeout: 设置 HTTP 请求的超时时间（单位：毫秒）。当网络请求超过此时间仍未收到响应时，将被视为失败，防止应用因网络问题而长时间无响应。
• frameRate: 定义游戏的帧率，即每秒渲染的帧数。较高的帧率（如 60）能提供更流畅的视觉体验，但对设备性能要求更高；较低的帧率（如 30）则更省电，适合性能较弱的设备。

Section sources

• config.json
• Root.ts

本地数据加密机制

项目的本地数据加密方案基于 crypto-es 库实现，由 Oops 框架的 StorageManager 类进行封装。

设计思路

1. 依赖库：项目通过 package.json 明确依赖了 crypto-es 库，这是一个轻量级的 JavaScript 加密库，支持 AES 等多种加密算法。
2. 框架集成：Oops 框架在 Root.ts 的 onLoad 方法中，通过 oops.config.game 读取 config.json 中的 localDataKey 和 localDataIv，并调用 oops.storage.init() 方法进行初始化。
3. 条件加密：根据 Oops 框架的设计，在开发调试模式（DEBUG 为 true）下，数据以明文形式存储，便于开发者调试。而在发布模式下，数据会自动使用 AES 算法进行加密后存储。

加密实现

StorageManager 类在初始化后，会拦截所有对 sys.localStorage 的读写操作。当调用 set 方法存储数据时，它会：

1. 将 JavaScript 对象序列化为 JSON 字符串。
2. 使用 localDataKey 作为密钥，localDataIv 作为初始化向量，通过 crypto-es 的 AES 算法对字符串进行加密。
3. 将加密后的密文（通常为 Base64 编码）存储到 localStorage 中。

当调用 get 方法读取数据时，流程则相反：

1. 从 localStorage 中读取密文。
2. 使用相同的密钥和初始化向量进行解密。
3. 将解密后的明文 JSON 字符串反序列化为 JavaScript 对象并返回。

flowchart TD
A[调用 oops.storage.set(key, value)] --> B[序列化为JSON]
B --> C[使用localDataKey和localDataIv进行AES加密]
C --> D[Base64编码]
D --> E[存入localStorage]
F[调用 oops.storage.get(key)] --> G[从localStorage读取]
G --> H[Base64解码]
H --> I[使用localDataKey和localDataIv进行AES解密]
I --> J[反序列化为对象]
J --> K[返回数据]

Diagram sources

• config.json
• Root.ts
• StorageManager.ts

Section sources

• package.json
• Root.ts
• Oops.ts

配置加载与初始化流程

游戏的配置加载和初始化是一个有序的过程，由 Main.ts 和 Root.ts 共同驱动。

流程图

sequenceDiagram
participant Main as Main.ts
participant Root as Root.ts
participant Config as config.json
participant Storage as StorageManager
participant Initialize as Initialize.ts
Main->>Root : director.loadScene("main")
Root->>Root : onLoad()
Root->>Root : 加载config.json资源
Root->>Root : 解析JsonAsset
loop 初始化框架模块
Root->>Root : oops.config.game = new GameConfig(config)
Root->>Root : oops.http.server = oops.config.game.httpServer
Root->>Root : oops.http.timeout = oops.config.game.httpTimeout
Root->>Storage : oops.storage.init(localDataKey, localDataIv)
Root->>Root : game.frameRate = oops.config.game.frameRate
end
Root->>Root : enabled = true
Root->>Root : init() 和 run()
Root->>Initialize : smc.initialize = ecs.getEntity<Initialize>(Initialize)
Initialize->>Initialize : protected init()
Initialize->>Initialize : loadCustom -> loadLanguage
Initialize->>Storage : oops.storage.get("language")
alt 语言存在
Initialize->>Initialize : 使用存储的语言
else 语言不存在
Initialize->>Initialize : 默认设为"zh"
Initialize->>Storage : oops.storage.set("language", "zh")
end
Initialize->>Initialize : 继续加载公共资源和游戏数据

Diagram sources

• Main.ts
• Root.ts
• Initialize.ts

Section sources

• Main.ts
• Root.ts
• Initialize.ts

本地缓存与云端数据策略

项目采用了一套混合数据存储策略，结合了本地缓存和云端同步，以平衡性能、用户体验和数据安全。

优先级策略

1. 本地优先（读取）：游戏启动时，会优先从本地存储中读取用户偏好设置，如语言选择 (oops.storage.get("language"))。这确保了即使在离线状态下，用户也能获得个性化的体验。
2. 云端优先（写入与同步）：对于核心的游戏进度数据（如金币、英雄信息、出战阵容），项目优先使用云端存储。在微信客户端中，通过 WxCloudApi 与微信云函数交互，实现数据的持久化和跨设备同步。

数据同步流程

• 初始化同步：在 Initialize.ts 的 loadGameDataUnified 方法中，程序首先判断是否为微信客户端。如果是，则调用 loadFromCloud()，通过 WxCloudApi.login() 获取云端数据，并用 overrideLocalDataWithRemote() 方法覆盖本地的 smc (SingletonModuleComp) 单例数据。
• 运行时同步：在游戏运行过程中，当用户数据发生变化（如获得金币、升级英雄），会立即调用 WxCloudApi.save() 将最新数据保存到云端，确保数据的实时性和安全性。

graph TD
A[游戏启动] --> B{是否为微信客户端?}
B -- 是 --> C[调用 WxCloudApi.login()]
C --> D{登录成功?}
D -- 是 --> E[获取云端数据]
E --> F[覆盖本地 smc 数据]
D -- 否 --> G[使用本地调试数据]
B -- 否 --> G
F --> H[进入游戏]
G --> H

Diagram sources

• Initialize.ts
• SingletonModuleComp.ts
• WxCloudApi.ts

Section sources

• Initialize.ts
• SingletonModuleComp.ts
• WxCloudApi.ts

性能与网络配置

除了数据存储，config.json 中的配置也直接影响游戏的性能和网络行为。

• frameRate 对性能的影响：frameRate 设置为 60，意味着游戏引擎会尽量每秒更新和渲染 60 帧。这能提供非常流畅的动画效果，但会持续占用较高的 CPU 和 GPU 资源，可能导致设备发热和耗电加快。开发者需要在流畅度和性能消耗之间做出权衡，对于性能要求不高的场景，可以考虑降低此值。
• httpServer 与 httpTimeout 的用途：httpServer 定义了所有 HTTP 请求的根地址，实现了请求地址的集中管理，便于在开发、测试和生产环境之间切换。httpTimeout 是一个关键的容错配置，它防止了因网络延迟或服务器无响应而导致的 UI 卡死。当请求超时后，应用可以捕获错误并给出友好的提示，提升用户体验。

Section sources

• Root.ts
• config.json

故障处理机制

项目在数据处理和网络通信方面设计了多层次的容错机制。

• 本地存储容错：在 Initialize.ts 中读取语言设置时，代码明确检查了 oops.storage.get("language") 的返回值是否为 null 或空字符串。如果不存在，则使用默认值 "zh" 并将其写回存储。这是一种典型的“降级”策略，确保了关键配置的可用性。
• 云端数据容错：loadFromCloud 和 loadFromLocalDebug 方法都使用了 try-catch 语句包裹。当云端登录或数据获取失败时，程序会捕获异常，记录错误日志，并尝试使用本地调试数据作为后备方案，避免游戏因数据加载失败而无法启动。
• 网络请求容错：httpTimeout 配置本身就是一种网络容错。此外，WxCloudApi 的调用通常会检查返回的 code 字段（如 200 表示成功），并根据不同的错误码（如 -3 参数错误，-6 资源不足）执行相应的处理逻辑，例如提示用户或回滚操作。

Section sources

• Initialize.ts
• WxCloudApi.ts

结论

该项目的本地存储机制设计完善，通过 config.json 实现了配置的集中化管理。利用 Oops 框架和 crypto-es 库，实现了安全的本地数据加密。项目采用了“本地缓存 + 云端同步”的混合策略，既保证了离线可用性和启动速度，又确保了核心数据的安全与跨设备同步。整个初始化流程清晰，配置项的加载和应用时机合理，并且在各个环节都考虑了容错处理，构建了一个健壮、可靠的游戏数据管理方案。