より安全で効率的な 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 

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

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 に切り替える (共通で追加されるもの) © LayerX Inc. Setter Method Builder Pattern を実現するための 構造体 XXX_builder 16 

1. Hybrid API に切り替える (共通で追加されるもの) © LayerX Inc. Setter Method Builder Pattern を実現するための 構造体 XXX_builder 17 

1. Hybrid API に切り替える (共通で追加されるもの) © LayerX Inc. Setter Method Builder Pattern を実現するための 構造体 XXX_builder 18 

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

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

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 

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

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