Version 30.x 新聞公告

針對 Protocol Buffers 版本 30.x 公告的變更。

以下公告專屬於 Version 30.x。如需依時間順序呈現的資訊，請參閱新聞。

以下章節涵蓋預計在 2025 年第一季發布的 v30 版本中的計畫性重大變更。其中也包含一些非重大變更，但可能需要您採取行動。這些變更描述了我們預期實作的方式，但由於軟體的彈性本質，其中某些變更可能不會實現，或者可能與本主題中的描述有所不同。

C++ 的變更

C++ 將主要版本從 5.29.x 提升至 6.30.x。

Descriptor API

v30 將更新 descriptor 中的傳回類型 (例如 full_name) 為 absl::string_view。這將開啟 descriptor 中的記憶體節省。

v28 引入了 PROTOBUF_FUTURE_STRING_VIEW_RETURN_TYPE 巨集，您可以在此期間使用它來在重大版本發布之前啟用更新的傳回類型。v30 版本將翻轉預設值並移除巨集。

ctype 從 FieldDescriptor 選項中移除

v30 將停止公開 FieldDescriptor 選項中的 ctype。您可以改用 v28 版本中新增的 FieldDescriptor::cpp_string_type() API。

以 Fetched Deps 取代 CMake 子模組

v30 將移除子模組並切換至 upb 的舊 CMake 模式以擷取依賴項。

如果您使用已安裝的套件，您將不會受到影響。這可能會破壞某些 CMake 工作流程。

修改 Debug API 以編輯敏感欄位

我們計畫在 v30 中修改 Protobuf debug API (包括 Protobuf AbslStringify、proto2::ShortFormat、proto2::Utf8Format、Message::DebugString、Message::ShortDebugString、Message::Utf8DebugString) 以編輯由 debug_redact 註解的敏感欄位；這些 API 的輸出將包含每個程序的隨機前綴，因此 Protobuf TextFormat Parser 將不再可解析這些輸出。

請參閱2024 年 11 月 21 日發布的新聞文章，以瞭解更多資訊。

移除與 Reflection 相關的函式

我們正在移除以下與 reflection 相關的函式：MutableRepeatedFieldRef<T>::Reserve()。

RepeatedPtrField 中即將推出的效能改進與此 API 不相容。預計此改進將加速重複存取 RepeatedPtrField 的元素，特別是循序存取。

移除已棄用的 API

v30 將移除以下已標記為棄用 (例如 ABSL_DEPRECATED) 至少一個次要或主要版本，且已過時或被取代的公開執行階段 API。

Arena::CreateMessage

API： Arena::CreateMessage

取代項目： Arena::Create

Arena::GetArena

API： Arena::GetArena

取代項目： value->GetArena()

RepeatedPtrField::ClearedCount

API： RepeatedPtrField::ClearedCount

取代項目： 遷移至 Arenas (遷移指南)。

JsonOptions

API： JsonOptions

取代項目： JsonPrintOptions

捨棄 C++14 支援

此版本將捨棄 C++ 14 作為最低支援版本，並將其提升至 17，根據 Foundational C++ Support matrix。

根據我們的政策，我們不認為這是重大變更。

在 Arena 上清除 Oneof 訊息後，引入 ASAN Poisoning

此變更新增了硬化檢查，會影響使用 Arenas 的 C++ protobuf。在 protobuf arena 上配置的 Oneof 訊息現在將在 debug 模式中清除，並在 ASAN 模式中 poisoned。呼叫 clear 後，未來嘗試使用記憶體區域將在 ASAN 中造成當機，並顯示 use-after-free 錯誤。

此實作需要 C++17。

捨棄我們的 C++ CocoaPods 版本

在 v30 中，我們將捨棄自 v4.x.x 以來已損壞的 C++ CocoaPods 版本。C++ 使用者應改為直接使用我們的 GitHub 版本。

JRuby 的變更

v30 將翻轉 JRuby 的預設實作為 FFI，這可能對某些 JRuby 使用者造成重大變更。

請注意，此變更不會建立 Ruby 主要版本提升，因為 JRuby 未正式支援。

Python 的變更

Python 將主要版本從 5.29.x 提升至 6.30.x。

捨棄 Python 3.8 支援

