跳到主要内容

规范-热更与兼容性

位置: 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如需修改，新增字段 + 迁移脚本
数据模型变更必须提供迁移函数P0migrateV1toV2()，递增 DATA_MODEL_VERSION
迁移脚本必须经过测试P0用生产数据脱敏副本测试迁移

3. 兼容性检查清单​

发版前必须检查：

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

4. 版本记录​

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