100 行
3.1 KiB
Markdown
100 行
3.1 KiB
Markdown
# 规范-热更与兼容性
|
||
|
||
> **位置**: `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 向后兼容
|
||
|
||
```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）: 初始版本，覆盖热更规则、协议兼容、数据兼容
|
