Version 26.x 的新闻公告

为 Protocol Buffers 版本 26.x 宣布的变更。

以下公告特定于版本 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 Pilling Gencode / 运行时不匹配

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

由于这只是添加了对现有策略的强制执行，因此不被认为是破坏性变更，但可能需要用户更新其生成的代码。

C++ 破坏性变更

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

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

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

以下已弃用的方法已移除

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

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

随着 版本 的发布，语法不再支持业务逻辑。相反，请使用 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 将中断与旧主要版本生成的代码的兼容性。用户应重新生成旧生成的代码，使其与同一版本一致。

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

这符合我们现有的 跨版本运行时保证，并且是一个破坏性变更。

移除已弃用的方法/变量

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

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

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

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

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

  • 旧 v2.x.x gencode 兼容性的运行时方法。根据我们的 跨版本运行时保证，不再支持此功能。

更多详细信息将在相应的发行说明中提供。

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 Iterable 扩展重复字段

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

在消息类中移除 RegisterExtension

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

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

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

在 26.x 版本中，setup.py 和 setup.cfg 将不再存在于 GitHub 存储库 或 GitHub 发布 tarball 的 python/ 目录中。这意味着将不再可能直接从 GitHub 存储库或发布 tarball 构建 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 和相关的兼容性代码，这将完成 4 月宣布的迁移。
  • 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 用于测试枚举是否已关闭。

Freeze 现在在 Ruby 中是递归的

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

upb 破坏性变更

以下变更是针对 26.x 系列计划的