移行ガイド

ライブラリのバージョンに加えられた互換性のない変更のリストと、変更に対応するためにコードを更新する方法。

v30.0 での変更点

以下は、ライブラリのバージョンに加えられた互換性のない変更のリストと、変更に対応するためにコードを更新する方法です。

これは、v30.x の新着情報およびv30.0 のリリースノートで発表された互換性のない変更を対象としています。

CMake サブモジュールからフェッチされた依存関係への置き換え

以前は、デフォルトの CMake の動作として Git サブモジュールを使用して固定された依存関係を取得していました。-Dprotobuf_ABSL_PROVIDER=package を指定すると、CMake の設定が Abseil のローカルインストールを検索するように切り替わりました（jsoncpp と gtest にも同様のオプションがあります）。これらのオプションは廃止され、デフォルトの動作は、まずすべての依存関係のインストールを検索し、必要に応じて GitHub から固定バージョンをフェッチするようにフォールバックします。

フォールバックフェッチを防止するには（以前の package の動作と同様）、CMake を次のように呼び出します。

cmake . -Dprotobuf_LOCAL_DEPENDENCIES_ONLY=ON

依存関係を固定バージョンから_常に_フェッチするには（以前のデフォルトの動作と同様）、CMake を次のように呼び出します。

cmake . -Dprotobuf_FORCE_FETCH_DEPENDENCIES=ON

string_view 戻り値の型

以下の記述子 API の戻り値の型が absl::string_view になり、メモリを節約できるようになりました。

MessageLite::GetTypeName
UnknownField::length_delimited
FieldDescriptor::full_name など、記述子 API の名前関数

今後の互換性のないリリースでは、さらに多くの API が absl::string_view に移行される予定です。

ほとんどの場合、安全な場合は型を absl::string_view を使用するように更新するか、必要な場合は明示的に元の型にコピーするようにしてください。この型が関数で返される場合は、呼び出し元も更新する必要がある場合があります。

影響を受ける API メソッドによって返される文字列が次のように使用されている場合

型移行

型	移行
`std::string`	既存の動作を維持するために、明示的に `std::string` に変換します。または、よりパフォーマンスの高い `absl::string_view` に切り替えます。
`const std::string&`	`absl::string_view` に移行します。実行不可能な場合（多数の依存関係のためなど）、`std::string` にコピーする方が簡単かもしれません。
`const std::string` `const char`	ヌル許容の場合は、`std::optional<absl::string_view>` に移行します。そうでない場合は、`absl::string_view` に移行します。 `absl::string_view` は null 終端が保証されていないため、`data()` を呼び出す際には注意してください。

std::string

既存の動作を維持するために、明示的に std::string に変換します。

または、よりパフォーマンスの高い absl::string_view に切り替えます。

const std::string&

absl::string_view に移行します。

実行不可能な場合（多数の依存関係のためなど）、std::string にコピーする方が簡単かもしれません。

const std::string*

const char*

ヌル許容の場合は、std::optional<absl::string_view> に移行します。

そうでない場合は、absl::string_view に移行します。

absl::string_view は null 終端が保証されていないため、data() を呼び出す際には注意してください。

一般的なコンテナやその他の API の場合、absl::string_view と互換性のあるバリアントに移行できる場合があります。以下に一般的な例をいくつか示します。

カテゴリ移行前移行

カテゴリ	移行前	移行
`std::vector<std::string>` への挿入	`push_back()` `push_front()` `push()`	`emplace_back()` `emplace_front()` `emplace()`
マップまたはセットへの挿入	`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...)`
マップまたはセットのルックアップ	`find()` `count()` `contains()`	Abseil コンテナに移行します。または、透過的な比較演算子を定義します。 `std::set<std::string, std::less<>> std::map<std::string, T, std::less<>>` https://abseil.io/tips/144 を参照してください。
文字列連結	`operator+` `operator+=`	`absl::StrCat()` `absl::StrAppend()` これらはパフォーマンス上の理由からいずれにしても推奨されます。https://abseil.io/tips/3 を参照してください。

std::vector<std::string> への挿入

push_back()

push_front()

push()

emplace_back()

emplace_front()

emplace()

マップまたはセットへの挿入

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...)

マップまたはセットのルックアップ

find()

count()

contains()

Abseil コンテナに移行します。

または、透過的な比較演算子を定義します。

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

https://abseil.io/tips/144 を参照してください。

文字列連結

operator+

operator+=

absl::StrCat()

absl::StrAppend()

これらはパフォーマンス上の理由からいずれにしても推奨されます。https://abseil.io/tips/3 を参照してください。

absl::string_view の使用に関する一般的なヒントについては、https://abseil.io/tips/1 も参照してください。

MSVC + Bazel のポイズニング

Windows の Bazel ユーザーは、この例のように、プロジェクトに以下を追加して clang-cl を使用するように切り替える必要があります。

.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

Bazel 8 のみとの互換性が必要なユーザー向け。

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

Bazel 7 および 8 との互換性が必要なユーザー向け。

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",
    ],
)

ユーザーは、次の互換性のないリリースまで、オプトアウトフラグ --define=protobuf_allow_msvc=true を設定することで、一時的にエラーを抑制することもできます。

