SuperAPI AI 工具集

postgres-game-schema

编程与开发

查看项目

更新于 11-15 03:09

技能介绍

用途

postgres-game-schema 是一个游戏项目的数据库模式技能,核心价值在于提供一套经过整理的 PostgreSQL 表结构与建表约定。它面向使用 Drizzle ORM 的游戏项目,不限定游戏类型,可用于搭建玩家、角色、会话、物品、背包、事件、排行榜、成就、货币、社交关系、公会等基础数据模型。其他相关技能(如支付、玩法分析、游戏经济设计)可在此基础上构建。

安装、驱动配置与迁移执行不包含在本技能内,需参考厂商文档;若已安装 neon-drizzle 技能则使用它,否则参考 Drizzle 官方入门文档。目标版本为稳定的 Drizzle 0.45.x 线,官方文档默认使用 rc 版本,需自行固定为 0.45。

主要约定

  • 命名:表名使用复数 snake_case,列在 SQL 中为 snake_case、在 TypeScript 中为 camelCase;索引命名为 <table>_<columns>_idx。
  • ID:使用 text("id").primaryKey().$defaultFn(() => crypto.randomUUID())。面向玩家的标识不使用自增整数,避免被枚举。
  • 时间戳:timestamp(...).notNull().defaultNow()。实体与目录表带 createdAt 和 updatedAt;追加型与状态行记录有意义的时间字段。每次更新需显式设置 updatedAt。
  • 软删除:players 表有 deletedAt,所有返回玩家的读取(包括 join)需过滤 isNull(players.deletedAt)。
  • JSONB:需要过滤、排序、join 或求和的字段用类型化列;各类型的额外属性放入 jsonb 扩展字段,不在核心表加类型专属列。使用 jsonb 而非 json。
  • 枚举:代码中需要分支判断的固定集合用 pgEnum;设计者会扩展的开放集合用文本。
  • 外键:玩家拥有的行对 players 使用 cascade;分析事件使用 set null 保留历史;目录引用不级联。
  • 索引:每个玩家拥有的表索引 owner key;常见过滤加以 owner 开头的复合索引;upsert 目标的自然键加唯一索引。
  • 货币:整数金额,不做读-改-写。入账用原子 amount = amount + n upsert;扣款用单条 UPDATE ... WHERE amount >= cost 并在无行更新时报告失败;表上加 CHECK (amount >= 0)。
  • 幂等:processed_events 表为每个已应用的外部事件或任务保存一行,与被保护变更在同一事务插入,主键冲突表示已处理。

角色与归属

players 是账号,绑定认证用户;characters 保存一个账号拥有的多个角色,角色名在分片内对存活角色唯一(部分索引基于 deleted_at IS NULL,删除后名字可释放)。角色数量上限是游戏规则,需在代码中检查。

有角色系统时,等级、经验与属性归属角色,需从 players 删除对应列并调整相关查询;单角色游戏可跳过 characters。钱包与背包归属账号还是角色由游戏决定,schema 默认放在账号上;迁移到角色需替换 playerId 为 characterId、调整索引、保留金额校验与受保护扣款,并修改查询模板中的货币与背包函数,否则会读写错误的钱包。公会成员关系默认每个玩家一个公会,多公会需参考表注释并另行设计替代账号规则。

使用方式

  1. 将 boilerplate/schema.ts 复制到项目的 schema 模块,删除不需要的表。
  2. 按约定从 templates/entity-template.ts 添加游戏实体(玩家拥有实体、目录定义加实例、枚举驱动的定时实体三种模式)。
  3. 按 Drizzle 文档使用 drizzle-kit 生成并应用迁移:先改 schema 再生成,不手写迁移 SQL。
  4. 按 templates/query-patterns.ts 的风格编写查询,数据库作为第一个参数传入。

文件内容

  • boilerplate/schema.ts:起始数据库用,包含 13 张表及枚举。
  • templates/entity-template.ts:新增实体的三种模式模板。
  • templates/query-patterns.ts:背包 join、排行榜前 N、事件聚合、JSONB 过滤、货币原子入账、受保护扣款、最高分 upsert 等函数,均接受任意 Drizzle Postgres 数据库实例。

注意事项

  • 不要用一个 JSON 大对象存放全部游戏状态,应规范化到表,JSONB 仅用于可扩展字段。
  • 缺少复合索引会导致“某玩家某类型事件”查询低效。
  • 热路径上按 JSONB 键过滤需用 GIN 索引配 @> 查询,或加表达式索引,或将键提升为类型化列。
  • 排行榜与公会查询 join players 时同样要过滤软删除玩家。
  • 多个 git worktree 同时跑迁移会冲突,同一时间只应有一个 worktree 执行迁移,实验性 schema 可另开 Neon 分支。
  • 若项目迁移到 Drizzle 1.0(rc 版本),relations()、casing 配置、迁移目录结构、PgDatabase 类型等会变化,需按官方 v0 到 v1 变更文档调整。

适用场景

适合使用 Drizzle ORM 与 PostgreSQL 搭建游戏后端数据层的项目,尤其是需要账号、角色、物品、背包、货币、事件、排行榜、公会等常见结构的游戏。也适合作为新增游戏实体与编写查询时的约定参考。

限制

本文档未提供具体收费、价格、平台支持范围或效果数据;安装、驱动与迁移步骤依赖外部文档,币种与钱包归属等业务规则需开发者自行决定并在代码中实现限制。