版本 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 欄位。

阻絕程式碼產生/執行階段不匹配

根據我們的跨版本執行階段保證，Protobuf 不支援跨主要版本邊界混合使用產生的程式碼和執行階段，或在單一主要執行階段版本內混合使用較新版 protoc 產生的程式碼和較舊的執行階段。我們計劃引入「毒藥丸」來偵測並強制執行這些不允許的不匹配。

這不被視為重大變更，因為這只是增加了對現有政策的執行，但可能需要使用者更新其產生的程式碼。

C++ 重大變更

在 v26 中，我們正計劃根據我們的重大變更政策和版本支援政策，對 C++ 進行主要版本升級。

以下各節概述了我們計劃在 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 進行主要版本升級。

以下各節概述了我們計劃在 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 可迭代物件擴充重複欄位

從 26.x 版本開始，使用 None 可迭代物件擴充重複欄位將會被拒絕（它會引發 TypeError）。例如，m.repeated_int32.extend(None) 將會被拒絕。

移除訊息類別中的 RegisterExtension

從 26.x 版本開始，RegisterExtension 將會被移除。您可以使用訊息物件上的 Extensions 屬性存取 Python 中的擴充。

這會影響純 Python 和 Python 的 C++ 實作，但不影響 upb Python。

從 GitHub 移除 setup.py 和 setup.cfg 支援

在 26.x 版本中，setup.py 和 setup.cfg 將不再存在於 GitHub 儲存庫的 python/ 目錄或 GitHub 發佈 tarball 中。這表示將無法再直接從 GitHub 儲存庫或發佈 tarball 建立 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 用於測試重複欄位是否已封裝。
    • FieldDescriptor.requires_utf8_validation 用於測試字串欄位是否需要 UTF-8 驗證。
    • EnumDescriptor.is_closed 用於測試列舉是否已封閉。

Ruby 中的 Freeze 現在是遞迴的

從 26.x 系列開始，當套用凍結時，將會遞迴地套用，影響所有子訊息、映射和重複欄位。

upb 重大變更

以下變更計劃在 26.x 版本中進行