于 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 版次字段
  • 版次的关键方法
    • hasPresence 成为确定单个字段是否跟踪存在性的主要方法，它反映了该字段的 features.field_presence 设置。
  • 迁移： 依赖 isRepeated 和 isRequired 来确定基数，并使用 hasPresence 检查单个字段的显式存在性跟踪。
• 对于 proto2/proto3 字段： getLabel 最终将被移除，在此期间不推荐使用。

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

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

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

时间线

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