Migrationsleitfaden

Eine Liste der Änderungen, die Breaking Changes für Versionen der Bibliotheken darstellen, und wie Sie Ihren Code anpassen, um diese Änderungen zu berücksichtigen.

Änderungen in v30.0

Die folgende Liste enthält die Änderungen, die Breaking Changes für Versionen der Bibliotheken darstellen, und wie Sie Ihren Code anpassen, um diese Änderungen zu berücksichtigen.

Dies umfasst Breaking Changes, die in den Nachrichtenankündigungen für v30.x und Versionshinweisen für v30.0 angekündigt wurden.

CMake-Submodule durch abgerufene Abhängigkeiten ersetzt

Zuvor war unser Standard-CMake-Verhalten die Verwendung von Git-Submodulen, um angepinnte Abhängigkeiten abzurufen. Die Angabe von -Dprotobuf_ABSL_PROVIDER=package würde unsere CMake-Konfigurationen umschalten, um nach lokalen Installationen von Abseil (mit ähnlichen Optionen für jsoncpp und gtest) zu suchen. Diese Optionen existieren nicht mehr, und das Standardverhalten ist, zuerst nach Installationen aller unserer Abhängigkeiten zu suchen und bei Bedarf auf das Herunterladen von angepinnten Versionen von GitHub zurückzugreifen.

Um das Zurückfallen auf das Herunterladen zu verhindern (ähnlich dem alten package-Verhalten), können Sie CMake aufrufen mit

cmake . -Dprotobuf_LOCAL_DEPENDENCIES_ONLY=ON

Um Abhängigkeiten immer von einer festen Version herunterzuladen (ähnlich dem alten Standardverhalten), können Sie CMake aufrufen mit

cmake . -Dprotobuf_FORCE_FETCH_DEPENDENCIES=ON

Rückgabetyp string_view

Rückgabetypen sind jetzt absl::string_view für die folgenden Descriptor-APIs, was Speicherplatz spart

MessageLite::GetTypeName
UnknownField::length_delimited
Descriptor-API-Namensfunktionen, wie z. B. FieldDescriptor::full_name

Wir erwarten, dass zukünftige Breaking Releases weitere APIs auf absl::string_view migrieren werden.

In den meisten Fällen sollten Sie versuchen, Typen auf die Verwendung von absl::string_view umzustellen, wo dies sicher ist, oder explizit in den ursprünglichen Typ zu kopieren, wo dies erforderlich ist. Möglicherweise müssen Sie auch Aufrufer aktualisieren, wenn dies in einer Funktion zurückgegeben wird.

Wenn der von den betroffenen API-Methoden zurückgegebene String verwendet wird als

Typ Migration

Typ	Migration
`std::string`	Konvertieren Sie explizit in `std::string`, um das bestehende Verhalten beizubehalten. Oder steigen Sie auf das performantere `absl::string_view` um
`const std::string&`	Migrieren Sie zu `absl::string_view` Wenn nicht möglich (z. B. aufgrund einer großen Anzahl von Abhängigkeiten), kann das Kopieren in eine `std::string` einfacher sein.
`const std::string` `const char`	Wenn nullfähig, migrieren Sie zu `std::optional<absl::string_view>`. Andernfalls migrieren Sie zu `absl::string_view`. Seien Sie vorsichtig beim Aufrufen von `data()`, da `absl::string_view` nicht garantiert nullterminiert ist.

std::string

Konvertieren Sie explizit in std::string, um das bestehende Verhalten beizubehalten.

Oder steigen Sie auf das performantere absl::string_view um

const std::string&

Migrieren Sie zu absl::string_view

Wenn nicht möglich (z. B. aufgrund einer großen Anzahl von Abhängigkeiten), kann das Kopieren in eine std::string einfacher sein.

const std::string*

const char*

Wenn nullfähig, migrieren Sie zu std::optional<absl::string_view>.

Andernfalls migrieren Sie zu absl::string_view.

Seien Sie vorsichtig beim Aufrufen von data(), da absl::string_view nicht garantiert nullterminiert ist.

Für gängige Container und andere APIs können Sie möglicherweise auf Varianten umstellen, die mit absl::string_view kompatibel sind. Nachfolgend finden Sie einige gängige Beispiele.

Kategorie Vor der Migration Migration

