保存数据和更新版本
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
前面几页,你的游戏对象都活在内存里——服务器一重启,数据就全没了。真正的游戏需要持久化:玩家的等级、背包里的装备、任务进度、充值记录……这些数据必须长期保存。
这一页讲两件事:怎么存数据(Storage API)和怎么管理模块版本(模块升级与迁移)。
两种持久化方式
FlexCore 有两种保存数据的方式:
| 方式 | 怎么用 | 适合什么 |
|---|---|---|
| Schema 内置持久化 | @State("X", { persistent: true }) | 世界共享的状态(回合数、Boss 刷新时间) |
| Storage API | server.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