2.3 枚举、oneof、map与嵌套消息
2.3 枚举、oneof、map 与嵌套消息
本节摘要：复合结构是 proto 语言的三种粘合剂：枚举把受限整数变成有名字的语义集合（第一编号必须为 0 的规则与未知枚举值行为是两大考点）、oneof 表达互斥多态语义（赋值即覆盖是最大陷阱）、map 在编码层的真身是重复的键值 message（超大 map 有单字节流风险）。本节给出每种结构的使用时机、字节层实质与工程禁区。
本章的收官之节：2.1 定字段身份、2.2 定标量语义，本节把它们组织成真实的业务结构。这些结构都会在第 3 章的字节流里现出原形——尤其是 map，它的编码真身会让很多人意外。
枚举：给整数发铭文牌
枚举把一组魔法数字变成自解释的名字集合：
message Excavation { enum Phase { PHASE_UNSPECIFIED = 0; // 第一编号必须为 0 PHASE_SURVEY = 1; PHASE_DIG = 2; PHASE_REPORT = 3; } Phase phase = 1; }
三条铁规。其一，第一编号必须为 0（proto3 强制），惯例命名成 XXX_UNSPECIFIED——因为 proto3 的"未赋值返回默认值"行为，字段没有值时会返回第一个枚举值，让它表示"未指定"而不是某个具体业务态，可以避开大量误判。其二，枚举编号同样适用字段编号的产权规则：删除枚举值后编号要进 reserved，重用编号等于让旧数据瞬间改换语义。其三，未知枚举值的行为：接收方版本旧、不认识新枚举值时，各语言运行时的处理策略不同——多数现代实现会把它保留为未识别的原始整数（C++/Go 存为未知字段意义上的数值），但循环进旧代码的 switch/if 链时会落到"不是任何已知值"的分支，你的代码必须为这个分支写好降级逻辑，而不是假设枚举值永远只有已知几种。
enum Phase { reserved 4, 5; // 注销两个已废弃的枚举编号 reserved "PHASE_ARCHIVE"; // 名字一并注销 PHASE_UNSPECIFIED = 0; PHASE_SURVEY = 1; PHASE_DIG = 2; PHASE_REPORT = 3; }
oneof：互斥语义的唯一正统表达
业务里常有"多选一"结构：登录凭证要么是密码、要么是验证码、要么是生物特征。用三个 optional 字段表达，语义上允许三者同时出现，校验逻辑散落各处；oneof 在契约层就把互斥焊死：
message Credential { oneof kind { string password = 1; string sms_code = 2; bytes biometric = 3; } int64 issued_at = 4; // oneof 之外的字段不受影响 }
两个必须刻进肌肉记忆的行为。赋值即覆盖：给 oneof 组内任何一个字段赋值，会清除组内其他字段的已赋值状态——设置 password 再设置 sms_code，password 就是没了，不是"两个都有"。反序列化同理：字节流里若出现同组多个字段（畸形消息或旧数据），只有最后一个存活。所以互斥字段永远放进 oneof，别用平行 optional 模拟。
presence 免费：oneof 组内字段天然有"设置与否"的判断能力（多数语言生成的代码可以查 oneof 当前激活的是哪个字段），这也让它成为 2.2 节说的 0 值盲区解法之一——把需要区分"0 与缺席"的标量单独包一个 oneof 组。editions 的显式 presence 出现后这个技巧用得少了，但存量代码里大量存在，读得懂是必备能力。
map：真身是重复 message
proto3 原生支持 map 字段：
message ArtifactIndex { map<string, int32> counts = 1; map<string, Excavation.Coordinate> positions = 2; // 值可以是消息 }
关键认知：map 在编码层没有专属形态，它的真身是"一个 repeated 的键值对 message"——编译器在背后生成一个隐藏的 CountsEntry { string key = 1; int32 value = 2; } 消息，counts 的字节流就是一串重复的 CountsEntry。确认这件事的方法很考古：用 decode_raw 解码一条带 map 的消息，你会看到字段 1 出现 N 次、每次是一段嵌套字节——与 repeated message 的形态别无二致。
由真身推出的三个工程结论：
- 键序不保证：map 的遍历顺序在任何语言里都不承诺与写入顺序一致，依赖键序的逻辑要把 map 换成 repeated 的自定义键值结构；
- 超大 map 是单字节流风险：十万元素的 map 序列化成一整条消息，解码方必须整条读完才能开始处理——内存与延迟都是刚性的。流水线式处理大映射时，改用流式的外层 repeated 包小 message；
- map 字段的更新语义是"整条替换"：多数反射式更新（比如配置下发场景的 merge）对 map 的处理是逐键覆盖，但直接赋值 map 字段是整体替换，两种语义的边界要在代码评审里盯紧。
嵌套与组合：什么时候建新 message
复合结构的最后一块拼图是组织哲学：什么时候把一组字段提升为独立的嵌套 message？判断标准不是"字段数量"，而是这组字段是否有独立的生命周期与复用可能。坐标的 x 与 y 永远同生共死，天生该是一个 message；而"姓名+昵称+头像"如果只在用户消息里出现一次，内联平铺即可，过早抽象出的 Profile message 往往变成演进包袱（第 5 章会看到，message 类型的复用契约一旦建立就很难收回）。
message ExcavationReport { message Trench { // 有独立生命周期：一条探方单独演进 string id = 1; repeated Artifact finds = 2; } message Artifact { // 高复用：被多处引用 string catalog_no = 1; Excavation.Coordinate found_at = 2; // 跨 message 引用嵌套类型 } repeated Trench trenches = 1; string title = 2; // 低复用字段直接平铺，不过度抽象 }
实战案例：登录凭证契约的重构
背景：某系统的用户消息用三个平行 optional 字段表达凭证类型（password、sms_code、device_token），外加一个 int 凭证类型码。运行三年的问题：偶发"两个字段同时有值"的脏数据（各服务写入路径没统一校验），以及类型码与实际字段不符的错位。操作：重构为 oneof 结构，凭证类型码删除（类型由 oneof 激活字段自解释）；灰度期间旧字段保留但标注 deprecated，新旧并存靠转换层；枚举类型码注销编号进 reserved。结果：重构上线后"双凭证脏数据"归零——因为 oneof 的覆盖语义让"同时有两个值"在字节层不可能出现。解读：契约层的表达力比校验代码更可靠，校验会漏、编译期结构不会。变式：如果凭证类型未来要跨服务传递并保留扩展点，oneof 加上第六章的 Any 机制可以支持"未知类型透传"，但多数场景 oneof 足够。
本节要点回顾
- 枚举三铁规：第一编号为 0 且命名 UNSPECIFIED、编号同样要 reserved、未知枚举值必须有降级分支；
- oneof 赋值即覆盖：互斥字段进 oneof，畸形多字段消息里只有最后一个存活；
- oneof 免费送 presence：是 0 值盲区的经典解法，存量代码识别必备；
- map 真身是重复键值 message：键序不保证、超大 map 单字节流风险、赋值即整体替换；
- 抽象看生命周期与复用：字段独立演进才建 message，否则平铺，过度抽象是演进包袱。
地层与铭文到此发掘完毕。下一章进入最深处：wire format。编号在字节里占几位、varint 怎么切字节、ZigZag 的映射公式、嵌套消息的长度前缀——每一层铭文都将在十六进制里现出原形。