SuperAPI AI 工具集

redis-game-patterns

编程与开发

查看项目

更新于 11-15 03:09

技能介绍

Redis Game Patterns

Redis 保存热的、可丢弃的游戏状态,数据库保存最终结果。若 Redis 以空状态重启,玩家不应 lose 任何重要的东西:比赛结果、奖励与货币先写入数据库。

客户端选择

这里的代码使用 ioredis 6,因为 BullMQ 6 默认用 ioredis 创建其 Redis 连接,而本套件中大多数游戏服务器已在运行 BullMQ(bullmq-game-queues)。ioredis 的 README 说明,对于新项目,推荐使用 node-redis;如果项目尚无 BullMQ、也还没有 ioredis,可考虑 node-redis 并移植命令。BullMQ 6 将 ioredis 标记为可选 peer,因此需显式安装:bun add ioredis。

每个文件都接收客户端作为参数,类型为来自 ioredis 的 Redis。在服务器中创建一次客户端并传入。保留默认的 replyMapping: "legacy":解析器预期 WITHSCORES 回复为扁平的 [member, score, ...] 字符串数组。代码需要 Redis 6.2 或更高版本(ZRANGE ... REV)。

模式 1:排行榜

当游戏按分数排名玩家时,复制 boilerplate/leaderboard.ts。

每个榜单与周期一个有序集合:lb:weekly:2026-W46、lb:season:3。新周期就是新 key;先快照旧榜,再删除它。

ZADD 会覆盖分数。若采用“最高分计入”,要有意决定:ZADD ... GT 保留较高值;ZINCRBY 累加分数。

并列:同分按成员 ID 的字节序排序(REV 下为反向),而不是按谁先到达该分数。若必须“先到先得”,把并列决胜编码进分数,并让整个分数处于 double 的精确整数范围(2^53)内。

ZREVRANK 的排名从 0 开始;样板代码对第一名玩家返回排名 1。

赛季结束时,调用 snapshot() 并传入一个把行写入 Postgres(postgres-game-schema)的函数,然后重置榜单。

模式 2:在线状态与临时状态

当游戏展示谁在线、在数据库之外保存实时对局状态,或应用限时增益时,复制 templates/ephemeral-state.ts。

在线状态:客户端每隔几秒心跳;服务器用 EX 写入 presence:<playerId>。key 不存在即离线,因此崩溃的客户端无需清理代码就会变为离线。把 TTL 设为几个心跳间隔,这样一个丢包不会让玩家短暂显示为离线。

对局状态:每场对局一个 JSON key,TTL 长于最长对局。update() 读取 JSON,应用你的纯函数,并用 compare-and-set Lua 脚本写回结果:仅当 key 仍保存着刚才读到的内容时才写入,否则重读并重试。同一进程内对同一对局的调用依次执行,因此彼此不会竞争;该脚本捕获与其他服务器之间的竞争。此处不要用 WATCH/MULTI:在一个共享客户端上的并发更新会交错它们的 WATCH 与 EXEC,导致写丢失。

限时增益:每个效果一个带 EX 的 key,外加一个按过期时间计分的每玩家有序集合来列出它们。过期无需清扫任务。

SET 会清除已有 TTL,除非再传 EX。模板中每次写入都会传。

模式 3:按动作限流

当某个动作需要冷却或限制刷屏时,复制 templates/rate-limiter.ts:攻击、聊天、交易、制作。

按玩家与动作设置 key:rl:<action>:<playerId>。不同动作的限制不同,因此每个玩家一个全局限制是错误的形状。

在有序集合上做滑动窗口:每次尝试是一个成员,以其时间戳计分。模板在一个 MULTI 中执行删除旧记录、添加、计数与设置过期,因此两个并发尝试不能同时通过。

被拒绝的尝试会被再次移除。否则刷按钮的玩家会在窗口过后仍被锁住。

对每个动作消息在服务器端检查限制,包括经由 WebSocket 到达的动作(game-backend-architecture)。

模式 4:玩家数据的 cache-aside

无文件;代码短到可现场编写。

从 Redis 读取 player:<id>。命中则解析并返回。

未命中则从数据库加载,用 SET key value EX ttl 写入并返回。缺失的行不会被缓存,除非你用一个短 TTL 缓存“未找到”标记。

每次对该玩家的数据库写入提交后,删除缓存 key。不要从游戏逻辑原地更新缓存。

若缓存的 JSON 解析失败,删除该 key 并回退到数据库。

只缓存游戏频繁读取且能容忍几秒延迟的数据(资料、配装、外观)。钱包余额与物品数量在变更它们的事务中从数据库读取。

陷阱

把 Redis 当作比赛结果、奖励或货币的真相记录。这些应写入数据库;Redis 可能丢失它们。

在多台服务器上对共享 key 做读后写。应使用 Lua 脚本(如 update() 所做)、单条命令,或在不被并发代码共享的连接上使用 MULTI/WATCH;普通 pipeline 无法阻止其他客户端的命令穿插执行。

对服务器不可错失的事件使用 Pub/Sub。Redis Pub/Sub 至多投递一次:宕机或断连的服务器会丢失消息。比赛结果与购买应通过队列发送(bullmq-game-queues)。

在共享命令连接上订阅。在 RESP2 下,已订阅的连接只接受 subscribe 系列命令,ioredis 的 README 建议为订阅创建单独连接。为订阅者分配独立客户端(redis.duplicate())。

Pub/Sub 频道加环境前缀(prod:match-events)。Pub/Sub 忽略数据库编号,因此同一 Redis 上的预发与生产会互相听到。

文件

boilerplate/leaderboard.ts:构建排名榜时复制;查看排名与快照如何计算时阅读。

templates/rate-limiter.ts:添加按动作限制时复制。

templates/ephemeral-state.ts:添加在线状态、实时对局状态或限时增益时复制。

references/sources.md:需要上述某条规则背后的 Redis 或 ioredis 页面时阅读。

相关技能

bullmq-game-queues:同一 Redis 上的持久任务与事件。

matchmaking-system:Redis 上的队列与大厅状态。

gameplay-analytics:Redis 上的事件缓冲。

postgres-game-schema:排行榜快照与玩家数据所在之处。

game-backend-architecture:客户端在哪里创建并传入。