找回密码
 立即注册
搜索
热搜: 活动 交友 discuz
跳到内容
FlexCore开发者社区

学习与实践

文档中心

从入门操作到版本更新,找到适合当前阶段的说明。

保存数据和更新版本

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。

前面几页,你的游戏对象都活在内存里——服务器一重启,数据就全没了。真正的游戏需要持久化:玩家的等级、背包里的装备、任务进度、充值记录……这些数据必须长期保存。

这一页讲两件事:怎么存数据(Storage API)和怎么管理模块版本(模块升级与迁移)。


两种持久化方式

FlexCore 有两种保存数据的方式:

方式怎么用适合什么
Schema 内置持久化@State("X", { persistent: true })世界共享的状态(回合数、Boss 刷新时间)
Storage APIserver.storage.*玩家私有数据、交易记录、独立于世界的业务数据

persistent: true 声明世界状态需要纳入持久化;实际保存、恢复取决于已启用的存储配置、快照与恢复入口。它不等于每次字段赋值都已持久化,也不能保证任意崩溃前的最后一次修改已保存。

但很多时候你需要主动控制存什么、什么时候存、怎么查。这就是 Storage API 的用途。

⚠️ Storage API 全部是异步的——只能在 Protocol handler 或 Event handler 里调用,不能在 System 回调里用。


Storage 基本操作

Storage 用"集合(collection)+ 键(key)"的方式组织数据,类似键值存储:

import { server } from "@flexcore/server";

// 写入
await server.storage.put(
  "players",              // 集合名
  "player:1001",          // 键
  { name: "Alice", level: 10, gold: 500 },
  {                       // 写入选项
    indexes: [            // 建索引,方便后面查询
      { index: "name", value: "Alice" },
    ],
  },
  { mode: "async" },      // 执行模式
);

// 读取
const data = await server.storage.get(
  "players",
  "player:1001",
  { mode: "async" },
);
if (data === null) {
  console.log("记录不存在");
} else {
  // 未指定泛型时 value 为 unknown,使用前按项目模型验证。
  console.log(data.value, data.version);
}
// version 是 StorageVersion(规范十进制字符串),不是 number。

// 修改(部分更新)
await server.storage.patch(
  "players",
  "player:1001",
  { gold: 600 },          // 只改 gold,其他字段不动
  {},
  { mode: "async" },
);

// 删除
await server.storage.remove(
  "players",
  "player:1001",
  undefined,              // expectedVersion(乐观锁,传 undefined 不检查)
  { mode: "async" },
);

每次写入都会返回一个 version 号。下次修改时可以传 expectedVersion 做乐观锁——如果数据被别人改过,你的修改会失败。


查询

写入时如果建了索引,后面可以按索引查询:

import { server } from "@flexcore/server";

// 按 name 索引查询
const results = await server.storage.query(
  "players",              // 集合名
  "name",                 // 索引名
  "Alice",                // 索引值
  10,                     // 最多返回几条
  { mode: "async" },
);
// results 是只读 StorageObject 数组;每项包含 key、value、version。

💡 索引项通过写入选项 indexes 维护;需要调整索引时按实际数据重新写入并验证。规划好你需要按什么字段查询。


唯一值

有些值必须全局唯一,比如用户名、邮箱。用 reserveUnique 预留:

import { server } from "@flexcore/server";

// 尝试占用用户名 "Alice"
await server.storage.reserveUnique(
  "players",              // 集合名
  "username",             // 唯一字段名
  "Alice",                // 要占用的值
  "player:1001",          // 关联的键
  { mode: "async" },
);

// 如果别人已经占用了 "Alice",这里会报错
// 如果占用成功,后续可以用 releaseUnique 释放
await server.storage.releaseUnique(
  "players",
  "username",
  "Alice",
  { mode: "async" },
);

事务

多个操作需要“要么全成功,要么全失败”时,用事务。下面固定余额仅展示 API 结构;真实转账必须先读双方数据、检查余额与版本,并在每个写操作的 options.expectedVersion 中传入读取版本:

import { server } from "@flexcore/server";

// 转账:A 扣钱,B 加钱——必须一起成功或一起失败
const tx = server.storage.createTransaction();

// 往事务里添加操作
tx.add({
  op: "patch",
  collection: "players",
  key: "player:A",
  value: { gold: 400 },   // A 扣 100
});

tx.add({
  op: "patch",
  collection: "players",
  key: "player:B",
  value: { gold: 600 },   // B 加 100
});

// 提交事务
const receipt = await tx.commit({ mode: "async" });
// receipt.committed → true
// receipt.versions 是各操作返回的 StorageVersion 或 undefined 数组。

如果中途任何一个操作失败,整个事务会回滚——A 不会扣钱,B 也不会加钱。


在哪里调用 Storage

Storage IO 应放在允许异步的 Protocol/Event handler 等上下文;System 回调必须同步。协议处理器先按协议编码解码字节,再把已验证的 context.entityId 和商品 ID 传给购买函数。不要使用客户端传入的价格。