あるいは、MSVC を使い続けたいユーザーは、CMake に切り替えることもできます。Visual Studio を使用するか、CMake コマンドラインに MSVC ジェネレーターを指定することで実行できます。例：

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

FieldDescriptor オプションから ctype を削除

FieldDescriptor オプションから ctype を公開するのをやめました。代わりに、v28 リリースで追加された FieldDescriptor::cpp_string_type() API を使用できます。

機密フィールドを削除するようにデバッグ API を変更

Protobuf C++ デバッグ API（Protobuf AbslStringify、proto2::ShortFormat、proto2::Utf8Format、Message::DebugString、Message::ShortDebugString、Message::Utf8DebugString を含む）は、debug_redact で注釈付けされた機密フィールドを削除するように変更されました。これらの API の出力にはプロセスごとのランダムなプレフィックスが含まれており、Protobuf TextFormat パーサーによって解析できなくなりました。ユーザーは、人間が読める出力が必要なほとんどの場合（ログ記録など）には新しい削除されたデバッグ形式を採用するか、シリアル化およびデシリアル化にはバイナリ形式に切り替えることを検討する必要があります。古いデシリアル化可能な形式が必要なユーザーは TextFormat.printer().printToString(proto) を使用できますが、これは機密フィールドを削除しないため、注意して使用する必要があります。

この件については、2024 年 12 月 4 日にリリースされたニュース記事で詳しく読むことができます。

非推奨 API の削除

少なくとも 1 つのマイナーまたはメジャーリリースで非推奨（ABSL_DEPRECATED など）とマークされ、廃止または置き換えられた以下の公開ランタイム API を削除しました。

API: Arena::CreateMessage

代替: Arena::Create

API: Arena::GetArena

代替: value->GetArena()

API: RepeatedPtrField::ClearedCount

代替: Arenaに移行してください（移行ガイド）。

API: JsonOptions

代替: JsonPrintOptions

C++14 のサポート終了

このリリースでは、Foundational C++ Support matrix に従って、C++ 14 の最小サポートバージョンを廃止し、C++ 17 に引き上げました。

ユーザーは C++17 にアップグレードする必要があります。

Arena 上の Oneof メッセージをクリアした後の ASAN ポイズニングの導入

この変更により、Arena を使用する C++ Protobuf に影響する強化チェックが追加されました。Protobuf Arena に割り当てられた Oneof メッセージは、デバッグモードではクリアされ、ASAN モードではポイズニングされます。クリアした後、メモリ領域を使用しようとすると、use-after-free エラーとして ASAN でクラッシュが発生します。

この実装には C++17 が必要です。

C++ CocoaPods リリースの終了

v4.x.x 以降機能していなかった C++ CocoaPods リリースは廃止されました。C++ ユーザーは、代わりに当社の GitHub リリースを直接使用する必要があります。

Pythonでの変更

Python のメジャーバージョンが 5.29.x から 6.30.x に上がりました。

Python 3.8 のサポート終了

最小サポート Python バージョンは 3.9 です。ユーザーはアップグレードする必要があります。

bazel/system_python.bzl エイリアスの削除

従来の bazel/system_python.bzl エイリアスを削除しました。

system_python.bzl への直接参照を削除し、代わりに protobuf_deps.bzl を使用してください。直接参照が必要な場合は、v5.27.0 で移動された python/dist/system_python.bzl を使用してください。

フィールドセッターの検証に関する変更

Python と upb のフィールドセッターは、エディション 2023 のクローズド列挙型を検証するようになりました。無効な値で更新されたクローズド列挙型フィールドはエラーを生成します。

非推奨の py_proto_library マクロの削除

protobuf.bzl 内の非推奨の内部 py_proto_library Bazel マクロが削除されました。これは、v29.x で protobuf の bazel/py_proto_library に移動された公式の py_proto_library に置き換えられました。この実装は、v29.x より前は rules_python で利用可能でした。

非推奨APIの削除

少なくとも 1 つのマイナーまたはメジャーリリースで非推奨とマークされていた以下の公開ランタイム API を削除しました。

リフレクションメソッド

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++にのみ存在します。Pure PythonやUPBではサポートされていません。

Python のマップフィールドに対する setdefault の動作変更

setdefault は ScalarMap の dict と似ていますが、キーと値の両方を設定する必要がある点が異なります。MessageMaps の setdefault は拒否されます。

Python のネストされたメッセージクラスの qualname が外側のメッセージ名を含むように

Python ネストされたメッセージクラス __qualname__ は、外側のメッセージ名を含むようになりました。以前は、__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 のほとんどの非推奨化

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 です。

また、-[GPBMessage unknownFields] も非推奨としました。代わりに、メッセージの未知フィールドを抽出および更新するための新しい API があります。

非推奨 API の削除

少なくとも 1 つのマイナーまたはメジャーリリースで非推奨とマークされていた以下の公開ランタイム API を削除しました。

GPBFileDescriptor

API: -[GPBFileDescriptor syntax]

代替: 廃止されました。

代替: 廃止 - 未知フィールドを含む 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:]