より安全で効率的な Go コードへ： Protocol Buffers Opaque API の導入

より安全で効率的な Go コードへ： Protocol Buffers Opaque API の導入 2025/09/16 layerx.go
#2 shoyan

whoami shoyan LayerX バクラク債務管理エンジニア新卒一年目 ex-42Tokyo 初登壇で非常に緊張しています © LayerX
Inc. 2

Agenda © LayerX Inc. 1: Opaque API とは何か？ Protocol Buffers
の基礎従来の Open Struct API の課題 Opaque API のメリット 2: Opaque API への段階的移行戦略 Hybrid API による安全な移行 open2opaque ツールの活用による移行の半自動化 Build Tags による段階的切り替え 3: まとめ 3

Opaque API とは？

Protocol Buffers (Protobuf) とは？ © LayerX Inc. Google が開発したデータシリアライゼーション形式 .proto
ファイルでスキーマを定義し、各言語のコードを自動生成 LayerX では Connect により gRPC 互換の HTTP API を構築している 5

proto3 までの Protobuf 構造体のフィールドが public になっており、フィールドに直接アクセスできていた本発表では、public で生成しているものを Open Struct
API と呼びます xxx.pb.go (.proto から生成) rpc_xxx.go (xxx.pb.go を呼び出す rpc) © LayerX Inc. 6

Opaque API とは？ edition 2023 から登場した、構造体のフィールドが private で、直接フィールドにアクセスできない API 代わりにアクセサメソッドを使用して操作を行う
Opaque API のメリット © LayerX Inc. 最適化によるフィールドのメモリ表現の影響を受けない Lazy Decoding により不必要なフィールドのデコードを回避しパフォーマンスを向上フィールド有無をポインタからビットフィールドで表現することで省メモリにポインタによる誤った操作を削減できる 7

最適化によるフィールドのメモリ表現の影響を受けない Protobuf からコードを生成する際に、本番の動作状況(PGO)から使用が稀なフィールドを別の構造体へ移動 xxx.pb.go (最適化前) rpc_xxx.go © LayerX Inc. 8

最適化によるフィールドのメモリ表現の影響を受けない Protobuf からコードを生成する際に、本番の動作状況(PGO)から使用が稀なフィールドを別の構造体へ移動 xxx.pb.go (最適化後) rpc_xxx.go © LayerX Inc. 9

Opaque API への段階的移行

一度に Opaque API に移行するのは危険 → Hybrid API を用いた Opaque API
への段階的移行を推奨 open2opaque コマンドにより、移行を半自動化 © LayerX Inc. 大規模プロジェクトでは、数百以上の.proto ファイルが存在する変更箇所のレビュー変更箇所の品質保証 .proto ファイルは複数のマイクロサービス間で共有されることがあるチーム間で同時に移行を進めるのは難しい互換性が必要 11

Opaque API の段階的移行手順 © LayerX Inc. 1: open2opaque setup
で Hybrid API を有効にする 2: open2opaque rewrite で既存のコードを Builder パターンに書き換え 3: open2opaque setup で Opaque API を有効にする 12

1. Hybrid API を有効にする実行コマンド: $ open2opaque setapi -api HYBRID
./... proto ファイルに Hybrid API に切り替えるオプションが追加される © LayerX Inc. 14

1. Hybrid API に切り替える (生成ファイルの差分) Open Struct API の xxx.pb.go
と Opaque API の xxx_protoopaque.pb.go が生成される xxx.pb.go xxx_protoopaque.pb.go © LayerX Inc. struct のフィールド: Public Build Tags: //go:build !protoopaque struct のフィールド: Private Build Tags: //go:build protoopaque 15

1. Hybrid API に切り替える (共通で追加されるもの) 構造体 XXX_builder で、フィールドが public か
private かを隠蔽 → 段階的移行が可能 © LayerX Inc. Setter Method Builder Pattern を実現するための構造体 XXX_builder 19

2. open2opaque rewrite で既存のコードを Builder パターンに書き換え実行コマンド: $ open2opaque rewrite
./... 構造体 XXX が Step1 で生成された Builder Pattern の構造体 XXX_builder に書き換えられる Build method 経由で構造体 XXX が作成されるように変換されます実行前実行後 © LayerX Inc. 21

Build Tags によってコンパイル対象の切り替え Open Struct API ( xxx.pb.go ) で
build する場合 (本番環境) go build ./... Opaque API ( xxx_protoopaque.pb.go ) で build する場合 (Opaque API 移行のテスト環境) go build -tags=protoopaque ./... © LayerX Inc. 22

3. open2opaque setup で Opaque API を有効にする実行コマンド: open2opaque setapi
-api OPAQUE ./... Open struct API で実装されてた xxx.pb.go が、 Opaque API ( xxx_protoopaque.pb.go ) に書き換わる Opaque API への移行完了！ © LayerX Inc. 24

まとめ

Opaque API とは Opaque API の段階的移行 © LayerX Inc. 構造体のフィールドを
private にして、アクセサメソッド経由でのみ操作メモリ最適化・Lazy Decoding によるパフォーマンス向上ポインタによる誤った操作を防ぎ、安全性を向上 Hybrid API により Open Struct/Opaque API 両方のコードを生成 open2opaque で Opaque API への移行を半自動化 Build Tags により部分的に移行後の品質を検証 26

より安全で効率的な Go コードへ： Protocol Buffers Opaque API の導入

より安全で効率的な Go コードへ： Protocol Buffers Opaque API の導入

shoyan

Other Decks in Programming

Featured

Transcript