330 lines
12 KiB
Markdown
330 lines
12 KiB
Markdown
# 数据管理
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [en.json](file://assets/resources/language/json/en.json)
|
||
- [zh.json](file://assets/resources/language/json/zh.json)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [Main.ts](file://assets/script/Main.ts)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概述](#架构概述)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
本文档详细说明了游戏项目中的数据管理机制，涵盖本地配置、多语言支持与微信云同步功能。文档基于WxCloudApi.ts文件详细说明了与微信云开发的集成方式，包括用户数据上传、下载与冲突处理策略。同时分析了index.js云函数的部署结构与接口定义，解释了config.json中全局配置项的作用及其加载时机，并结合en.json和zh.json说明了多语言系统的实现机制与文本替换流程。
|
||
|
||
## 项目结构
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[assets] --> B[resources]
|
||
A --> C[script]
|
||
B --> D[config]
|
||
B --> E[language]
|
||
B --> F[config.json]
|
||
D --> G[game]
|
||
D --> H[map]
|
||
E --> I[json]
|
||
I --> J[en.json]
|
||
I --> K[zh.json]
|
||
C --> L[game]
|
||
L --> M[wx_clound_client_api]
|
||
M --> N[WxCloudApi.ts]
|
||
M --> O[USAGE.md]
|
||
```
|
||
|
||
**图示来源**
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [en.json](file://assets/resources/language/json/en.json)
|
||
- [zh.json](file://assets/resources/language/json/zh.json)
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
|
||
**本节来源**
|
||
- [assets/resources/config.json](file://assets/resources/config.json)
|
||
- [assets/resources/language/json/en.json](file://assets/resources/language/json/en.json)
|
||
- [assets/resources/language/json/zh.json](file://assets/resources/language/json/zh.json)
|
||
|
||
## 核心组件
|
||
|
||
本文档的核心组件包括微信云同步机制、多语言支持系统和本地配置管理。WxCloudApi.ts提供了与微信云开发平台的集成接口，实现了用户数据的云端存储与同步功能。config.json文件定义了游戏的全局配置参数，包括版本信息、包名、本地数据加密密钥等。多语言系统通过en.json和zh.json两个语言包文件实现，支持英文和中文两种语言的动态切换。
|
||
|
||
**本节来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [en.json](file://assets/resources/language/json/en.json)
|
||
- [zh.json](file://assets/resources/language/json/zh.json)
|
||
|
||
## 架构概述
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 客户端 as 客户端应用
|
||
participant WxCloudApi as WxCloudApi
|
||
participant 云函数 as 云函数(index.js)
|
||
participant 数据库 as 云数据库
|
||
客户端->>WxCloudApi : 初始化云环境
|
||
WxCloudApi->>云函数 : 调用云函数初始化
|
||
云函数-->>WxCloudApi : 环境初始化完成
|
||
客户端->>WxCloudApi : 登录请求
|
||
WxCloudApi->>云函数 : 调用login命令
|
||
云函数->>数据库 : 查询用户数据
|
||
数据库-->>云函数 : 返回用户数据
|
||
云函数-->>WxCloudApi : 返回登录结果
|
||
WxCloudApi-->>客户端 : 返回用户数据
|
||
客户端->>WxCloudApi : 保存游戏数据
|
||
WxCloudApi->>云函数 : 调用save命令
|
||
云函数->>数据库 : 更新用户数据
|
||
数据库-->>云函数 : 返回更新结果
|
||
云函数-->>WxCloudApi : 返回保存结果
|
||
WxCloudApi-->>客户端 : 返回操作结果
|
||
```
|
||
|
||
**图示来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
|
||
**本节来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
|
||
## 详细组件分析
|
||
|
||
### 微信云同步机制分析
|
||
|
||
#### 云API客户端实现
|
||
```mermaid
|
||
classDiagram
|
||
class WxCloudApi {
|
||
+static init(env : string)
|
||
+static async login() : Promise~CloudCallFunctionResult~
|
||
+static async save(gameData : any) : Promise~CloudCallFunctionResult~
|
||
+static async get() : Promise~CloudCallFunctionResult~
|
||
}
|
||
class CloudReturnType {
|
||
+code : number
|
||
+msg? : string
|
||
+data? : T
|
||
}
|
||
WxCloudApi --> CloudReturnType : 使用
|
||
```
|
||
|
||
**图示来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
|
||
#### 云函数服务端实现
|
||
```mermaid
|
||
flowchart TD
|
||
Start([云函数入口]) --> Init["初始化云环境"]
|
||
Init --> CheckCmd["检查命令类型"]
|
||
CheckCmd --> Login{"命令是login?"}
|
||
Login --> |是| HandleLogin["处理登录请求"]
|
||
Login --> |否| Save{"命令是save?"}
|
||
Save --> |是| HandleSave["处理保存请求"]
|
||
Save --> |否| Get{"命令是get?"}
|
||
Get --> |是| HandleGet["处理获取请求"]
|
||
Get --> |否| ReturnError["返回未知命令错误"]
|
||
HandleLogin --> ReturnSuccess["返回用户数据"]
|
||
HandleSave --> ValidateData["验证数据"]
|
||
ValidateData --> UpdateDB["更新数据库"]
|
||
UpdateDB --> CheckResult["检查更新结果"]
|
||
CheckResult --> |成功| ReturnSuccess
|
||
CheckResult --> |失败| ReturnFail["返回保存失败"]
|
||
HandleGet --> ReturnUserData["返回用户数据"]
|
||
ReturnSuccess --> End([函数结束])
|
||
ReturnFail --> End
|
||
ReturnError --> End
|
||
```
|
||
|
||
**图示来源**
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
|
||
**本节来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
|
||
### 多语言系统分析
|
||
|
||
#### 语言包结构
|
||
```mermaid
|
||
erDiagram
|
||
zh_json {
|
||
string common_prompt_ok PK
|
||
string common_prompt_cancal
|
||
string common_prompt_title_sys
|
||
string common_prompt_content
|
||
string btn_demo_lang
|
||
string loading_load_json
|
||
string role_name
|
||
string role_lv
|
||
string role_hp
|
||
}
|
||
en_json {
|
||
string common_prompt_ok PK
|
||
string common_prompt_cancal
|
||
string common_prompt_title_sys
|
||
string common_prompt_content
|
||
string btn_demo_lang
|
||
string loading_load_json
|
||
string role_name
|
||
string role_lv
|
||
string role_hp
|
||
}
|
||
config_json ||--o{ zh_json : 包含
|
||
config_json ||--o{ en_json : 包含
|
||
```
|
||
|
||
**图示来源**
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [zh.json](file://assets/resources/language/json/zh.json)
|
||
- [en.json](file://assets/resources/language/json/en.json)
|
||
|
||
#### 语言系统初始化流程
|
||
```mermaid
|
||
flowchart TD
|
||
Start([初始化]) --> CheckStorage["检查本地存储"]
|
||
CheckStorage --> HasLang{"有语言设置?"}
|
||
HasLang --> |是| UseStoredLang["使用存储的语言"]
|
||
HasLang --> |否| SetDefault["设置默认语言为zh"]
|
||
SetDefault --> StoreLang["存储语言设置"]
|
||
UseStoredLang --> SetLangPath["设置语言包路径"]
|
||
StoreLang --> SetLangPath
|
||
SetLangPath --> LoadLangFont["加载语言字体"]
|
||
LoadLangFont --> LoadLangRes["加载语言资源"]
|
||
LoadLangRes --> Complete([初始化完成])
|
||
```
|
||
|
||
**图示来源**
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [config.json](file://assets/resources/config.json)
|
||
|
||
**本节来源**
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [en.json](file://assets/resources/language/json/en.json)
|
||
- [zh.json](file://assets/resources/language/json/zh.json)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
|
||
### 本地配置管理分析
|
||
|
||
#### 全局配置结构
|
||
```mermaid
|
||
classDiagram
|
||
class Config {
|
||
+version : string
|
||
+package : string
|
||
+localDataKey : string
|
||
+localDataIv : string
|
||
+httpServer : string
|
||
+httpTimeout : number
|
||
+frameRate : number
|
||
+language : LanguageConfig
|
||
}
|
||
class LanguageConfig {
|
||
+type : string[]
|
||
+path : PathConfig
|
||
}
|
||
class PathConfig {
|
||
+json : string
|
||
+texture : string
|
||
}
|
||
Config --> LanguageConfig : 包含
|
||
LanguageConfig --> PathConfig : 包含
|
||
```
|
||
|
||
**图示来源**
|
||
- [config.json](file://assets/resources/config.json)
|
||
|
||
#### 配置加载与数据同步流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 初始化 as Initialize
|
||
participant 存储 as oops.storage
|
||
participant 语言 as oops.language
|
||
participant 云API as WxCloudApi
|
||
初始化->>存储 : 获取语言设置
|
||
存储-->>初始化 : 返回语言值
|
||
初始化->>初始化 : 判断语言值是否存在
|
||
初始化->>存储 : 设置默认语言为zh
|
||
初始化->>语言 : 设置语言包路径
|
||
初始化->>语言 : 加载语言资源
|
||
初始化->>初始化 : 判断是否为微信客户端
|
||
初始化->>云API : 初始化云环境
|
||
云API->>微信云 : 初始化环境
|
||
微信云-->>云API : 环境初始化完成
|
||
云API-->>初始化 : 初始化完成
|
||
初始化->>云API : 调用登录接口
|
||
云API->>微信云 : 调用云函数
|
||
微信云->>数据库 : 查询用户数据
|
||
数据库-->>微信云 : 返回用户数据
|
||
微信云-->>云API : 返回登录结果
|
||
云API-->>初始化 : 返回用户数据
|
||
初始化->>smc : 更新云端数据
|
||
```
|
||
|
||
**图示来源**
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
|
||
**本节来源**
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [Main.ts](file://assets/script/Main.ts)
|
||
|
||
## 依赖分析
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[WxCloudApi.ts] --> B[index.js]
|
||
A --> C[微信云开发SDK]
|
||
D[Initialize.ts] --> A
|
||
D --> E[config.json]
|
||
F[Main.ts] --> D
|
||
G[LoadingViewComp.ts] --> H[语言系统]
|
||
H --> E
|
||
I[en.json] --> E
|
||
J[zh.json] --> E
|
||
B --> K[云数据库]
|
||
style A fill:#f9f,stroke:#333
|
||
style B fill:#bbf,stroke:#333
|
||
style D fill:#f96,stroke:#333
|
||
style E fill:#9f9,stroke:#333
|
||
```
|
||
|
||
**图示来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [config.json](file://assets/resources/config.json)
|
||
|
||
**本节来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [config.json](file://assets/resources/config.json)
|
||
|
||
## 性能考虑
|
||
数据管理机制在性能方面有以下考虑：首先，云同步操作采用异步方式执行，避免阻塞主线程影响游戏流畅度。其次，语言包资源采用按需加载策略，在游戏初始化阶段只加载必要的语言资源，减少启动时的内存占用。再者，本地配置数据在游戏启动时一次性加载到内存中，后续使用时直接从内存读取，提高访问效率。最后，云函数设计遵循最小权限原则，每个函数只完成单一功能，便于性能监控和优化。
|
||
|
||
## 故障排除指南
|
||
当遇到数据管理相关问题时，可参考以下排查步骤：首先检查网络连接是否正常，因为云同步功能依赖网络通信。其次查看控制台日志，云函数执行结果和错误信息都会输出到日志中。对于多语言显示问题，确认config.json中的语言配置是否正确，以及对应的语言包文件是否存在。如果云同步失败，检查WxCloudApi.init()方法是否正确初始化了云环境ID。对于本地配置加载问题，确保config.json文件格式正确且位于正确的资源路径下。
|
||
|
||
**本节来源**
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js)
|
||
- [config.json](file://assets/resources/config.json)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
|
||
## 结论
|
||
本文档全面分析了游戏项目的数据管理机制，涵盖了本地配置、多语言支持与微信云同步三大核心功能。通过WxCloudApi.ts与index.js的配合，实现了安全可靠的云端数据存储与同步。config.json文件提供了灵活的全局配置管理，支持版本控制、包名设置和性能参数调整。多语言系统通过en.json和zh.json两个语言包文件实现了中英文切换功能，提升了游戏的国际化支持能力。整体数据管理架构设计合理，既保证了数据的安全性和一致性，又兼顾了性能和用户体验。 |