WARNING

💡 模块名:GameHelper.ServerData

描述

服务器缓存模块，提供数据的注册(registerKeys)，手动上报，手动拉取，取消注册(cancelKeys)等功能。

• 支持提前预加载服务器上的数据，需要在调用GameHelper初始化时，添加saveServDataKeys属性。每一个需要提前预载的数据，就是该属性数组里的一个值。

• 支持直接注册好需要在一段时间内保存的数据（registerKeys），注册时写明需要保存的数据的 key。

• 注册完成后，每隔规定的时间，会自动上传一次被注册的数据，同时切换前后台时，也会自动上传一次数据。

• 注册期间，也可以手动调起上报所有的注册数据（updateKeys）。

• 当不再需要保存这些数据时，例如退出玩法的时候，注意调用取消注册的方法（cancelKeys），释放不必要的内存。

接入说明

• 与本地缓存（GameHelper.LocalStorage）与硬盘缓存（GameHelper.DiskStorage）使用方法类似，在需要保存数据时只需要调用保存数据方法uploadData进行数据保存，在需要获取数据时调用数据获取方法getData来获取。

• 由于服务器保存会使用到网络请求，对性能有一定影响，故不建议频繁调用。

• 建议只在游戏进入时拉取数据getData。

使用流程

预载入

如有预载入需求，在调用 GameHelper 初始化(GameHelper.init)方法时,在传入的对象添加saveServDataKeys属性。GameHelper执行初始化时就会提前载入好传入数组中所有 key 所对应的数据,保存到本地(使用GameHelper.DiskStorage进行保存)。

DANGER

⚡ 只有当本地缓存没有保存过对应 key 的数据时才会将预载入的数据保存到本地

//GameHelper初始化
GameHelper.init({
  //省略其他参数...
  saveServDataKeys: ["key1", "key2"], //提前预载的数据的key
});

获取数据

进入玩法后调用getData拉取服务器数据,拉取的数据会自动保存覆盖到本地(GameHelper.DiskStorage)。

传入对象可添加isCover属性来控制是否自动保存覆盖, 默认为true。

GameHelper.ServerData.getData({
  keys: "key1",
  isCover: false, //是否自动覆盖本地,默认为true
  success(res) {
    console.log("获取服务器缓存成功：", res);
  },
  fail(err) {
    console.log("获取服务器缓存失败：", err);
  },
});

上传数据

需要上传保存数据时, 调用uploadData进行保存。

传入对象可添加isCover属性来控制是否自动保存, 默认为false。

DANGER

⚡getData和uploadData传参对象中都可以传入isCover属性,但两个方法的isCover的默认值不同。

⚡getData的isCover默认值为true

⚡ uploadData的isCover默认值为false

GameHelper.ServerData.uploadData({
  data: {
    //保存的数据
    key1: 11,
    key2: 22,
  },
  isCover: true, //是否覆盖本地数据,默认为false
  success(res) {
    //成功上传回调
    console.log("上传成功");
  },
  fail(res) {
    //上传失败回调
    console.log("上传失败");
  },
});

注册

如有需要定时保存,可以直接注册好需要在一段时间内保存的数据（registerKeys

DANGER

⚡ 必要时需要取消注册(调用cancelKeys方法),否则会影响性能。

接口索引

方法

参数	类型	默认值	是否必填	说明
opt	RegisterParams	object	是	注册参数

RegisterParams

参数	类型	默认值	是否必填	说明
keysList	string[][]	/	是	需要注册的 key 集合
compare	(local: object,server: object) => void	/	否	新老数据对比方法回调
filter	(key: string, value: string) => boolean	/	否	数据上传筛选方法回调
success	(res: {mark:number,code:number}) => void	/	否	成功回调
fail	(err:{code: number}) => void	/	否	失败回调

返回值

无

描述

注册 keys，相同的 keys 仅需注册一次即可。被注册的 keys，会自动在指定间隔时间上传数据，以及前后台切换时，也会自动上传一次。

TIP

🧐 注意 keys 是二维字符串数组，一维存放需要的 key，二维表示一维的 keys 分别应用什么保存的频率。

🧐 例如：[['key1', 'key2'],['key3', 'key4'],['key5', 'key6'],['key7', 'key8']]

