Version 26.x 新闻公告

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

以下公告仅针对 Version 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 字段。

Poison Pill 代码生成 / 运行时不匹配

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

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

C++ 破坏性更改

根据我们的破坏性更改策略和版本支持策略，我们计划在 v26 中对 C++ 进行主要版本升级。

以下部分概述了我们计划包含在 Protocol Buffers 26.0 版本中的一系列破坏性更改。请注意，计划可能会改变，而且确实会改变。这些是需要注意的潜在破坏性更改，但它们可能不会在此特定版本中发生，或者根本不会发生。

移除 repeated 字段上已弃用的 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 将破坏与旧主要版本生成代码的兼容性。用户应重新生成旧代码，使其与运行时版本相同。

例如，GeneratedMessageV3（最初是为了与 v3.x.x 运行时兼容 v2.x.x 生成的代码而引入的）将被重命名为 GeneratedMessage。运行时将更新以支持 Editions，而 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

拒绝使用 None 可迭代对象扩展 repeated 字段

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

移除消息类中的 RegisterExtension

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

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

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

在 26.x 版本中，GitHub 仓库的 python/ 目录或 GitHub 发布 tar 包中将不再包含 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 中，纯 Python 和 C++ 扩展中的 message.UnknownFields() 已被弃用。我们计划在 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 用于测试 repeated 字段是否是 packed 类型。
    • FieldDescriptor.requires_utf8_validation 用于测试字符串字段是否需要 UTF-8 验证。
    • EnumDescriptor.is_closed 用于测试枚举是否关闭。

Ruby 中 Freeze 现在是递归的

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

upb 破坏性更改

计划在 26.x 系列中进行以下更改