下面是可类型检查的业务函数,需在已配置 Storage 的模块中调用。示例把余额和本次购买数量放在同一记录,用 expectedVersion 防止并发覆盖;发生冲突时重新读取并重新验证,不盲目重放扣款。跨记录发货、订单去重与重试需按业务设计事务。

import { server } from "@flexcore/server";

type Wallet = { gold: number; inventory: Record<string, number> };
function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}
function isWallet(value: unknown): value is Wallet {
  return isRecord(value) && typeof value.gold === "number" &&
    Number.isSafeInteger(value.gold) && value.gold >= 0 &&
    isRecord(value.inventory) && Object.values(value.inventory).every(
      count => typeof count === "number" && Number.isSafeInteger(count) && count >= 0,
    );
}

export async function purchase(playerId: string, itemId: string) {
  // 演示商品目录由服务端维护,客户端只提交 itemId。
  const catalog = new Map([["potion", { price: 10 }]]);
  const item = catalog.get(itemId);
  if (!item) return { ok: false, reason: "item_not_found" };
  const key = `player:${playerId}`;
  const record = await server.storage.get("players", key, { mode: "async" });
  if (!record || !isWallet(record.value)) {
    return { ok: false, reason: "invalid_wallet" };
  }
  const wallet = record.value;
  if (wallet.gold < item.price) return { ok: false, reason: "not_enough_gold" };
  const count = (wallet.inventory[itemId] ?? 0) + 1;
  if (!Number.isSafeInteger(count)) return { ok: false, reason: "inventory_full" };
  const receipt = await server.storage.put("players", key, {
    gold: wallet.gold - item.price,
    inventory: { ...wallet.inventory, [itemId]: count },
  }, { expectedVersion: record.version }, { mode: "async" });
  return { ok: true, version: receipt.version };
}

Protocol/Event handler 中也要检查未知输入的结构,不能因为为 storage.get<T> 指定了泛型就认为数据库内容已通过运行时验证。


模块升级与迁移

当你的项目依赖外部玩法模块(比如战斗模块、背包模块)时,升级这些模块需要小心——Schema 变更可能不兼容旧数据。

升级流程

# 1. 先看看升级会改什么(dry-run,不实际执行)
fc-tools.exe module update --project . --package @demo/combat --dry-run

# 2. 确认没问题后,正式升级
fc-tools.exe module update --project . --package @demo/combat

# 3. 如果有 Schema breaking changes,需要显式接受
fc-tools.exe module update --project . --package @demo/combat --accept-breaking

--dry-run 会显示升级计划:会改哪些文件、Schema 有什么变化、有没有 breaking changes。先看计划,再决定要不要继续。

数据迁移

r2 的 fc-tools module 没有 migrate 子命令,也没有本页旧版所述的 --database-url 入口。Schema 变更应先查看真实契约差异和模块提供的迁移要求,备份数据,并通过模块实际支持的升级流程处理。接受 breaking diff 不等于自动完成任意业务数据转换。

module restore 从 npm/FlexCore lock 恢复物理依赖和残留安装事务,不能当作数据库回滚。--force 只在确认没有活动 fc 进程时移除残留事务锁。详见升级指南。

其他模块命令

# 安装新模块
fc-tools.exe module add --project . --package @demo/inventory

# 移除模块(默认保留数据,加 tombstone)
fc-tools.exe module remove --project . --module-id @demo/inventory

# 恢复锁定依赖和残留安装事务;先确认没有活动 fc 进程
fc-tools.exe module restore --project . --force

# 查看模块依赖图
fc-tools.exe module graph --package ./node_modules/@demo/combat

# 检查模块契约
fc-tools.exe module verify --package ./node_modules/@demo/combat

发布前检查

上线前,养成习惯跑一遍检查:

# 1. 项目结构检查
fc-tools.exe server check --project .

# 2. 编译构建
fc-tools.exe server build --project .

这两个命令会检查:

  • Schema 定义是否合法
  • Token 引用是否匹配
  • TypeScript 类型是否正确
  • 模块依赖是否完整
  • 契约差异与模块依赖是否通过工具校验(业务数据迁移仍须独立验证)

这些检查通过后,仍需验证实际配置、数据恢复与运行行为;构建检查不替代上线验证。


回头看

数据持久化和模块管理是上线前必须搞定的两件事:

  • 需要长期保存的数据 → server.storage(异步,在 Protocol/Event handler 里用)
  • 世界共享的持久化状态 → @State("X", { persistent: true })(按实际配置保存和恢复)
  • 升级外部模块 → module update --dry-run 先看,再正式升级
  • Schema 变了 → 检查契约差异、备份和模块真实迁移路径
  • 上线前 → server check + server build

Archiver|小黑屋|FlexCore开发者社区

GMT+8, 2026-11-20 00:20 , Processed in 0.086484 second(s), 5 queries .

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部