Kategorie	Vor der Migration	Migration
Einfügen in `std::vector<std::string>`	`push_back()` `push_front()` `push()`	`emplace_back()` `emplace_front()` `emplace()`
Einfügen für Maps oder Sets	`set.insert(key)` `map.insert({key, value})` `map.insert({key, {value_params...}})`	`set.emplace(key)` `map.emplace(key, value)` `map.try_emplace(key, value_params...)`
Suche für Maps oder Sets	`find()` `count()` `contains()`	Migrieren Sie zu Abseil-Containern. Oder definieren Sie einen transparenten Komparator. `std::set<std::string, std::less<>> std::map<std::string, T, std::less<>>` Siehe https://abseil.io/tips/144
String-Verkettung	`operator+` `operator+=`	`absl::StrCat()` `absl::StrAppend()` Diese werden ohnehin aus Leistungsgründen empfohlen. Siehe https://abseil.io/tips/3.

Einfügen in std::vector<std::string>

push_back()

push_front()

push()

emplace_back()

emplace_front()

emplace()

Einfügen für Maps oder Sets

set.insert(key)

map.insert({key, value})

map.insert({key, {value_params...}})

set.emplace(key)

map.emplace(key, value)

map.try_emplace(key, value_params...)

Suche für Maps oder Sets

find()

count()

contains()

Migrieren Sie zu Abseil-Containern.

Oder definieren Sie einen transparenten Komparator.

std::set<std::string, std::less<>> std::map<std::string, T, std::less<>>

Siehe https://abseil.io/tips/144

String-Verkettung

operator+

operator+=

absl::StrCat()

absl::StrAppend()

Diese werden ohnehin aus Leistungsgründen empfohlen. Siehe https://abseil.io/tips/3.

Siehe auch https://abseil.io/tips/1 für allgemeine Tipps zur Verwendung von absl::string_view.

Poison MSVC + Bazel

Bazel-Benutzer unter Windows sollten zu clang-cl wechseln, indem sie Folgendes zu ihrem Projekt hinzufügen, wie in diesem Beispiel.

.bazelrc

common --enable_platform_specific_config build:windows
--extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl
--extra_execution_platforms=//:x64_windows-clang-cl

MODULE.bazel

bazel_dep(name = "platforms", version = "0.0.10")
bazel_dep(name = "rules_cc", version = "0.0.17")

# For clang-cl configuration
cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension")
use_repo(cc_configure, "local_config_cc")

WORKSPACE

load("//:protobuf_deps.bzl", "PROTOBUF_MAVEN_ARTIFACTS", "protobuf_deps")

protobuf_deps()

load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains")

rules_cc_dependencies()

rules_cc_toolchains()

BUILD

Für Benutzer, die nur Kompatibilität mit Bazel 8 benötigen.

platform(
    name = "x64_windows-clang-cl",
    constraint_values = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
        "@bazel_tools//tools/cpp:clang-cl",
    ],
)

Für Benutzer, die Kompatibilität mit Bazel 7 und 8 benötigen.

platform(
    name = "x64_windows-clang-cl",
    constraint_values = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
        # See https://github.com/bazelbuild/rules_cc/issues/330.
        "@rules_cc//cc/private/toolchain:clang-cl",
    ],
)

Benutzer können den Fehler auch vorübergehend unterdrücken, indem sie die Opt-out-Flagge --define=protobuf_allow_msvc=true bis zur nächsten Breaking-Version setzen.

Alternativ können Benutzer, die MSVC weiterhin verwenden möchten, zu CMake wechseln. Dies kann mit Visual Studio erfolgen oder durch Angabe eines MSVC-Generators in der CMake-Kommandozeile. Zum Beispiel

cmake -G "Visual Studio 17 2022" -A Win64 .

ctype aus FieldDescriptor-Optionen entfernt

Wir haben die ctype aus FieldDescriptor-Optionen nicht mehr verfügbar gemacht. Sie können stattdessen die API FieldDescriptor::cpp_string_type() verwenden, die in der v28-Version hinzugefügt wurde.

Debug-APIs modifiziert, um sensible Felder zu schwärzen

