Protobuf Editions 命名设计解析：从自由字符串到 Edition 枚举的取舍

本文导读：本篇基于 Protobuf 仓库中的设计文档 edition-naming.md（2023-08-25 批准）展开，完整还原 Editions 命名方案的设计动机、五条原始设计意图、推荐方案（Edition 枚举）与五个被否决的备选方案的权衡过程；并结合当前仓库中 descriptor.proto 的实际枚举定义与 protoc 解析器的实现源码，说明这一设计是如何落地演进的。读完后，你将理解为什么 edition = "2023" 这个看似简单的字符串最终被约束成"任意语言都能直接比较"的离散枚举值。

背景：松散的命名约定与跨语言比较负担

Life of an Edition 为 edition 命名给出了一套非常宽松的方案：只定义了顺序规则和 . 分隔符，除此之外对 edition 名称没有任何约束。社区随后约定俗成地采用"年份 + 可选修订号"的形式（例如 2023、2024.3）。

问题出在另一份设计文档 Editions: Life of a FeatureSet 中的决策上：feature 解析（feature resolution）至少需要部分地在每一种支持的语言中重复实现。按照 Life of a FeatureSet 的界定，需要重复的最小操作是两件事：

• edition 比较（edition comparison）
• proto 合并（proto merging）

edition 比较在当时并不算复杂，但由于 edition 名称的约束过于松散，比较逻辑里潜藏着大量可能遗漏的边界情况。设计者希望在任何语言里都能用简单的字典序字符串比较（lexicographical string comparison）完成 edition 比较，从而把每个运行时里的重复实现降到最简。

问题描述：松散命名的三类风险

边界情况与 Hyrum's Law 风险

