移行ガイド

ライブラリのバージョンに加えられた破壊的変更と、それらの変更に対応するためにコードを更新する方法のリスト。

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`	null 許容の場合は、`std::optional` に移行します。それ以外の場合は、`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*

null 許容の場合は、`std::optional` に移行します。

それ以外の場合は、`absl::string_view` に移行します。

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

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

カテゴリ移行前移行

カテゴリ	移行前	移行
`std::vector` への挿入	`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::map>` https://abseil.io/tips/144 を参照してください。
文字列結合	`operator+` `operator+=`	`absl::StrCat()` `absl::StrAppend()` これらはパフォーマンス上の理由から推奨されています。https://abseil.io/tips/3 を参照してください。

`std::vector` への挿入

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::map>

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 アリーナに割り当てられた Oneof メッセージは、デバッグモードではクリアされ、ASAN モードではポイズンされます。クリア後、将来そのメモリ領域を使用しようとすると、ASAN で use-after-free エラーとしてクラッシュが発生します。

この実装には 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 のフィールドセッターは、Edition 2023 に基づいてクローズド enum を検証するようになりました。無効な値で更新されたクローズド enum フィールドはエラーを生成します。

非推奨の py_proto_library マクロを削除しました

`protobuf.bzl` にあった非推奨の内部 `py_proto_library` Bazel マクロが削除されました。これは、v29.x で `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:]