2025 年 7 月 14 日宣布的变更

弃用 FieldDescriptor 枚举

我们宣布一项即将发生的变更，涉及 FieldDescriptor 枚举及其关联的表示 optional、required 和 repeated 的值。我们正在弃用这些值，并鼓励使用更精确的访问器方法。

背景

虽然 FieldDescriptor.label 枚举曾一度有用，但随着 Protocol Buffers 的发展，已经引入了更符合语言习惯的方式来确定字段的基数（单一/重复）和存在性语义。

• 在 proto2 中，optional、required 和 repeated 是显式关键字。
• 在 proto3 中，不再支持 required。所有标量字段都隐式地是“optional”的，即如果未设置，它们将具有默认值。后来在 proto3 中重新引入了 optional 关键字，以明确跟踪标量字段的存在性（区分未设置的字段和设置为其默认值的字段）。
• 在 2023 版中，我们移除了 optional 和 required 关键字，并使用特性来控制这些行为。

label 枚举混淆了这些不同的概念（基数、必需性和显式存在性跟踪），可能导致混淆，尤其是在 proto3 的字段存在性模型中。

影响与迁移

FieldDescriptor.label 字段最终将从 API 中移除。

请注意，本主题中的方法名称在某些语言中的拼写可能略有不同。

• 对于 Protocol Buffer Editions 字段
  • Editions 的关键方法
    • hasPresence 成为确定单个字段是否跟踪存在性的主要方法，它反映了该字段的 features.field_presence 设置。
  • 迁移： 依赖 isRepeated 和 isRequired 来确定基数，并使用 hasPresence 来检查单个字段中的显式存在性跟踪。
• 对于 proto2/proto3 字段： getLabel 最终将被移除，在此期间不建议使用。

所有在其代码中与 FieldDescriptor 对象交互的 Protocol Buffers 用户（例如，用于代码生成、反射和动态消息处理）都应停止直接使用 FieldDescriptor.label。

请更新您的代码以使用以下方法：

• 检查字段是否为 repeated：field.isRepeated
• 检查字段是否为 required（仅限 proto2 和 editions）：field.isRequired
• 检查单个字段是否具有显式存在性，请使用 hasPresence

时间线

此弃用立即生效。虽然 getLabel 将继续工作，但我们建议您主动迁移代码以确保未来的兼容性和清晰度。这一变更将为使用 Protocol Buffers 的开发者带来更稳健、更易于理解的体验。