根據我們的官方 Python 支援政策，我們將捨棄對 Python 3.8 及更低版本的支援。這表示最低支援的 Python 版本為 3.9。

移除 bazel/system_python.bzl 別名

v30 將移除舊版 bazel/system_python.bzl 別名。

移除對 system_python.bzl 的直接參考，改為使用 protobuf_deps.bzl。如果您需要直接參考，請使用 在 v5.27.0 中移動的 python/dist/system_python.bzl。

欄位 Setter 驗證變更

Python 和 upb 的欄位 setter 將在 v30 中修復，以驗證 2023 版本下的封閉 enum。以無效值更新的封閉 enum 欄位將產生錯誤。

移除已棄用的 py_proto_library Macro

protobuf.bzl 中已棄用的內部 py_proto_library Bazel 巨集將在 v30.x 中移除。

這應由官方 py_proto_library 取代，該程式庫將在 v29.x 後移至 protobuf 中的 bazel/py_proto_library。此實作先前在 v29.x 之前的 rules_python 中提供。

移除已棄用的 API

v30 將移除以下已標記為棄用至少一個次要或主要版本，且已過時或被取代的公開執行階段 API。

Reflection 方法

API： reflection.ParseMessage、reflection.MakeClass

取代項目： message_factory.GetMessageClass()

RPC 服務介面

API： service.RpcException、service.Service、service.RpcController 和 service.RpcChannel

取代項目： 從 2.3.0 版開始，RPC 實作不應嘗試以此為基礎建構，而應提供程式碼產生器外掛程式，以產生特定於特定 RPC 實作的程式碼。

MessageFactory 和 SymbolDatabase 方法

API： MessageFactory.GetPrototype、MessageFactory.CreatePrototype、MessageFactory.GetMessages、SymbolDatabase.GetPrototype、SymbolDatabase.CreatePrototype 和 SymbolDatabase.GetMessages

取代項目： message_factory.GetMessageClass() 和 message_factory.GetMessageClassesForFiles()。

GetDebugString

API： GetDebugString

取代項目

沒有取代項目。它僅存在於不再發布的 Python C++ 中。純 Python 或 UPB 不支援它。

Python setdefault 對於 Map 欄位的行為變更

從 v30 開始，setdefault 對於 ScalarMap 將與 dict 類似，但必須同時設定鍵和值。setdefault 將拒絕 MessageMaps。

Python 巢狀訊息類別 __qualname__ 包含外部訊息名稱

Python 巢狀訊息類別 __qualname__ 現在包含外部訊息名稱。在 v30 之前，巢狀訊息的 __qualname__ 結果與 __name__ 相同，因為未包含外部訊息名稱。

例如

message Foo {
  message Bar {
    bool bool_field = 1;
  }
}
nested = test_pb2.Foo.Bar()
self.assertEqual('Bar', nested.__class__.__name__)
self.assertEqual('Foo.Bar', nested.__class__.__qualname__) # It was 'Bar' before

Objective-C 的變更

這將是 Objective-C 的第一個重大版本發布.

Objective-C 將主要版本從 3.x.x 提升至 4.30.x。

徹底改革不明欄位處理 API，棄用大多數現有 API

v30 將棄用 GPBUnknownFieldSet，並以 GPBUnknownFields 取代。新的類型將保留來自原始輸入或 API 呼叫的不明欄位的順序，以確保在將訊息寫回時，維護順序的任何語意含義。

作為此變更的一部分，GPBUnknownField 類型也變更了其 API，幾乎所有現有的 API 都已棄用，並新增了新的 API。

已棄用的屬性 API

  • varintList
  • fixed32List
  • fixed64List
  • lengthDelimitedList
  • groupList

已棄用的修改 API

  • addVarint
  • addFixed32
  • addFixed64
  • addLengthDelimited
  • addGroup

已棄用的初始化器 initWithNumber:。

新的屬性 API

  • type
  • varint
  • fixed32
  • fixed64
  • lengthDelimited
  • group

此類型將在其值中對單一欄位編號建模，而不是群組給定欄位編號的所有值。用於建立新欄位的 API 是 GPBUnknownFields 類別上的 add* API。

v30 也將棄用 -[GPBMessage unknownFields]。取而代之的是，將有新的 API 來擷取和更新訊息的不明欄位。

