Kafka×Protobuf スキーマ設計: フィールド番号と互換性の実務指針

KafkaでProtobufを採用する最大の理由は、軽量なワイヤ形式と強い型付け、そしてスキーマ進化のしやすさにあります。ただし、その前提は「フィールド番号」を正しく扱うことです。

本稿では、Confluent Schema Registry を利用した一般的な実装を前提に、CCDAKの出題範囲に沿って、フィールド番号と互換性の安全運用を具体例で解説します。

KafkaでProtobufを使う理由とワイヤ形式の前提

ConfluentのProtobufシリアライザは、メッセージペイロードにマジックバイトとスキーマIDを付加し、Schema Registry と連携してスキーマ進化を安全にします。コンシューマはスキーマIDからスキーマを取得し、バイト列を解釈します。

Protobufはワイヤ上でフィールド番号を用います。番号が意味を持つため、番号の再利用や付け替えは後方互換性を破壊します。スキーマの見た目（フィールド名）よりも、実体（番号と型）が重要だと理解してください。

• Schema Registry による互換性チェックを活用することで、本番前に破壊的変更を検知可能
• Protobufの未認識フィールドは旧クライアント側で無視されるため、適切に設計すれば追加は安全に行える
• ワイヤ形式は軽量。頻出フィールドは番号を小さくするとエンコード効率がよい

Kafka × Protobuf × Schema Registry の関係

フィールド番号の設計原則

Protobufのフィールド番号は1〜536870911の範囲で、19000〜19999は内部予約のため使用不可です。番号はワイヤ互換性の核心であり、いったん公開したら変更しない・再利用しないが鉄則です。

番号にはエンコード上のコスト差があります。1〜15はタグが短く、頻出・必須に近いフィールドに割り当てると効率的です。将来の拡張を見越し、論理ブロックやチームごとに番号帯を計画的に確保しておくと運用が安定します。

• 一度リリースした番号は再利用しない（削除時は reserved に入れる）
• 高頻度アクセスのフィールドは番号1〜15を優先
• 将来拡張用に未使用番号をあらかじめ確保（例: 100–199は拡張用）
• 19000–19999は使用しない（Protobuf予約）
• 型の変更やoneofへの移動は別番号の新フィールドで表現し、古い番号は非推奨→予約へ

.proto 例: 予約と追加のパターン

syntax = "proto3";
package com.example;

message OrderV1 {
  // 頻出フィールドは小さい番号
  int64 order_id = 1;
  string customer_id = 2;
  // 将来の状態コード
  int32 status_code = 10;
}

// 進化後
message OrderV2 {
  int64 order_id = 1;
  string customer_id = 2;
  // status_code を enum に置き換えたい → 新番号で追加
  // 旧 10 は非推奨 → 予約して再利用禁止
  reserved 10; // 旧: status_code
  // 名前も予約できる
  reserved "status_code";

  // 新しい enum ベースの状態。旧クライアントは未認識として無視
  OrderStatus status = 20;

  // フィールド削除時は [deprecated = true] → 後で reserved へ
  string note = 30 [deprecated = true];
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0; // 0 はデフォルト
  ORDER_STATUS_PLACED = 1;
  ORDER_STATUS_SHIPPED = 2;
  ORDER_STATUS_CANCELLED = 3;
}

互換性モードと安全な進化パターン

Schema Registry の互換性モードは主に Backward / Forward / Full の3種類。Protobufでは「新フィールド追加（新番号）」は多くのケースで後方互換的です。旧コンシューマは未認識フィールドを無視するため、既存の読み取りは成立します。

破壊的なのは、番号変更・再利用、型変更、oneof への移動、enum 番号変更などです。見た目の名称変更はワイヤ上は成立しても、コード生成や検証で破綻しやすく、実務上は破壊的とみなすのが安全です。