🧐 其中 key1，key2 应用高频的保存，key3，key4 的频率低一点，后面的更低一点。

🧐 但是具体的保存频率由后台的配置决定，也可能所有的项使用一个固定频率。

🧐 当前默认为统一 300s 的保存频率。

• 在注册完成前，传入compare回调函数，可以比对本地与服务器的数据，自行决定使用哪一部分的缓存。

compare是对比的回调，在获取到服务器的缓存后，会把注册的 keys 里的本地与服务器缓存的，以键值对的形式回调。业务层此时可以进行比较，判断是使用本地的缓存，还是使用服务器的缓存。

• 支持在每次上传数据前，对数据进行筛选，只有筛选通过的数据才能被上传。

• 成功回调里会回传一个mark属性，持有该mark才能在后续正常调用主动上传updateKeys和取消注册cancelKeys。

TIP

🧐 如果不传入对比函数，则以本地缓存为主。

🧐 也就是用本地缓存覆盖线上的缓存。

🧐 故接入时，最好自行做好本地/服务器缓存判断的逻辑

示例

GameHelper.ServerData.registerKeys({
  keysList: [
    ["key1", "key2"],
    ["key3", "key4"],
  ],
  compare(local, server) {
    //对比回调
    // 简单判断
    if (local.score >= server.score) {
      // 使用本地缓存
    } else {
      // 使用服务器缓存，用服务器的缓存覆盖本地的缓存
      GameHelper.DiskStorage.setItem(server);
    }
  },
  filter(key, value) {
    //筛选回调
    if (key === "bestScore") {
      // 仅bestScore大于1000时，该数据才会被记录在服务器上
      return value >= 1000;
    }
  },
  success(res) {
    //需要保存mark记号,在主动上传updateKeys和取消注册cancelKeys需要用到
    this.mark = res.mark;
    // 游戏正式初始化
    this.init();
  },
  fail(res) {
    console.log("获取服务器缓存失败：", res);
    this.init();
  },
});

---

取消指定 keys 的注册。

传入的 mark 是注册时返回的 mark。

参数	类型	默认值	是否必填	说明
mark	number	/	是	已注册 keys 的 mark

返回值

无

示例

//传入cancelKeys里的mark在调用registerKeys的success回调里获取
GameHelper.ServerData.cancelKeys(this.mark);

---

手动把注册的指定 keys 上传一次。

传入的 mark 是注册时返回的 mark。

参数	类型	默认值	是否必填	说明
mark	number	/	是	已注册 keys 的 mark

返回值

无

示例

//传入updateKeys里的mark在调用registerKeys的success回调里获取
GameHelper.ServerData.updateKeys(this.mark);

---

获取服务器上指定 keys 的缓存。

参数	类型	默认值	是否必填	说明
opt	GetParams	/	是	获取数据

GetParams

参数	类型	默认值	是否必填	说明
keys	string[] | string	/	是	获取的 keys,传入数组时,获取的值为所有传入 key 所对应的数据的集合
isCover	boolean	true	否	是否覆盖本地数据
success	(res: object) => voidstring	/	否	成功回调
fail	(err:{code: number, msg: string}) => void	/	否	失败回调

返回值

无

示例

GameHelper.ServerData.getData({
  keys: "key1",
  isCover: false, //是否自动覆盖本地,默认为true
  success(res) {
    console.log("获取服务器缓存成功：", res);
  },
  fail(err) {
    console.log("获取服务器缓存失败：", err);
  },
});

---

把指定的数据上传到服务器缓存上。

参数	类型	默认值	是否必填	说明
opt	UploadParams	/	是	上传参数

UploadParams

参数	类型	默认值	是否必填	说明
data	object	/	是	获取的 keys
isCover	boolean	false	否	是否覆盖本地数据
success	(res: {code: number, msg: string}) => void	/	否	成功回调
fail	(err:{code: number, msg: string}) => void	/	否	失败回调

返回值

无

示例

GameHelper.ServerData.uploadData({
  data: {
    key1: 11,
    key2: 22,
  },
  isCover: true, //是否覆盖本地数据
  success(res) {
    console.log("上传成功");
  },
  fail(res) {
    console.log("上传失败");
  },
});