移除已棄用的 API

v30 將移除以下已標記為棄用至少一個次要或主要版本，且已過時或被取代的公開執行階段 API。

GPBFileDescriptor

API： -[GPBFileDescriptor syntax]

取代項目： 已過時。

GPBMessage mergeFrom:extensionRegistry

API： -[GPBMessage mergeFrom:extensionRegistry:]

取代項目： -[GPBMessage mergeFrom:extensionRegistry:error:]

GPBDuration timeIntervalSince1970

API： -[GPBDuration timeIntervalSince1970]

取代項目： -[GPBDuration timeInterval]

GPBTextFormatForUnknownFieldSet

API： GPBTextFormatForUnknownFieldSet()

取代項目： 已過時 - 使用 GPBTextFormatForMessage()，其中包含任何不明欄位。

GPBUnknownFieldSet

API： GPBUnknownFieldSet

取代項目： GPBUnknownFields

GPBMessage unknownFields

API： GPBMessage unknownFields 屬性

取代項目： -[GPBUnknownFields initFromMessage:]、-[GPBMessage mergeUnknownFields:extensionRegistry:error:] 和 -[GPBMessage clearUnknownFields]

移除舊 Gencode 的已棄用執行階段 API

此版本將移除支援 3.22.x 版本之前 Objective-C gencode 的已棄用執行階段方法。當舊版產生的程式碼啟動時，程式庫也會在執行階段發出記錄訊息。

API： +[GPBFileDescriptor allocDescriptorForClass:file:fields:fieldCount:storageSize:flags:]

取代項目： 使用目前版本的程式庫重新產生。

API： +[GPBFileDescriptor allocDescriptorForClass:rootClass:file:fields:fieldCount:storageSize:flags:]

取代項目： 使用目前版本的程式庫重新產生。

API： +[GPBEnumDescriptor allocDescriptorForName:valueNames:values:count:enumVerifier:]

取代項目： 使用目前版本的程式庫重新產生。

API： +[GPBEnumDescriptor allocDescriptorForName:valueNames:values:count:enumVerifier:extraTextFormatInfo:]

取代項目： 使用目前版本的程式庫重新產生。

API： -[GPBExtensionDescriptor initWithExtensionDescription:]

取代項目： 使用目前版本的程式庫重新產生。

其他變更

Poison MSVC + Bazel

我們將在 v34 中捨棄對 Bazel 和 MSVC 一起使用的支援。從 v30 開始，除非您指定 opt-out 旗標 --define=protobuf_allow_msvc=true 以使其靜音，否則我們將使用錯誤 poison 此組合。

MSVC 的路徑長度限制與 Bazel 的沙箱機制結合，使其組合變得越來越難以支援。與其隨機中斷將 protobuf 安裝到長路徑中的使用者，我們將完全禁止從 Bazel 使用 MSVC。我們將繼續支援使用 CMake 的 MSVC，並開始支援使用 Bazel 的 clang-cl。如需任何意見反應或討論，請參閱 https://github.com/protocolbuffers/protobuf/issues/20085。

其他變更 (非破壞性)

除了這些重大變更之外，還有一些其他值得注意的變更。雖然以下變更不被視為重大變更，但仍可能影響使用者。

Poison Pill 警告

v30 將更新 poison pills，針對新的滾動升級政策下可運作，但在下一個主要版本提升中將會中斷的舊 gencode + 新執行階段組合發出警告。例如，Java 4.x.x gencode 應可與 5.x.x 執行階段搭配運作，但會警告即將與 6.x.x 執行階段中斷。

C# 和 Ruby 中 UTF-8 強制執行的變更

v30 將包含修復程式，以使 UTF-8 強制執行在各種語言中保持一致。字串欄位中具有錯誤非 UTF-8 資料的使用者可能會更早看到浮現的 UTF-8 強制執行錯誤。

Ruby 和 PHP 在 JSON 解析中的錯誤

v30 修復了 JSON 解析中數字欄位字串的不一致性，根據 JSON 規格。

此修復程式不會伴隨主要版本提升，但 Ruby 和 PHP 現在會針對數字欄位中的非數字字串 (例如 ""、"12abc"、"abc") 引發錯誤。v29.x 將包含針對這些錯誤案例的警告。