Die Protobuf C++ Debug-APIs (einschließlich Protobuf AbslStringify, proto2::ShortFormat, proto2::Utf8Format, Message::DebugString, Message::ShortDebugString, Message::Utf8DebugString) wurden geändert, um sensible Felder, die mit debug_redact annotiert sind, zu schwärzen; die Ausgaben dieser APIs enthalten ein pro-Prozess randomisiertes Präfix und sind nicht mehr von Protobuf TextFormat Parsers parsbar. Benutzer sollten das neue geschwärzte Debug-Format für die meisten Fälle übernehmen, die eine menschenlesbare Ausgabe erfordern (z. B. Logging), oder erwägen, auf das binäre Format für Serialisierung und Deserialisierung umzusteigen. Benutzer, die das alte parsable Format benötigen, können TextFormat.printer().printToString(proto) verwenden, dies schwärzt jedoch keine sensiblen Felder und sollte daher mit Vorsicht verwendet werden.

Lesen Sie mehr darüber im Nachrichtenartikel vom 4. Dezember 2024.

Veraltete APIs entfernt

Wir haben die folgenden öffentlichen Runtime-APIs entfernt, die seit mindestens einer Minor- oder Major-Version als veraltet (z. B. ABSL_DEPRECATED) gekennzeichnet waren und die obsolet oder ersetzt sind.

API: Arena::CreateMessage

Ersatz: Arena::Create

API: Arena::GetArena

Ersatz: value->GetArena()

API: RepeatedPtrField::ClearedCount

Ersatz: Migration zu Arenen (Migrationsleitfaden).

API: JsonOptions

Ersatz: JsonPrintOptions

C++14-Unterstützung eingestellt

Diese Version hat C++14 als Mindestunterstützungsversion gestrichen und auf 17 angehoben, gemäß der Foundational C++ Support Matrix.

Benutzer sollten auf C++17 aktualisieren.

ASAN-Poisoning nach dem Löschen von Oneof-Nachrichten auf Arena eingeführt

Diese Änderung fügte eine Härtungsprüfung hinzu, die C++-Protobufs mit Arenen betrifft. Oneof-Nachrichten, die auf der Protobuf-Arena allokiert sind, werden jetzt in Debug-Modus gelöscht und im ASAN-Modus vergiftet. Nach dem Aufruf von clear führen zukünftige Versuche, den Speicherbereich zu verwenden, zu einem Absturz in ASAN als Use-after-free-Fehler.

Diese Implementierung erfordert C++17.

Unsere C++ CocoaPods-Veröffentlichung eingestellt

Wir haben unsere C++ CocoaPods-Veröffentlichung eingestellt, die seit v4.x.x fehlerhaft war. C++-Benutzer sollten stattdessen direkt unsere GitHub-Veröffentlichung verwenden.

Änderungen in Python

Python hat seine Hauptversion von 5.29.x auf 6.30.x hochgestuft.

Unterstützung für Python 3.8 eingestellt

Die minimale unterstützte Python-Version ist 3.9. Benutzer sollten aktualisieren.

Alias bazel/system_python.bzl entfernt

Wir haben den alten Alias bazel/system_python.bzl entfernt.

Entfernen Sie direkte Verweise auf system_python.bzl zugunsten der Verwendung von protobuf_deps.bzl. Verwenden Sie python/dist/system_python.bzl, wohin es in v5.27.0 verschoben wurde, wenn Sie einen direkten Verweis benötigen.

Änderungen bei der Validierung von Feldsettern

Die Feldsetter von Python und upb validieren nun geschlossene Enums unter Edition 2023. Aktualisierte geschlossene Enum-Felder mit ungültigen Werten generieren Fehler.

Veraltetes Makro py_proto_library entfernt

Das veraltete interne py_proto_library Bazel-Makro in protobuf.bzl wurde entfernt. Es wurde durch das offizielle py_proto_library ersetzt, das in v29.x nach protobuf in bazel/py_proto_library verschoben wurde. Diese Implementierung war vor v29.x in rules_python verfügbar.

Veraltete APIs entfernt

Wir haben die folgenden öffentlichen Runtime-APIs entfernt, die seit mindestens einer Minor- oder Major-Version als veraltet gekennzeichnet waren.

Reflection-Methoden

APIs: reflection.ParseMessage, reflection.MakeClass

Ersatz: message_factory.GetMessageClass()

RPC-Dienstschnittstellen

APIs: service.RpcException, service.Service, service.RpcController und service.RpcChannel

