谜题后端 - KV 存储

KV 适合保存单个状态、计数器和配置。

工具函数

$puzzle.kv、$team.kv、$this.kv 分别提供不同作用域的 KV 接口。

kv.get(key: string): unknown | null;
kv.getEntry(key: string): KvEntry | null;
kv.set(key: string, value: unknown, options?: KvOptions | null): KvMutation;
kv.setIfAbsent(key: string, value: unknown, options?: KvOptions | null): KvMutation;
kv.increment(key: string, amount?: number, options?: TtlOptions | null): KvMutation;
kv.compareAndSet(key: string, expectedVersion: string, value: unknown, options?: KvOptions | null): KvMutation;
kv.delete(key: string): boolean;

$game.kv 提供当前比赛任意作用域的 KV 接口，提供的函数同上，但是在第一个参数前增加一个 scope 参数用于指定作用域。例如：

kv.get(scope: Scope, key: string): unknown | null;

相关类型

type KvOptions = {
  ttl: number | null; // ms
};

type KvEntry = {
  value: unknown;
  version: string;
  expiresAt: string | null;
};

type KvMutation = {
  applied: boolean;
  entry: KvEntry | null;
  serverTime: string;
};

• KV 项每次更新时将增加一次 version，便于原子操作。
• ttl 代表项的存活时间，使用毫秒作为单位，范围是 1 - 31,536,000,000 毫秒（365 天），提供 null 代表永久保存。所有更新项的函数不提供 options 时，如果写入项是新键，则默认永久保存；如果写入项是已有键，则默认保留旧的 TTL。

get

kv.get(key: string): unknown | null;
kv.getEntry(key: string): KvEntry | null;

获取指定键的值或详细信息。

set

kv.set(key: string, value: unknown, options?: KvOptions | null): KvMutation;

设置指定键的值。

setIfAbsent

kv.setIfAbsent(key: string, value: unknown, options?: KvOptions | null): KvMutation;

如果键不存在，则设置指定键的值。这是一个原子操作。

increment

kv.increment(key: string, amount?: number, options?: TtlOptions | null): KvMutation;

增加项的值，默认增加 1。要求现有值必须为数字，否则抛出异常。这是一个原子操作。

compareAndSet

kv.compareAndSet(key: string, expectedVersion: string, value: unknown, options?: KvOptions | null): KvMutation;

如果项的 version 是预期值，则设置新值。这是一个原子操作。

delete

kv.delete(key: string): boolean;

删除指定键。