lawless-design/docs/00_项目概述/开发规范/规范-热更与兼容性.md

规范-热更与兼容性

位置: docs/开发规范/规范-热更与兼容性.md 版本: v1.0 日期: 2026-07-08 关联: AGENTS.md、TDD-02（客户端热更新技术方案）、PRD-03（热更新与活动系统）

---

1. 热更铁律

1.1 Asset Bundle 热更

规则	优先级	说明
客户端启动时检查热更包版本	P0	版本不匹配时强制下载更新
热更包大小 < 50MB（单次）	P0	大资源分多个 Bundle 按需加载
热更下载失败可重试 3 次	P0	失败后提示手动更新或跳过（非强制内容）
热更发布 1 小时内可一键回滚	P0	回滚到上一版本，不影响玩家数据
热更内容限定：UI/文案/配置/脚本	P0	禁止热更修改协议格式/数据库结构

1.2 热更禁止行为

• ❌ 热更修改 Protobuf 字段编号/类型
• ❌ 热更修改数据库表结构
• ❌ 热更删除已存在的 API 接口
• ❌ 热更修改核心战斗公式（影响平衡性的走 Nacos 配置热更）
• ❌ 热更包未经测试直接上生产

---

2. 协议兼容性

2.1 Protobuf 向后兼容

// ✅ 正确：新增字段用新编号
message CharacterData {
  string id = 1;
  int32 energy_current = 2;
  int32 energy_cap = 3;
  // v1.1 新增
  int32 seclusion_end_time = 4;
}

// ✅ 正确：废弃字段保留编号（reserved）
message OldMessage {
  reserved 3, 5;
  reserved "old_field_name";
  string new_field = 1;
}

// ❌ 错误：修改已有字段编号
message Bad {
  string id = 2;  // 原来是 1，修改后旧客户端解析错误
}

2.2 API 向后兼容

规则	优先级	说明
新增 API 必须走版本号	P0	/v2/character/create
旧 API 保留至少 2 个版本	P0	旧版本标记 deprecated，客户端迁移后下线
禁止删除已有 API 路径	P0	只能标记 deprecated，返回 410 Gone
禁止修改已有 API 参数含义	P0	如需修改，新建 API 路径
服务端必须忽略未知字段	P0	旧客户端连接新服务端时不崩溃

2.3 数据模型向后兼容

规则	优先级	说明
新增字段必须有默认值	P0	旧存档读取时自动填充默认值
禁止删除已有字段	P0	废弃字段保留，数据迁移到新结构
禁止修改字段数据类型	P0	如需修改，新增字段 + 迁移脚本
数据模型变更必须提供迁移函数	P0	migrateV1toV2()，递增 DATA_MODEL_VERSION
迁移脚本必须经过测试	P0	用生产数据脱敏副本测试迁移

---

3. 兼容性检查清单

发版前必须检查：

□ Protobuf reserved 字段是否完整
□ 新增 API 是否走了版本号
□ 旧 API 是否仍可用
□ 数据模型迁移脚本是否测试通过
□ 旧客户端能否连接新服务端
□ 热更包大小是否 < 50MB
□ 热更回滚方案是否就绪

---

4. 版本记录

• v1.0（2026-07-08）: 初始版本，覆盖热更规则、协议兼容、数据兼容