版本 26.x 的新闻公告

Protocol Buffers 版本 26.x 的变更公告。

以下公告特定于 2024 年 3 月 13 日发布的版本 26.x。有关按时间顺序排列的信息，请参阅新闻。

常规变更

JSON 格式化程序选项变更

从 26.x 系列开始，用于打印具有默认值字段的 JSON 格式化程序选项将被一种固定的方式取代，以一致地处理 proto2 和 proto3 的 optional 字段。

  • Java: includingDefaultValueFields() 被替换为 alwaysPrintFieldsWithNoPresence()。
  • C++: always_print_default_values 被替换为 always_print_fields_with_no_presence=True。
  • Py: including_default_value_fields=True 被替换为 always_print_fields_with_no_presence=True。

新标志在 proto3 消息上的行为与旧标志完全相同，但不再适用于 proto2 的 optional 字段。旧标志适用于 proto2 的 optional 字段，但不适用于 proto3 的 optional 字段。

对生成代码/运行时不匹配进行“毒丸”处理

根据我们的跨版本运行时保证，Protobuf 不支持跨主版本边界混合使用生成的代码和运行时，也不支持在单个主运行时版本中将较新版本的 protoc 生成的代码与较旧的运行时混合使用。我们计划引入“毒丸”来检测和强制执行这些不允许的不匹配情况。

这不被视为重大变更，因为它只是增加了对现有策略的强制执行，但可能需要用户更新其生成的代码。

C++ 重大变更

在 v26 中，我们计划根据我们的重大变更政策和版本支持政策对 C++ 进行主版本升级。

以下各节概述了我们计划在 protocol buffers 26.0 版本中包含的一系列重大变更。请注意，计划可能会发生变化。这些是需要注意的潜在重大变更，但它们可能不会在这个特定版本中发生，或者根本不会发生。

移除重复字段上已弃用的 clear API

以下已弃用的方法将被移除

  • RepeatedPtrField::ReleaseCleared()
  • RepeatedPtrField::ClearedCount()
  • RepeatedPtrField::AddCleared()

移除 C++ 旧版语法描述符 API

随着版本 (editions)的发布，业务逻辑不再支持语法。相反，应使用descriptor.h中定义的各种特性辅助函数来查询更具针对性的行为，例如使用has_presence在 C++ 中查询特性。

移除已弃用的语法访问器

我们计划在 v26 中移除已弃用的语法访问器 FileDescriptor::Syntax。我们建议改用 FileDescriptor::edition 的 getter 方法。

移除已弃用的 SupportsUnknownEnumValues 方法

SupportsUnknownEnumValues 方法已于2023 年 3 月被弃用。我们计划在 v26 中将其移除。

移除 std::string 错误收集器重载

我们计划移除错误收集器中已弃用的 std::string 方法。

Java 重大变更

在 v26 中，我们计划根据我们的重大变更政策和版本支持政策对 Java 进行主版本升级。

以下各节概述了我们计划在 protocol buffers 26.0 版本中包含的一系列重大变更。请注意，计划可能会发生变化。这些是需要注意的潜在重大变更，但它们可能不会在这个特定版本中发生，或者根本不会发生。

与旧版生成代码的兼容性中断

v26.x 将中断与旧主版本生成的代码的兼容性。用户应重新生成旧代码，使其与当前版本一致。

例如，最初为与 v3.x.x 运行时兼容的 v2.x.x 生成代码而引入的 GeneratedMessageV3 将重命名为 GeneratedMessage。运行时将更新以支持版本 (Editions)，这将与旧的生成代码不兼容。

这符合我们现有的跨版本运行时保证，并且是一项重大变更。

移除已弃用的方法/变量

v26.x 将移除对已弃用方法和变量的访问。这些通常在之前的版本中已被标记为 @Deprecated。