• 追加は新番号で。既存番号はそのまま維持
• 削除は段階的に: 非推奨 → 参照停止 → reserved
• 型を変えたい場合は新番号・新フィールドで併存期間を作る
• enum は値の追加は可、番号の変更は不可

削除・再利用・リネームの運用手順

削除や置換は段階的に進めます。いきなりフィールドを消すと旧アプリのコンパイルが通らず、あるいは互換性検証で落ちます。非推奨フラグ→利用停止→予約の順が安全です。

番号と名前の両方を reserved に入れることで、将来の誤再利用を防げます。スキーマ履歴を Schema Registry と一緒に運用し、PRレビューチェックに互換性検証を組み込むと事故が減ります。

• Step1: 対象フィールドに deprecated を付与し、利用停止の告知
• Step2: プロデューサが新フィールドへ完全移行するまで待機（並走期間）
• Step3: 古いフィールドを .proto から削除し、番号・名前を reserved に登録
• Step4: Schema Registry 上で互換性を Full（または組織標準）に固定し、破壊的変更をブロック

.proto で削除時に行う定型

message CustomerV2 {
  int64 id = 1;
  string email = 2;
  // 旧 phone は利用停止済み → 削除して予約
  reserved 5;           // 番号の再利用禁止
  reserved "phone";     // 名前の再利用禁止
}

oneof・map・enum の互換性の落とし穴

oneof にフィールドを追加すると、旧クライアントはその分岐を未認識として扱い、期待する意味論を満たせない可能性があります。Schema Registry の検証を通っても、アプリ互換性としては破壊的になりがちです。

map は内部的に繰り返しメッセージへ変換されます。キー・値の型変更は破壊的。enum は値の追加は安全ですが、値番号の変更や再割当ては破壊的です。名称変更はワイヤ上は許容でも、生成コードや読みやすさの観点から原則避けます。

• oneof: 既存フィールドの oneof への移動は避ける（破壊的）
• map: キー型の変更は不可。値型変更も不可。必要なら新フィールドで置換
• enum: 値の追加は可、番号変更・再利用は不可。削除時は番号を reserved 相当として再利用禁止
• 名称変更は最終手段。ワイヤ互換でもツールチェーン互換を壊すことがある

運用設定とCCDAK観点の確認ポイント

Subject Naming Strategy は再利用戦略に直結します。TopicNameStrategy（デフォルト、<topic>-value）、RecordNameStrategy（メッセージ型単位で共有）、TopicRecordNameStrategy（トピック×型）を要件に応じて選択します。

Protobufシリアライザ/デシリアライザはそれぞれ io.confluent.kafka.serializers.protobuf.KafkaProtobufSerializer / KafkaProtobufDeserializer を使用します。生成クラスを返したい場合は specific.protobuf.value.type を設定します。

互換性レベルはグローバルやサブジェクト単位で設定可能です。開発環境は Backward、プロダクションは Full を基本とし、破壊的変更をブロックする運用が無難です。

• CCDAKチェック: 互換性モードの意味、許容/非許容変更例を即答できること
• Subject Naming Strategy をケースで選べること（スキーマ再利用 vs 分離）
• Producer/Consumer の Protobuf SerDe 設定と Schema Registry 連携を説明できること

Schema Registry とクライアント設定の例

# Producer/Consumer プロパティ（抜粋）
key.serializer=org.apache.kafka.common.serialization.StringSerializer
value.serializer=io.confluent.kafka.serializers.protobuf.KafkaProtobufSerializer
schema.registry.url=http://localhost:8081
# 型を返したい場合（例）
specific.protobuf.value.type=com.example.OrderV2
# Subject Naming Strategy を変更したい場合（例）
value.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy

# 互換性モード設定（サブジェクト単位）
# Backward/Forward/Full などを指定
curl -X PUT -H "Content-Type: application/json" \
  --data '{"compatibility": "FULL"}' \
  http://localhost:8081/config/my-orders-value

問題で確認

よくある質問