2.1 message字段与编号：不动产产权规则

2.1 message 字段与编号：不动产产权规则

本节摘要：message 是 proto 语言的细胞，字段编号是细胞里的 DNA。本节拆解字段声明的完整语法（类型、名字、编号、标签四要素），重点发掘字段编号的三段区间在字节层的成本差异、reserved 机制防止的事故模式，以及 package 与嵌套带来的命名空间隔离。读完你应当能为团队制定一份可执行的字段编号管理规范。

在发掘顺序上，本节处理地层的最小单元——一个字段怎么声明才安全。它承接第 1 章的"字段编号是身份"这个论断，把编号的产权规则讲透；通往 2.2 的类型系统与第 3 章 tag 的字节形态。

字段声明四要素

一条完整的 proto3 字段声明：

syntax = "proto3";
package inventory.v1;

message Artifact {
  string id = 1;         // 类型 字段名 编号
  reserved 6, 8 to 11;   // 产权注销声明
  reserved "weight", "origin";  // 连名字一起注销
  repeated string tags = 4 [deprecated = true];  // repeated 是标签（label）
}
​

四个要素里，类型和名字是给人看的，编号是给字节流看的，标签决定字段的出现次数语义（repeated 可重复、singular 至多一次）。第 1 章说过：字段名只活在编译期，序列化后的字节里只有编号——所以改名永远安全，改编号几乎永远是事故。

编号三段区间：为什么 15 是分界线

字段编号不是均匀的整数空间，它在字节层有三段截然不同的成本：

为什么 15 是分界线？tag 的编码规则（第 3 章逐字节拆解）是把编号左移三位再或上 wire type，编码成 varint。一个 varint 字节只有 7 个有效位，减去 3 个 wire type 位，剩 4 位——能表示的编号上限恰好是 15。于是字段 1 到 15 的 tag 只要一个字节（如字段 8 的 varint tag 是 08），字段 16 起就要两个字节（如字段 16 的 tag 是 80 01）。

这个差异乘上 repeated 字段会放大：一个出现 1000 次的 repeated 字段，用编号 8 比用编号 20 每条记录省 1 字节，总量省 1000 字节。所以团队规范常见一条：把最频繁出现的字段（尤其 repeated）安排在 1–15 号。注意管理动作：新项目不要一口气把 1–15 用完，留给后来者；字段删除后编号立刻进 reserved。

reserved：产权注销的唯一正道

删除字段是 proto 演进里最危险的动作。错误做法是直接删掉那一行：

// 三年前的写法（事故现场）
message Artifact {
  string id = 1;
  // int32 weight = 2;   ← 直接注释掉，编号 2 变成无主空地
  repeated string tags = 3;
}
​

半年后新同事加字段，顺手用了编号 2——而某个老服务还留着旧代码在发编号 2 的 weight 数据。新字段与旧 weight 在字节流里共用同一个身份，接收方按新契约解旧数据，读出语义错乱的值，且不报任何错。这就是编号重用事故，第 1.1 节悬案三种原因里的第一种。

正确做法是产权注销：

message Artifact {
  string id = 1;
  reserved 2;                    // 编号永久封存
  reserved "weight";             // 名字也封存，防止新字段冒用旧名误导
  repeated string tags = 3;
}
​

reserved 声明让 protoc 编译期就拒绝任何人再使用这些编号与名字。名字注销容易被忽视——名字重用虽然字节层安全（字节里只有编号），但会让旧代码的日志、监控、序列化 trace 里出现同名字段两种语义的解读混乱，一并封掉是低成本高回报的保险。

⚠️ 常见坑：reserved 的编号列表和名字列表要写两条独立语句（或用逗号并列），语法上编号与名字不能混在一条里。这是编译期错误里最高频的一种。

package 与命名空间

proto 文件顶部还有两个地层级的声明值得交代。package 提供命名空间隔离，避免多团队同名 message 撞车：

package inventory.v1;
message Artifact { ... }

package museum.v1;
message Artifact { ... }   // 不同 package，互不冲突
​

规范上建议 package 带版本号（v1），让第 5 章的大版本演进可以走"新建 v2 package"的平行扩容路线，而不是在原地改语义。嵌套 message 则提供了 message 内部的局部命名空间——考古现场常用的分层写法：

message Excavation {
  message Coordinate {          // 嵌套类型，全名为 Excavation.Coordinate
    int32 x = 1;
    int32 y = 2;
  }
  Coordinate location = 1;
  repeated Coordinate grid = 2;  // 嵌套类型与 repeated 组合表达点阵
}
​

嵌套深度建议不超过三层——proto 不限制嵌套层数，但超过三层的引用名（A.B.C.D）会显著伤害可读性，且部分老代码生成器对深嵌套支持不佳。

实战案例：给历史欠账做产权清算

背景：接手一个演进六年的 proto 文件，编号 1 到 40 用满了 38 个，中间散布着注释掉的字段与疑似重用过的编号，没有一条 reserved。操作：第一步，从 Git 历史把该文件所有历史版本拉出来，对每个编号建立"出现过的类型与字段名"清单；第二步，凡是被至少两个不同语义字段用过的编号（共发现 3 个），标记为"污染编号"——它们的旧数据无法被安全解读，只能靠业务层校验兜底；第三步，为全部 14 个已删除字段补上 reserved，与 3 个污染编号合并写入；第四步，新规范落地：新增字段从 41 号起跳，1–15 号剩余空位只准 repeated 高频字段使用。结果：清算后 protoc 编译通过，且一个下游 Java 服务在升级后立刻报出了两处此前静默的编号冲突——正是污染编号的旧债浮出水面。解读：reserved 的事后补写不能修复已损坏的历史数据，但能阻止欠账继续扩大；编号考古的价值在于把"哪些字节流可信"这个问题变成可回答的。变式：如果 Git 历史不可得，可以用第 3 章的 decode_raw 对存量线上消息抽样勘察，按字段编号反推实际使用情况。

本节要点回顾

• 四要素：类型、名字、编号、标签——前两个给人看，编号给字节流看，标签定出现次数；
• 三段区间：1–15 号 tag 一个字节（热区，留给高频与 repeated 字段）、16–2047 两个字节、19000 段禁用；
• 15 的来历：varint 单字节 7 有效位减去 3 位 wire type，剩 4 位恰好编到 15；
• reserved 是注销正道：删字段必封编号与名字，防重用事故；名字封存防解读混乱；
• package 带版本号：为将来平行扩容留路，嵌套不超三层。

编号定了身份，类型定语义。下一节进入类型系统：定长与变长整数怎么选、sint 为何存在、"没赋值"到底编码成什么。