这将移除对以下（非详尽）列表的访问

  • 描述符语法 API，应替换为相应的特性访问器（例如 FieldDescriptor.hasPresence(), EnumDescriptor.isClosed()）

  • TextFormat 打印方法，应替换为相应的 TextFormat.printer() 方法。

  • PARSER 变量，应替换为 parser() 方法。

  • 用于兼容旧版 v2.x.x 生成代码的运行时方法。根据我们的跨版本运行时保证，这已不再受支持。

更多细节将在相应的版本说明中提供。

PHP 重大变更

为 26.x 系列计划了以下变更

  • 在 setter 中验证字符串字段的 UTF-8 编码。
  • 移除通用服务。（commit 40ad3fa）

Python 重大变更

在 v26 中，我们计划根据我们的重大变更政策和版本支持政策对 Python 进行主版本升级。

为 26.x 系列计划了以下变更

  • 使 str(msg) 对字符串字段中任何无效的 UTF-8 进行转义。
  • 使 text_format.MessageToString() 默认输出原始 UTF-8，同时对任何无效的 UTF-8 序列进行转义。
  • 修复时间戳边界（commit 1250d5f）

移除已弃用的 API

在 26.x 版本中，以下已弃用的 API 将被移除

拒绝使用不可迭代对象扩展重复字段

从 26.x 版本开始，使用 None 可迭代对象扩展重复字段将被拒绝（将引发 TypeError）。例如，m.repeated_int32.extend(None) 将被拒绝。

移除 message 类中的 RegisterExtension

从 26.x 版本开始，RegisterExtension 将被移除。您可以在 Python 中使用消息对象上的 Extensions 属性来访问扩展。

这会影响纯 Python 和 Python 的 C++ 实现，但不会影响 upb Python。

从 GitHub 移除对 setup.py 和 setup.cfg 的支持

在 26.x 版本中，GitHub 仓库或 GitHub 发布 tar 包的 python/ 目录中将不再包含 setup.py 和 setup.cfg。这意味着将无法再直接从 GitHub 仓库或发布 tar 包构建 Python 包。

发布在 PyPI 上的 Python 源码包的顶层目录中仍将包含一个 setup.py。对于不想使用我们在 PyPI 上分发的二进制包的用户，这是构建 Python 二进制包的支持和推荐方式。

更多信息，请参阅 #15671。

时间戳将进行有效性检查

在 v26 中，系统将检查 Timestamp 值是否有效。秒数必须在 [-62135596800, 253402300799] 范围内，纳秒数必须在 [0, 999999999] 范围内。超出这些范围的值将引发异常。

移除已弃用的语法访问器

我们计划在 v26 中移除已弃用的语法访问器 FileDescriptor.syntax。我们计划用 FileDescriptor.edition 来替代它。

移除对 UnknownFields 的支持

在 v25 中，message.UnknownFields() 在纯 Python 和 C++ 扩展中已被弃用。我们计划在 v26 中将其移除。请使用 unknown_fields.py 中新的 UnknownFieldSet(message) 支持作为替代。

有关所有这些变更的更多细节将在相应的版本说明中提供。

Ruby 重大变更

  • 修复 RepeatedField#each_index 以具有正确的语义。（#11767）
  • 移除 Ruby DSL 及相关的兼容性代码，这将完成四月份宣布的迁移。
  • Message#to_h 修复
    • 移除未设置的 oneof 字段。（#6167）
    • 移除未设置的子消息字段
  • 为 encode_json/decode_json 使用消息的池。
  • 移除已弃用的语法访问器 FileDescriptor.syntax，并用语义检查来替代它
    • FieldDescriptor.has_presence 用于测试字段是否存在。
    • FieldDescriptor.is_packed 用于测试重复字段是否已打包。
    • FieldDescriptor.requires_utf8_validation 用于测试字符串字段是否需要 UTF-8 验证。
    • EnumDescriptor.is_closed 用于测试枚举是否为封闭的。

Ruby 中的 Freeze 现在是递归的

从 26.x 系列开始，当应用 freeze 时，它将递归应用，影响所有子消息、映射和重复字段。

upb 重大变更

为 26.x 系列计划了以下变更