pan/heros

Files

panw 4235e3b776 refactor(game): 移除已弃用的事件常量

- 删除 UpdateHero 和 UpdateFightHero 事件
- 移除 MISSION_UPDATE 事件常量
- 优化游戏事件枚举定义

2025-10-28 16:15:47 +08:00

17 KiB

Raw Blame History

云数据同步

**本文档引用的文件** - [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://build-templates/wechatgame/cloud_functions/cocos_cloud/config.json) - [deploy.md](file://build-templates/wechatgame/cloud_functions/cocos_cloud/deploy.md) - [wx.aip.d.ts](file://assets/script/game/wx_clound_client_api/wx.aip.d.ts) - [NetCode.json](file://assets/resources/config/game/NetCode.json)

简介

本项目实现了基于微信云开发的云数据同步解决方案，为Cocos Creator游戏提供云端用户数据存储与同步功能。系统采用前后端分离架构，通过云函数处理业务逻辑，确保数据安全性和一致性。

核心功能包括：

用户身份认证与自动创建
游戏进度数据的云端存储与获取
数据版本控制与冲突解决
错误处理与重试机制
安全性保障与权限控制

系统架构概览

graph TB
subgraph "客户端层"
Game[游戏客户端]
WxCloud[WxCloudApi.ts]
end
subgraph "微信云开发平台"
CloudFunc[云函数:cocos_cloud]
Database[(云数据库)]
Storage[(云存储)]
end
subgraph "微信服务器"
WXServer[微信服务器]
OpenID[用户OpenID]
end
Game --> WxCloud
WxCloud --> CloudFunc
CloudFunc --> Database
CloudFunc --> WXServer
WXServer --> OpenID
Database --> Storage

图表来源

核心组件分析

前端组件

WxCloudApi类 提供了统一的云服务接口，封装了微信云开发的复杂性，为游戏逻辑提供简洁的API。

主要特性：

单例模式设计，确保全局唯一实例
异步操作支持，避免阻塞主线程
泛型类型安全，提供完整的TypeScript支持
错误码标准化，便于统一处理

后端组件

云函数服务 运行在微信云开发环境中，负责处理所有业务逻辑和数据操作。

核心功能：

用户身份验证与自动注册
数据持久化与查询
权限控制与安全验证
错误日志记录与监控

章节来源

WxCloudApi.ts详解

类结构设计

classDiagram
class WxCloudApi {
+init(env : string) void
+login() Promise~CloudCallFunctionResult~
+save(gameData : any) Promise~CloudCallFunctionResult~
+get() Promise~CloudCallFunctionResult~
}
class CloudReturnType {
+code : number
+msg? : string
+data? : T
}
class CloudCallFunctionResult {
+result : T
+errMsg : string
+requestID : string
}
WxCloudApi --> CloudReturnType : "返回"
CloudReturnType --> CloudCallFunctionResult : "嵌套"

图表来源

init方法实现机制

功能描述： 初始化微信云开发环境，建立客户端与云服务的连接。

实现特点：

单次调用原则：每个游戏会话只需初始化一次
环境参数配置：支持动态环境切换
平台兼容性：条件调用，避免非微信环境下报错

调用时机： 游戏启动时，在主场景加载完成后调用。

login方法实现机制

功能描述： 执行用户登录流程，获取用户身份信息和游戏数据。

数据结构定义：

字段名	类型	描述	必填
code	number	状态码，200表示成功	是
msg	string	错误信息（失败时）	否
data	object	用户数据对象	是
data.openid	string	微信平台用户标识	是
data.regist_time	number	用户注册时间戳	是
data.game_data	object	游戏自定义数据	否

调用流程：

调用微信云函数cocos_cloud
传递cmd参数值为"login"
云函数验证用户身份
自动创建或查询用户记录
返回用户完整信息

save方法实现机制

功能描述： 将游戏数据保存到云端，实现数据的持久化存储。

数据结构：

接收任意类型的gameData对象
执行全覆盖式写入操作
支持复杂嵌套数据结构

安全特性：

数据完整性校验
操作日志记录
版本控制支持

get方法实现机制

功能描述： 从云端获取用户的最新游戏数据。

实现特点：

实时数据拉取
缓存策略支持
数据一致性保障

章节来源

WxCloudApi.ts

云函数服务端实现

服务端架构设计

sequenceDiagram
participant Client as 客户端
participant CloudFunc as 云函数
participant Database as 云数据库
participant WXServer as 微信服务器
Client->>CloudFunc : 调用云函数
CloudFunc->>WXServer : 获取用户OpenID
WXServer-->>CloudFunc : 返回用户标识
CloudFunc->>Database : 查询用户记录
Database-->>CloudFunc : 返回用户数据
alt 用户不存在
CloudFunc->>Database : 创建新用户记录
Database-->>CloudFunc : 返回新记录ID
end
CloudFunc->>Database : 执行数据操作
Database-->>CloudFunc : 返回操作结果
CloudFunc-->>Client : 返回处理结果

图表来源

index.js

getOrCreaterUser函数实现

功能描述： 核心用户管理逻辑，确保每个微信用户都有对应的数据库记录。

实现细节：

使用OpenID作为唯一标识符
自动检测用户是否存在
原子性操作保证数据一致性
异常处理机制

数据模型：

字段名	类型	描述	默认值
_openid	string	微信OpenID	必填
regist_time	number	注册时间戳	当前时间
game_data	object	游戏数据	{}

登录处理逻辑

流程分析：

身份验证：通过cloud.getWXContext()获取用户上下文
用户查询：根据OpenID查找用户记录
用户创建：如用户不存在则自动创建
数据返回：返回完整的用户信息

错误处理：

数据库连接失败
用户查询超时
记录创建失败

数据保存逻辑

操作流程：

数据验证：检查传入的游戏数据格式
用户确认：确保用户记录存在
数据更新：使用原子更新操作
结果反馈：返回操作统计信息

性能优化：

批量操作支持
索引优化
连接池管理

章节来源

index.js

数据流与调用流程

完整数据同步流程

flowchart TD
Start([游戏启动]) --> Init["WxCloudApi.init()"]
Init --> Login["WxCloudApi.login()"]
Login --> LoginSuccess{"登录成功?"}
LoginSuccess --> |否| LoginFail["显示登录错误"]
LoginSuccess --> |是| LoadGameData["加载用户数据"]
LoadGameData --> GameLoop["游戏主循环"]
GameLoop --> SaveCheck{"需要保存数据?"}
SaveCheck --> |否| GameLoop
SaveCheck --> |是| SaveData["WxCloudApi.save()"]
SaveData --> SaveSuccess{"保存成功?"}
SaveSuccess --> |否| Retry["重试机制"]
SaveSuccess --> |是| GameLoop
Retry --> RetryCount{"重试次数<3?"}
RetryCount --> |是| SaveData
RetryCount --> |否| SaveFail["保存失败处理"]
LoginFail --> End([结束])
SaveFail --> End
SaveSuccess --> End

图表来源

请求响应数据结构

登录请求：

// 请求格式
{
    cmd: "login"
}

// 响应格式
{
    code: 200,
    data: {
        openid: "wx_openid_string",
        regist_time: 1640995200000,
        game_data: {
            level: 10,
            coins: 1000,
            inventory: [...],
            achievements: {...}
        }
    }
}

保存请求：

// 请求格式
{
    cmd: "save",
    data: {
        level: 11,
        coins: 1200,
        inventory: [...],
        achievements: {...}
    }
}

// 响应格式
{
    code: 200,
    data: {
        errMsg: "document.update:ok",
        stats: {
            updated: 1
        }
    }
}

获取请求：

// 请求格式
{
    cmd: "get"
}

// 响应格式
{
    code: 200,
    data: {
        _id: "mongodb_document_id",
        _openid: "wx_openid_string",
        regist_time: 1640995200000,
        game_data: {...}
    }
}

错误处理与状态码

状态码定义

状态码	含义	处理方式	示例场景
200	成功	正常处理	登录成功、数据保存成功
-1	通用错误	重试或提示用户	网络超时、数据库错误
-2	命令未知	检查参数	云函数参数错误
-3	权限不足	提示授权	用户未授权

错误分类处理

网络错误：

连接超时：自动重试3次
断线重连：本地缓存待发送数据
网络恢复：批量同步缓存数据

业务错误：

用户不存在：触发重新登录
数据冲突：采用最后修改时间策略
权限验证失败：引导用户重新授权

系统错误：

云函数异常：降级到本地存储
数据库不可用：启用离线模式
服务端维护：显示维护公告

章节来源

前端调用示例

基础使用示例

// 初始化云服务
WxCloudApi.init('your-cloud-env');

// 用户登录
async function handleLogin() {
    try {
        const result = await WxCloudApi.login();
        
        if (result.result.code === 200) {
            const userData = result.result.data;
            console.log('登录成功:', userData);
            // 更新游戏状态
            game.user = userData;
            loadGameProgress(userData.game_data);
        } else {
            console.error('登录失败:', result.result.msg);
            showErrorMessage(result.result.msg);
        }
    } catch (error) {
        console.error('登录异常:', error);
        showNetworkError();
    }
}

// 保存游戏进度
async function saveGameProgress(progressData: any) {
    try {
        const result = await WxCloudApi.save(progressData);
        
        if (result.result.code === 200) {
            console.log('保存成功');
            game.lastSyncTime = Date.now();
        } else {
            console.error('保存失败:', result.result.msg);
            // 触发重试机制
            scheduleRetry(() => saveGameProgress(progressData));
        }
    } catch (error) {
        console.error('保存异常:', error);
        scheduleRetry(() => saveGameProgress(progressData));
    }
}

高级使用模式

批量操作：

async function batchSaveOperations(operations: Array<{type: string, data: any}>) {
    for (const op of operations) {
        switch (op.type) {
            case 'progress':
                await saveGameProgress(op.data);
                break;
            case 'achievement':
                await saveAchievement(op.data);
                break;
        }
    }
}

数据同步策略：

class SyncManager {
    private pendingSaves: Array<any> = [];
    
    async queueSave(data: any) {
        this.pendingSaves.push({
            data,
            timestamp: Date.now(),
            retryCount: 0
        });
        await this.processQueue();
    }
    
    private async processQueue() {
        while (this.pendingSaves.length > 0) {
            const item = this.pendingSaves[0];
            try {
                await WxCloudApi.save(item.data);
                this.pendingSaves.shift();
            } catch (error) {
                if (item.retryCount < 3) {
                    item.retryCount++;
                    await new Promise(resolve => setTimeout(resolve, 1000 * item.retryCount));
                } else {
                    // 移除失败项，可能需要手动处理
                    this.pendingSaves.shift();
                }
            }
        }
    }
}

部署与配置

云函数部署流程

步骤1：环境准备

# 进入云函数目录
cd build-templates/wechatgame/cloud_functions/cocos_cloud

# 安装依赖
npm install

# 验证安装
ls node_modules/wx-server-sdk

步骤2：配置环境 编辑config.json文件：

{
  "permissions": {
    "openapi": [
      // 可选的开放API列表
    ]
  }
}

步骤3：部署云函数 使用微信开发者工具：

打开项目根目录
选择云函数cocos_cloud
点击上传并部署
验证部署状态

环境配置

config.json配置项：

配置项	类型	描述	示例值
permissions.openapi	Array	公开API权限列表	[]
database	string	数据库环境ID	"prod-123456"
storage	string	存储环境ID	"storage-123456"

环境变量：

DYNAMIC_CURRENT_ENV：动态环境变量
OPENID：用户唯一标识
APP_ID：小程序APP ID

章节来源

安全性与最佳实践

权限控制机制

_openid权限控制：

每个用户只能访问自己的数据
数据操作必须通过云函数验证
防止跨用户数据泄露

数据加密策略：

敏感数据本地加密
传输过程使用HTTPS
定期轮换加密密钥

性能优化建议

数据库优化：

// 在getOrCreaterUser函数中添加索引
await db.collection(user_db_name)
    .where({ _openid: openid })
    .orderBy('regist_time', 'desc')
    .limit(1)
    .get();

缓存策略：

客户端缓存最近使用的数据
设置合理的缓存过期时间
实现智能预加载机制

监控与日志

关键指标监控：

API调用成功率
平均响应时间
错误率分布
用户活跃度

日志记录：

// 在index.js中添加详细日志
console.log(`[${new Date().toISOString()}] User action:`, {
    action: cmd,
    openid: wxContext.OPENID,
    timestamp: Date.now(),
    duration: Date.now() - startTime
});

故障排除与优化

常见问题解决

问题1：云函数部署失败

# 错误：Cannot find module 'wx-server-sdk'
# 解决方案：
npm install wx-server-sdk --save

问题2：登录失败

检查微信登录状态
验证云环境配置
确认用户授权范围

问题3：数据同步延迟

优化网络连接
减少不必要的同步
实现增量同步机制

性能监控

关键性能指标：

API响应时间：<200ms
成功率：>99%
错误率：<0.1%
并发处理能力：>1000 QPS

监控告警：

// 添加性能监控
const performanceMonitor = {
    recordApiCall(apiName, duration, success) {
        // 发送到监控系统
        sendMetrics({
            apiName,
            duration,
            success,
            timestamp: Date.now()
        });
    }
};

数据一致性保障

多副本同步：

主从复制机制
冲突检测算法
自动修复机制

事务处理：

// 使用云数据库事务
const transaction = await db.startTransaction();
try {
    // 执行多个操作
    await transaction.collection('users')
        .doc(userId)
        .update({ data: { balance: newBalance } });
    
    await transaction.collection('transactions')
        .add({ data: transactionData });
    
    await transaction.commit();
} catch (error) {
    await transaction.rollback();
}

总结

本云数据同步解决方案提供了完整的微信云开发集成方案，具有以下优势：

技术优势：

基于微信原生云开发，稳定性高
TypeScript类型安全，开发效率高
异步操作支持，用户体验好
完善的错误处理机制

业务价值：

用户数据云端存储，防止丢失
跨设备数据同步，提升用户体验
自动备份机制，降低运营成本
安全可靠，符合隐私保护要求

扩展性：

支持多种数据类型存储
易于添加新的业务功能
可扩展的权限控制系统
灵活的配置管理机制

通过合理使用这套云数据同步方案，开发者可以构建稳定可靠的云端游戏数据管理系统，为用户提供优质的云端游戏体验。

17 KiB Raw Blame History Unescape Escape

云数据同步

目录

简介

系统架构概览

核心组件分析

前端组件

后端组件

WxCloudApi.ts详解

类结构设计

init方法实现机制

login方法实现机制

save方法实现机制

get方法实现机制

云函数服务端实现

服务端架构设计

getOrCreaterUser函数实现

登录处理逻辑

数据保存逻辑

数据流与调用流程

完整数据同步流程

请求响应数据结构

错误处理与状态码

状态码定义

错误分类处理

前端调用示例

基础使用示例

高级使用模式

部署与配置

云函数部署流程

环境配置

安全性与最佳实践

权限控制机制

性能优化建议

监控与日志

故障排除与优化

常见问题解决

性能监控

数据一致性保障

总结

17 KiB

Raw Blame History