全栈攻城狮

Appearance

道具/物品系统 ​

概述 ​

道具是玩家与游戏世界交互的载体：消耗品、装备、材料、碎片都在背包里流转。道具系统的难点在统一抽象（千变万化的道具用一套模型表达）、增减接口的安全（防止刷道具/丢道具）、以及背包容量（有限空间的取舍）。本文设计完整的道具系统。

一、Item 统一抽象 ​

1.1 道具定义（配置） ​

道具配置化定义，行为差异通过"类型 + 参数"表达，避免为每个道具写代码：

ItemDef（配置表）：
  itemId、名称、图标、描述
  type（CONSUMABLE/EQUIP/MATERIAL/FRAGMENT/…）
  stackLimit（堆叠上限）
  bindType（BOUND_ON_GET / BOUND_ON_USE / UNBOUND）
  useEffect（使用效果，Json 配置）
  sellPrice（出售价）
  quality（品质：白/绿/蓝/紫/橙）
道具类型：
  消耗品：药水、体力瓶 → 使用即消失
  装备：武器、防具 → 带属性，可穿戴
  材料：升级材料、打造材料 → 合成原料
  碎片：角色碎片、装备碎片 → 集齐兑换
  功能类：改名卡、扩展券 → 触达功能

1.2 实例 vs 定义 ​

同一种道具有"定义"与"实例"两层：定义是静态配置，实例是玩家持有的具体一份（带数量、绑定、唯一属性）。

玩家持有（PlayerItem）：
  id、playerId、itemId、count
  bindFlag、uniqueProps（Json，装备强化等）
  obtainTime
  PRIMARY KEY(id)
  索引：playerId + itemId
区分：
  可堆叠道具（材料）：一行记录 count
  唯一道具（装备）：每件一行，带独立属性
  抽象统一：都走"背包项"模型，count=1 即唯一件

二、道具增减接口 ​

2.1 统一入口 ​

所有道具变动走唯一入口，保证记录与校验一致：

核心接口：
  addItem(playerId, itemId, count, reason, bizId)
  removeItem(playerId, itemId, count, reason, bizId)
  useItem(playerId, itemId, count)

安全要求：
  所有变更写流水（来源/去向可追溯）
  bizId 幂等（防重复发放）
  数量校验（不能为负、不能超上限）
addItem 流程：
  1. 查询 ItemDef（不存在拒绝）
  2. 校验背包容量/堆叠上限
  3. 落库（新增行或累加堆叠）
  4. 写道具流水
  5. 推送背包变更 + 红点

2.2 批量与聚合 ​

批量发放：
  多种道具一次发放 → 逐种校验容量，整体成功或部分失败
  部分失败：成功项保留，失败项提示背包满

高频聚合：
  战斗结算多道具 → 聚合一次写入，减少事务次数
  流水可按组聚合（一次战斗一组流水）

2.3 使用效果 ​

使用道具走效果执行器，效果配置化：

useItem 流程：
  1. 校验持有数量
  2. 扣减道具
  3. 执行效果（回血/加货币/开箱子/兑换）
  4. 效果执行失败 → 回滚扣减

效果执行器：
  Map<String, EffectHandler>  按效果类型注册
  配置 usesEffect 定义参数（数量/概率/产物）

三、背包容量管理 ​

3.1 容量模型 ​

背包容量：
  基础容量（如 50 格）
  付费/奖励扩容（+10 格 × N 档）
  临时扩容（活动期间）

容量计算：
  堆叠道具占 1 格（按种类）
  唯一道具每件占 1 格
  容量 = 基础 + 扩容 - 已用

3.2 满包处理 ​

满包策略：
  主动获取 → 拒绝并提示（"背包已满"）
  系统发放 → 走邮件/临时仓库
  自动合并堆叠 → 优先合并同种可堆叠道具
  一键整理 → 排序/合并，腾出空间
临时仓库（溢出区）：
  部分游戏提供溢出存放（最多 N 件）
  溢出区内道具不可交易/使用
  腾出空间后自动归位

3.3 背包查询与排序 ​

查询：
  分页拉取背包列表
  按类型/品质筛选
  排序：品质 → 类型 → 获取时间

性能：
  背包数据 Redis 缓存（热数据）
  变更后推送增量，客户端本地维护

四、道具状态与流转 ​

4.1 绑定状态 ​

绑定规则：
  BOUND_ON_GET：获取即绑定，不可交易
  BOUND_ON_USE：使用后绑定
  UNBOUND：可交易/上架

状态流转：
  仅允许 未绑定 → 绑定（不可逆）
  绑定道具出售/分解 → 只返还通用货币/材料

4.2 流转渠道 ​

流转渠道（都走统一增减接口）：
  商城购买、任务奖励、活动发放
  玩家交易、邮件附件、掉落
  分解/合成/强化等消耗

防刷设计：
  交易走服务端校验（价格上限、异常检测）
  掉落概率服务端计算（随机章节）
  所有流转留流水

五、实现要点 ​

核心接口：
  addItem / removeItem / useItem
  getBag(playerId, page)
  sortBag(playerId)
  checkCapacity(playerId, itemList)

扩展：
  synthesize（合成）→ 材料 + 图纸 → 产物
  decompose（分解）→ 装备 → 材料
  upgrade（强化）→ 装备 + 材料 → 属性提升
工程注意：
  配置热更新（新道具无需发版）
  道具 ID 稳定（勿复用/变更语义）
  唯一道具并发操作（强化/交易）加锁
  背包数据一致性（Redis 与 MySQL 对账）
常见坑：
  堆叠上限溢出 → 拆分多行
  并发使用重复扣减 → 同玩家串行 + 条件更新
  满包导致活动奖励丢失 → 邮件兜底
  绑定状态混乱 → 状态机严格单向
与其他系统衔接：
  发放 → 商城/任务/抽奖/活动统一调用
  消耗 → 强化/合成/交易
  展示 → 玩家数据模型/背包
  审计 → 道具流水与货币流水同套体系