全栈攻城狮

Appearance

游戏服务器设计文档撰写 ​

概述 ​

好代码需要好文档：接手快、评审有据、上线有手册。游戏服务器需要四类核心文档：架构设计文档（为什么这么设计）、接口规范文档（前后端契约）、数据库设计文档（数据模型）、部署运维手册（怎么跑怎么修）。本文给出四类文档的模板与写作要点。

一、架构设计文档 ​

1.1 文档结构模板 ​

架构设计文档模板：
  1. 概述（系统目标、业务范围、读者）
  2. 术语与缩略语
  3. 业务场景与核心流程
  4. 总体架构（分层 + 拓扑图）
  5. 关键技术决策（选型与理由、备选方案）
  6. 模块设计（模块职责、依赖、交互）
  7. 数据设计（核心实体、缓存、存储策略）
  8. 非功能设计（性能/安全/可用性/扩展性）
  9. 风险与对策
  10. 附录（参考、待办、变更记录）

1.2 关键技术决策写法 ​

决策记录（ADR 风格）：
  决策：对局采用状态同步而非帧同步
  背景：弹射对战有物理碰撞，需防作弊
  方案：服务端权威状态同步 + 快照兜底
  权衡：广播量大（增量+AOI 缓解），换安全与可回放
  备选：帧同步（流量小，但确定性与防作弊成本高）

好处：
  新人知道"为什么"
  评审聚焦决策质量
  变更时先改文档
架构图（文本/工具均可）：
  客户端 → 接入网关（Netty，无状态）
           → 逻辑节点（房间分片，一致性哈希）
              → Redis（在线/房间/快照）
              → MySQL（档案/对局/流水）
              → MQ（异步任务：排行/通知/审计）
  监控：Prometheus + Grafana + ELK + SkyWalking

二、接口规范文档 ​

2.1 协议接口规范 ​

接口规范模板：
  Opcode：1201
  名称：出牌请求
  方向：客户端 → 服务器
  请求体字段表（名称/类型/必填/说明）
  响应体字段表（code/数据/消息）
  错误码表（具体错误及含义）
  时序图（调用顺序与依赖）
// 字段表示例
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| roomId | int64 | 是 | 房间 ID |
| cards | Card[] | 是 | 要出的牌，1-20 张 |
| seq | int32 | 是 | 操作序号（防乱序） |

2.2 文档管理 ​

接口文档规范：
  单一来源：proto 定义作为权威（protoc 生成文档）
  版本管理：协议版本 + 变更记录
  评审流程：接口变更需前后端确认
  兼容原则：字段只增不改（见协议章节）

工具：
  Protobuf 定义即文档（注释齐全）
  API 平台（YApi/Apifox）托管 HTTP 接口
  Mock 服务（联调先行）
// proto 注释即文档
// 出牌请求：校验通过后广播给房间内所有玩家
message PlayCardReq {
  int64 room_id = 1;    // 房间 ID
  repeated Card cards = 2;  // 出牌列表
}

三、数据库设计文档 ​

3.1 设计模板 ​

数据库设计文档：
  1. ER 总览（实体关系图）
  2. 表清单（表名/用途/容量预估）
  3. 每表字段（名称/类型/约束/索引/说明）
  4. 索引设计（主键/唯一/普通，覆盖场景）
  5. 分表策略（按 Uid Hash/时间，见存储章节）
  6. 数据生命周期（归档/清理）
  7. 变更流程（加字段兼容，见灰度章节）
// 表设计示例
表：battle_record（对局记录）
字段：
  id bigint PK
  room_id bigint 索引（房间维度查询）
  biz_id varchar 唯一（幂等，见结算章节）
  player_id bigint 索引（玩家历史战绩）
  result varchar（胜负/积分）
  detail json（手牌/出牌过程）
  created_at datetime（按时间分表/归档）

3.2 设计原则 ​

游戏库设计原则：
  读写分离（热数据缓存，MySQL 兜底）
  冷热分离（近期明细 vs 历史归档）
  流水表只增不改（审计需求）
  幂等键（biz_id 唯一索引）
  容量预估（在线 × 行为频率 → 行数/存储）
容量估算示例：
  日活跃 10 万 × 人均 5 局 = 50 万行/日
  年对局记录 ≈ 1.8 亿行
  → 按时间分表（月表）+ 历史归档

四、部署运维手册 ​

4.1 手册结构 ​

部署运维手册：
  1. 环境说明（架构图、节点清单、端口）
  2. 部署步骤（镜像/配置/启动，见容器化章节）
  3. 配置说明（环境变量、配置中心、关键参数）
  4. 运维操作（发布/回滚/扩容/维护，见灰度章节）
  5. 监控告警（面板地址、告警规则、值班流程）
  6. 故障排查手册（常见问题 SOP）
  7. 数据备份与恢复
  8. 应急联系（值班表、升级路径）
// 故障排查 SOP 示例
故障：登录超时
步骤：
  1. 查监控：网关 CPU/连接数、登录 QPS/RT
  2. 查日志：登录失败原因（traceId）
  3. 查链路：哪一跳慢（网关→逻辑→DB）
  4. 判断：DB 慢查询 / 逻辑阻塞 / 网络
  5. 处理：对应方案 + 验证
  6. 复盘：沉淀到手册

4.2 手册维护 ​

手册维护：
  与代码同库管理（docs/ops/）
  发布流程更新手册（CI/CD 附带文档变更）
  演练：故障演练验证 SOP 有效性
  新人培训：手册即教材

文档质量检查：
  步骤可执行（照着做能完成）
  信息最新（与配置同步）
  有截图/示例（降低理解成本）

五、实现要点 ​

设计文档撰写清单：
  架构文档：概述 + 架构 + 决策记录 + 非功能
  接口文档：字段表 + 错误码 + 时序 + 单一来源
  数据库文档：ER + 表字段 + 索引 + 分表 + 生命周期
  运维手册：部署 + 配置 + 故障 SOP + 演练

常见坑：
  只写"是什么"不写"为什么" → 决策记录缺失
  接口文档与代码不同步 → proto 单一来源
  无容量估算 → 上线后库爆
  手册不演练 → 出事照着手册也救不了

与整体体系衔接：
  各模板引用前 13 周章节方案
  运维手册 → 运维章节落地
  接口规范 → 协议章节
  数据设计 → 存储章节