允许无限多"实践中永远不会出现"的 edition 名称，会带来真实的 [Hyrum's Law] 风险。原文举了一个典型例子：2023.a 在当时是合法的 edition 名，而它与 2023.10 的相对顺序并不直观——按字典序 2023.10 < 2023.a（因为 1 < a），按数值语义却应该是 2023.a 在前（若 a 代表修订版）。此外，早期的 editions 测试中实际使用过一个叫 very-cool 的 edition 名，这显然不是一个需要长期支持的形态。结论是：edition 名应尽可能简单，且约束必须可执行、有文档。

Calver 视觉误导与"patch edition"混淆

edition 看起来像 calver（按日历年的版本号），导致大家把修订版称为 "patch editions"，暗示它是对早期 edition 的 bug 修复——但这并非原始设计意图。文档中明确了五条原始意图，值得逐条对照当前仓库的实现来理解：

1. Editions 严格按时间排序。修订号（revision）只是"一年内可以发布多个 edition"的机制，但不能往更早的槽位里插入新 edition。
2. 新 edition 可以随时添加。只要排在既有 edition 之后就是非破坏性变更，可以在 patch release 中完成。
3. 新 feature 可以随时添加，无需变更 edition。它按定义是非破坏性的，也可以放在 patch release。
4. feature 只能在破坏性 release 中删除。editions 模型不支持删除 feature——那永远是 breaking change，只会在 protobuf 的主版本号（major version）提升时发生。
5. feature 默认值只能在新 edition 中变更。一旦某个 feature 选定了默认值，只能靠发布带新默认值的新 edition 来改变；这仍是非破坏性变更，可走 patch release。

注意：第 2、3 条说明"新增 edition / 新增 feature 都不破坏兼容"，而"删除 feature / 改默认值"分别被限制在 major release 和新 edition 里——这正是 edition 作为单向时间轴的语义基础，也是后文"枚举必须时间有序"的根源。

设计目标：五条期望属性

文档列出了对 edition 命名机制的期望：

• 允许的值是离散的、由 protobuf 团队控制的；
• 易于比较；
• 跨语言支持；
• 集合规模较小（未来一个世纪内少于 100 个）；
• 增长缓慢（大约每年一次）。

这五条目标直接把解法指向了枚举：值域由维护者独占、整数天然可比、任意语言都能处理、规模可控。

推荐方案：Edition 枚举

方案草案

最简单的做法是专门建一个 Edition 枚举来指定 edition。proto 文件里继续使用字符串，但解析器会立刻把字符串转成枚举，之后的所有代码都按枚举处理。这样就有了一个集中式的、跨语言共享的"所有合法 edition 列表"。文档当时的草案是：

enum Edition {
  EDITION_UNKNOWN = 0;
  EDITION_2023 = 1;
  EDITION_2024 = 2;
  // ...
}

proto 文件中的写法与最初决策完全一致，仍是字符串：

edition = "2023";

文档同时声明：这些值意图上是可按数值比较的，用于确定 edition 的时间顺序。

与当前仓库实现的对照

当前 descriptor.proto 中的 Edition 枚举已经落地并进一步演化，比草案多了多个特殊占位值：

// The full set of known editions.
enum Edition {
  // A placeholder for an unknown edition value.
  EDITION_UNKNOWN = 0;

  // A placeholder edition for specifying default behaviors *before* a feature
  // was first introduced.  This is effectively an "infinite past".
  EDITION_LEGACY = 900;

  // Legacy syntax "editions".  These pre-date editions, but behave much like
  // distinct editions.  These can't be used to specify the edition of proto
  // files, but feature definitions must supply proto2/proto3 defaults for
  // backwards compatibility.
  EDITION_PROTO2 = 998;
  EDITION_PROTO3 = 999;

  // Editions that have been released.  The specific values are arbitrary and
  // should not be depended on, but they will always be time-ordered for easy
  // comparison.
  EDITION_2023 = 1000;
  EDITION_2024 = 1001;
  EDITION_2026 = 1002;

  // A placeholder edition for developing and testing unscheduled features.
  EDITION_UNSTABLE = 9999;

  // Placeholder editions for testing feature resolution. ...
  EDITION_1_TEST_ONLY = 1;
  EDITION_2_TEST_ONLY = 2;
  EDITION_99997_TEST_ONLY = 99997;
  EDITION_99998_TEST_ONLY = 99998;
  EDITION_99999_TEST_ONLY = 99999;

  // Placeholder for specifying unbounded edition support. ...
  EDITION_MAX = 0x7FFFFFFF;
}

对照草案可以确认三点演进事实（均有源码注释为证）：

• 正式 edition 的值不是草案里的 1、2，而是 1000、1001、1002；注释明确写着 "The specific values are arbitrary and should not be depended on, but they will always be time-ordered for easy comparison"——恰好兑现了文档中"数值可比较"的承诺，同时把具体数值声明为不可依赖。
• 枚举中额外加入了 EDITION_LEGACY（feature 引入之前的"无限过去"）、EDITION_PROTO2/PROTO3（用于兼容 feature 默认值定义，但不能用于指定 proto 文件的 edition）、EDITION_UNSTABLE（开发/测试未排期 feature）以及若干 *_TEST_ONLY 占位值——这些正是文档所警告的"边界情况"被枚举收编之后的形态。
• 仓库内确实存在使用这些 edition 的真实 proto，例如 editions/golden/test_messages_proto2_editions.proto 以 edition = "2023"; 开头，而 editions/codegen_tests/ 目录下按 edition2023_*、edition2024_* 组织着各命名风格与语言特性的测试 proto。

解析器如何把字符串变成枚举

文档说"parser will quickly convert them"，这条路径在当前 parser.cc 中可以完整看到。ParseSyntaxIdentifier 处理文件首句：

if (has_edition) {
  if (!Edition_Parse(absl::StrCat("EDITION_", syntax), &edition_) ||
      edition_ == Edition::EDITION_PROTO2 ||
      edition_ == Edition::EDITION_PROTO3 ||
      edition_ == Edition::EDITION_UNKNOWN) {
    RecordError(syntax_token.line, syntax_token.column, [&] {
      return absl::StrCat("Unknown edition \"", syntax, "\".");
    });
    return false;
  }
  syntax_identifier_ = "editions";
  return true;
}

这段代码与文档描述逐条对应：

• 字符串拼接成 EDITION_<名字> 后调用生成的 Edition_Parse，未知 edition（无论未来还是已被移除的）直接报 Unknown edition "..." 错误——这正是推荐方案 Pros 里说的 "Automatic rejection of unknown editions"，不需要任何自定义逻辑；
• EDITION_PROTO2 / EDITION_PROTO3 / EDITION_UNKNOWN 被显式排除，与枚举注释"can't be used to specify the edition of proto files"一致；
• 解析成功即 syntax_identifier_ = "editions"——即文档中提到的"syntax gets set to editions by the parser when an edition is found"这一事实；
• 文件必须以 edition 或 syntax 声明开头（parser.cc 中 require_syntax_identifier_ || LookingAt("syntax") || LookingAt("edition") 分支），缺失时回退 proto2 并告警。

开放枚举的取舍与"revision 暂缓"

文档还讨论了理想状态下应使用开放枚举（open enum），避免某个 edition 值落入 unknown field set。但该枚举必须存在于 descriptor.proto，因此在完成 edition zero 迁移之前无法改为开放枚举。过渡方案正是上面看到的解析器行为：edition 出现时 syntax 被置为 editions，此时未设置 edition 应视为错误；等迁移到开放枚举后，可以再换成更简单的合法性检查。

关于修订号（revisions），文档的决定是直接不做：暂时不允许 2023.1 这类修订版；"如果我们真需要超过一个 revision，说明犯了大错，到时再讨论命名（比如 EDITION_2023_OOPS）"。规划上保持每年恰好一个 edition。

推荐方案的利弊（文档原文立场）

Pros：

• edition 比较更简单了——就是整数比较，从而每个语言里的 feature resolution 都变得平凡（trivial）；
• 自动拒绝未知 edition（包括未来的、被移除的、未知修订号），其他方案需要 protoc 里的自定义逻辑来强制；
• 不再"长得像 calver"，避免上述命名混淆；
• 没有修订号简化了文档，edition 更易理解和维护。

Cons：

• 将来把 descriptor.proto 迁移到 editions 时可能有挑战；
• 解析器实现上可能有点棘手（但文档指出 Prototiller 已经处理得很好——事实上当前 C++ 解析器也已如上实现）。

被否决的备选方案

文档逐一评估了五个替代方案，权衡过程对理解最终形态很有价值。

1. Proto 文件内直接用枚举值

不用字符串，edition 直接写枚举，例如：

enum Edition {
  E2023  = 1;
  E2023A = 2;
  E2024  = 3;
}

• Pros：整数比较更简单；一年内可有任意数量 revision；闭枚举自动拒绝未知 edition；不像 calver。
• Cons：可读性变差（edition = E2023A 不如 edition = "2023.1" 直观）；可能要求解析器变更才能把 descriptor.proto 迁上 editions；是大改动，需要更新文档与对外沟通；插件作者无法预发布即将上线的 feature（文档还自问：我们是否真该允许这件事）。
• Neutral：edition 必须严格时间有序，不能回头给旧 revision 加东西（原方案本来也不允许）；edition 顺序与名字完全脱钩，需要写反射测试强制值严格递增。

2. 截断修订号（Truncated Revisions）

最贴近原计划的方案：限制每年至多 9 个中间 edition，即 edition 要么只是年份（2023），要么带一位修订号（2024.3）；修订号约束在 (0,9]，年份必须是 >=2023 的整数。这样 edition 排序就退化为简单的字典序字符串比较。

• Pros：严格收紧命名、避免意外边界情况；比较代码极易在各语言复制（就是字符串比较）；消除 revision 0 的歧义（2023.0 不合法）。
• Cons：限制每年至多 10 个 edition（看起来合理；由于 protoc 负责强制，日后还可重审；只要保持字典序就可任意扩展）。

3. 固定长度 edition（Fixed Length）

总是从 .0 开起，Edition Zero 就成了 2023.0。利弊同上一方案，额外地：

• Pros：修订版不再突兀——习惯 2023.0 的用户看到 2023.1 不会困惑。
• Cons：对外发布的沟通与文档已经称首个 edition 为 2023，改名需要更新传播；目前没有修订号的真实用例，却给"典型情况"增加了复杂度。

4. Edition 消息（message）

用带结构的消息建模 edition：

message Edition {
  uint32 year = 1;
  uint32 revision = 2;
}

• Pros：schema 本身自动强制大部分约束；允许任意数量 revision；不可能误用字符串比较。
• Cons：每种语言仍需要自定义比较代码（代价略高于字符串比较）；要么在解析期把 edition 字符串转成该 message，要么彻底改变 edition 的声明语法。

5. 什么都不做（Do Nothing）

• Pros：当下省事。
• Cons：明天要把比较代码复制到每种语言时更难；向 Hyrum's Law 和意外滥用敞开大门。

从设计到落地：仓库中的验证点

把文档结论映射回当前仓库，可以形成一条完整证据链：

文档主张	仓库证据
proto 文件仍用字符串，解析器立即转枚举	edition = "2023";（test_messages_proto2_editions.proto）+ Edition_Parse("EDITION_" + syntax)（parser.cc）
未知 edition 自动拒绝	解析失败时报 Unknown edition "..."（parser.cc）
edition 存在时 syntax 置为 editions	syntax_identifier_ = "editions";（parser.cc）
数值可比较、时间有序	Edition 枚举注释"always be time-ordered for easy comparison"（descriptor.proto）
值域集中、离散、跨语言共享	枚举定义于 descriptor.proto，供所有语言运行时引用

同时，What are Protobuf Editions 中"protoc specifies which editions it understands, and will reject .proto files (that use editions it does not understand)"的表述，与上述解析器行为相互印证：拒绝未知 edition 的机制不是附加逻辑，而是枚举本身带来的免费能力。

小结

Edition 命名设计的核心洞见是：把"edition 名"从一个人类可读的自由字符串重新定义为一个机器可比较的离散枚举，字符串只是 proto 文件里的声明语法糖。这一取舍用很小的解析器改动（字符串 → 枚举名 → 整数）换来了三个持久收益：任意语言里 edition 比较都是整数比较、未知 edition 被自动拒绝、且彻底摆脱了 calver 外观造成的"patch edition"误解。而被否决的方案（截断修订号、固定长度、edition message 等）则留档说明了为何"每年一个 edition、无修订号"是当前最简且可扩展的约束。若后续需要追踪 feature 在各 edition 间的默认值流转，可继续阅读 editions-life-of-a-featureset.md 与 life-of-an-edition.md。