📚 课程目录第2章数据结构基础

数据结构基础：Schema定义、字段类型、嵌套结构、枚举类型

聊状态数据结构，咱们得从最基础的东西说起。你想想看，一个状态数据要能演进出新版本，首先得把「地基」打牢。这个地基，就是 Schema 定义、字段类型、嵌套结构和枚举类型。我在项目中见过太多因为地基没打好，后面改起来痛不欲生的案例。嗯，咱们一个一个来拆。

Schema 定义：给数据立规矩

说白了，Schema 就是一份「数据说明书」。它告诉系统：这个状态里有哪些字段，每个字段叫什么名字，是什么类型，能不能为空。没有 Schema，数据就是一盘散沙。

我个人习惯用 Protocol Buffers（protobuf）来定义 Schema。为什么？因为它天生就是为「演进」设计的。来看一个最简单的例子：

syntax = "proto3";

message UserState {
  int32 user_id = 1;
  string user_name = 2;
  string email = 3;
}

这里每个字段后面的数字（1、2、3）是 字段编号，不是默认值。这个编号是 Schema 演进的「锚点」——一旦定下来，就别改了。我曾经见过一个团队，因为觉得编号「看着不顺眼」就重新排了一遍，结果线上数据全乱了。嗯，血的教训。

避坑指南：字段编号一旦发布，永久保留。删除字段时，用 reserved 关键字标记已废弃的编号，防止未来误用。

字段类型：选对类型，少走弯路

字段类型的选择，直接影响后续的兼容性。我把它分成三类来说：

类型类别	常见类型	兼容性要点
标量类型	int32、int64、float、double、bool、string、bytes	同大类可互转（如 int32 → int64），跨大类不兼容
复合类型	message、map、repeated	嵌套 message 需单独管理版本；map 的 key 类型不可变
特殊类型	enum、oneof、Any	enum 新增值需谨慎；oneof 整体替换时破坏兼容

这里有个细节：int32 和 sint32 虽然都是整数，但编码方式不同。int32 用可变长编码，负数占 10 个字节；sint32 用 ZigZag 编码，负数只占 1-5 个字节。如果你确定字段值可能为负，用 sint32 更省空间。我在做游戏排行榜状态时，就因为这个选择，单条记录省了 40% 的存储。

小技巧：不确定用哪种整数类型时，优先选 int64。它兼容所有整数类型，而且现代 CPU 处理 64 位整数几乎没有性能损失。

嵌套结构：层次化组织数据

真实世界的状态数据很少是扁平的。用户信息里嵌套地址，订单里嵌套商品列表——这种层次关系，用嵌套结构来表达最自然。

message Address {
  string country = 1;
  string city = 2;
  string detail = 3;
}

message UserState {
  int32 user_id = 1;
  string user_name = 2;
  Address address = 3;  // 嵌套 message
  repeated string tags = 4;  // 重复字段
}

嵌套结构在演进时有个坑：内层 message 的变更会影响所有外层使用者。比如你给 Address 加了一个 postal_code 字段，所有引用 Address 的 message 都会自动「继承」这个新字段。听起来很方便？但如果你只想让某个特定的 UserState 使用新字段，其他场景保持原样，嵌套结构就做不到。

我遇到过一个案例：订单系统和物流系统共享同一个 Address 定义。订单系统加了「收货人电话」字段，物流系统没做任何适配，结果反序列化时直接报错。解决方案？要么拆成两个独立的 Address，要么用 oneof 做条件分支。

  核心原则：嵌套结构适合「强耦合」的父子关系。如果两个模块只是「恰好有相同结构的数据」，别偷懒，各自定义一份。

枚举类型：有限集合的优雅表达

枚举（enum）用来表示一组固定的取值。比如用户状态：在线、离线、忙碌、隐身。用枚举比用魔法数字（0、1、2、3）可读性强太多了。

enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;
  USER_STATUS_ONLINE = 1;
  USER_STATUS_OFFLINE = 2;
  USER_STATUS_BUSY = 3;
  USER_STATUS_INVISIBLE = 4;
}

注意第一个值必须是 0，而且名字要带上 UNSPECIFIED 或 UNKNOWN 后缀。为什么？因为 protobuf 在反序列化时，如果遇到未知的枚举值，会默认返回 0。如果你把 0 定义成「在线」，那未知值就会被错误地解析为「在线」——这 bug 藏得够深吧？

枚举的演进要格外小心。我建议遵循三条规则：

只增不减：可以加新值，但不要删除旧值。用 reserved 标记废弃值。
不改变语义：不要把 1 从「在线」改成「离线」，老数据会全乱。
预留别名：如果某个值要废弃，用 alias 保留旧名称，方便迁移。

避坑指南：我曾经在微服务间共享枚举定义。A 服务新增了一个枚举值，B 服务没更新 proto 文件。结果 B 服务收到新值后，直接抛异常。后来我们加了一个「未知值兜底逻辑」——收到不认识的值，记录日志，走默认分支，而不是直接崩溃。

知识体系总览

下面这张图把本章的核心知识点串起来了。你可以把它当作一个「检查清单」——设计状态数据结构时，对着这张图过一遍，基本不会漏掉关键点。

这张图里，Schema 定义是中心，四个分支分别对应字段编号、字段类型、嵌套结构和枚举类型。每个分支下面还有更细的要点。你设计状态数据结构时，可以把它当作一个「检查清单」——对着过一遍，基本不会漏掉关键点。

小结

这一章我们聊了 Schema 定义、字段类型、嵌套结构和枚举类型。这些东西看起来基础，但恰恰是这些「基础」决定了你的状态数据能不能平滑演进。我个人经验是：花 80% 的时间把 Schema 设计好，后面 20% 的时间做兼容性测试就够了。如果 Schema 设计得草率，后面 80% 的时间都在填坑。