Ersatz: Ab Version 2.3.0 sollten RPC-Implementierungen nicht versuchen, darauf aufzubauen, sondern stattdessen Code-Generator-Plugins bereitstellen, die Code für die jeweilige RPC-Implementierung generieren.

MessageFactory- und SymbolDatabase-Methoden

APIs: MessageFactory.GetPrototype, MessageFactory.CreatePrototype, MessageFactory.GetMessages, SymbolDatabase.GetPrototype, SymbolDatabase.CreatePrototype und SymbolDatabase.GetMessages

Ersatz: message_factory.GetMessageClass() und message_factory.GetMessageClassesForFiles().

GetDebugString

APIs: GetDebugString

Ersatz

Kein Ersatz. Nur in Python C++, das nicht mehr veröffentlicht wird. Es wird in reinem Python oder UPB nicht unterstützt.

Änderung des setdefault-Verhaltens in Python für Map-Felder

setdefault ähnelt dict für ScalarMap, mit der Ausnahme, dass sowohl Schlüssel als auch Wert gesetzt werden müssen. setdefault wird für MessageMaps abgelehnt.

Python verschachtelte Nachrichtenklasse qualname enthält den Namen der äußeren Nachricht

Die Python-verschachtelte Nachrichtenklasse __qualname__ enthält nun den Namen der äußeren Nachricht. Zuvor hatte __qualname__ dasselbe Ergebnis wie __name__ für verschachtelte Nachrichten, da der Name der äußeren Nachricht nicht enthalten war.

Zum Beispiel

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

Änderungen in Objective-C

Dies ist die erste Breaking-Version für Objective-C.

Objective-C hat seine Hauptversion von 3.x.x auf 4.30.x hochgestuft.

Überarbeitete Unknown Field Handling APIs, die die meisten bestehenden APIs veralten lassen

Wir haben GPBUnknownFieldSet veraltet und durch GPBUnknownFields ersetzt. Der neue Typ bewahrt die Reihenfolge der unbekannten Felder aus der ursprünglichen Eingabe oder den API-Aufrufen, um sicherzustellen, dass die semantische Bedeutung der Reihenfolge erhalten bleibt, wenn eine Nachricht wieder ausgegeben wird.

Als Teil dessen hat der Typ GPBUnknownField ebenfalls API-Änderungen erfahren, wobei fast alle bestehenden APIs veraltet und neue hinzugefügt wurden.

Veraltete Property-APIs

varintList
fixed32List
fixed64List
lengthDelimitedList
groupList

Veraltete Modifizierungs-APIs

addVarint
addFixed32
addFixed64
addLengthDelimited
addGroup

Veralteter Initialisierer initWithNumber:.

Neue Property-APIs

type
varint
fixed32
fixed64
lengthDelimited
group

Dieser Typ modelliert eine einzelne Feldnummer in ihrem Wert, anstatt alle Werte für eine gegebene Feldnummer zu gruppieren. Die APIs zum Erstellen neuer Felder sind die add* APIs der Klasse GPBUnknownFields.

Wir haben auch -[GPBMessage unknownFields] veraltet. An seiner Stelle gibt es neue APIs zum Extrahieren und Aktualisieren der unbekannten Felder der Nachricht.

Veraltete APIs entfernt

Wir haben die folgenden öffentlichen Runtime-APIs entfernt, die seit mindestens einer Minor- oder Major-Version als veraltet gekennzeichnet waren.

GPBFileDescriptor

API: -[GPBFileDescriptor syntax]

Ersatz: Obsolet.

Ersatz: Obsolet - Verwenden Sie GPBTextFormatForMessage(), das alle unbekannten Felder enthält.

GPBUnknownFieldSet

API: GPBUnknownFieldSet

Ersatz: GPBUnknownFields

GPBMessage unknownFields

API: GPBMessage unknownFields Property

Ersatz: -[GPBUnknownFields initFromMessage:], -[GPBMessage mergeUnknownFields:extensionRegistry:error:] und -[GPBMessage clearUnknownFields]

Veraltete Runtime-APIs für alten Gencode entfernt

Diese Version hat veraltete Runtime-Methoden entfernt, die den Objective-C-Gencode vor der Version 3.22.x unterstützten. Die Bibliothek gibt auch eine Protokollnachricht zur Laufzeit aus, wenn alter generierter Code gestartet wird.

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