CCDAK対策: Schema Registry の Subjects 命名戦略を正しく選ぶ — TopicNameStrategy と RecordNameStrategy の比較

CCDAKで頻出のSchema Registryの要点は、スキーマ自体よりも「どのSubjectで互換性を縛るか」です。Subjectの付け方は命名戦略に依存し、スキーマ進化の自由度や再利用性、運用のしやすさを大きく左右します。

本稿では代表的な3戦略（TopicNameStrategy、RecordNameStrategy、TopicRecordNameStrategy）を比較し、実務シナリオ別の選択指針と設定例を示します。公式ドキュメントの挙動に基づき、試験対策と現場適用の両方を意識して解説します。

前提整理: Subjectと命名戦略の役割

Schema Registryはスキーマを「Subject」単位でバージョン管理し、互換性もSubject単位で評価します。Producerはシリアライズ時にスキーマをSubjectへ登録し、メッセージにはSchema IDだけを埋め込みます。ConsumerはIDでスキーマを取得します。つまり、ワイヤ形式はSubject名を含まないため、Subjectは登録・互換性管理の境界を決めるための概念です。

命名戦略は、このSubject名をどう決めるかのルールです。主な選択肢は以下の3つです。TopicNameStrategy（既定）、RecordNameStrategy、TopicRecordNameStrategy。選択によって互換性の適用範囲（1トピック限定か、複数トピック横断か）が変わります。

• 互換性はSubject単位で評価される（Backward/Forward/Full など）
• デフォルト戦略はTopicNameStrategy（<topic>-key / <topic>-value）
• RecordNameStrategyはレコード完全修飾名でSubjectを共有し、複数トピックで再利用を促進
• Schema IDはレジストリ全体で一意。ConsumerはIDで解決するため、Subjectは互換性管理のための境界

Producer/ConsumerとSubjectの関係

Producer               Schema Registry                 Consumer
    |                          |                            |
    | 1) Serialize(value)      |                            |
    |--> subject resolved -----|                            |
    |    (by strategy)         |                            |
    |                          | 2) Register or lookup      |
    |-------------------------> |    schema under Subject    |
    |                          |    -> returns Schema ID    |
    | 3) Send record (ID+data) |                            |
    |-----------------------------------------------------> |
    |                          | 4) Fetch by Schema ID <----|
    |                          |    (subject not in wire)   |

TopicNameStrategy: トピックごとに互換性を区切る既定戦略

TopicNameStrategyは最も安全で既定の戦略です。Subjectは <topic>-key と <topic>-value に分かれ、互換性評価は各トピックのキー/値ごとに独立します。異なるトピック間で同一スキーマを使っても、互いの進化は干渉しません。

利点は、トピック境界で変更影響を閉じ込められることです。欠点は、同一スキーマを複数トピックで共有する場合でもSubjectが分断され、スキーマの重複登録や互換性基準の分散管理が発生する点です。

• Subject例: orders-value, orders-key
• 変更影響は1トピック内に限定
• 同一スキーマの再利用性は低い（トピックごとに再登録）
• 運用初期や独立開発チームが多い環境で無難

設定例: 値にRecordNameStrategy、キーにTopicNameStrategyを適用する

Properties p = new Properties();
p.put("bootstrap.servers", "localhost:9092");
p.put("key.serializer", "io.confluent.kafka.serializers.KafkaAvroSerializer");
p.put("value.serializer", "io.confluent.kafka.serializers.KafkaAvroSerializer");
p.put("schema.registry.url", "http://localhost:8081");

// 既定はTopicNameStrategyだが、明示も可能
p.put("key.subject.name.strategy", "io.confluent.kafka.serializers.subject.TopicNameStrategy");

// 値だけRecordNameStrategyに切り替える例（混在可）
p.put("value.subject.name.strategy", "io.confluent.kafka.serializers.subject.RecordNameStrategy");

// 本番では自動登録を止め、最新利用へ切り替える選択肢もある
p.put("auto.register.schemas", false);
p.put("use.latest.version", true);

// 確認: 現在のSubject一覧
// curl http://localhost:8081/subjects
// 例: orders-key, orders-value, com.example.OrderCreated などが列挙される

RecordNameStrategy: レコード名で横断的に再利用する

RecordNameStrategyは、Avroの完全修飾名（namespace.name）やProtobuf/JSON Schemaのメッセージ名でSubjectを決定します。結果として、同一のレコードを複数トピックで用いる場合でも、単一のSubjectに集約され、互換性の基準も一箇所にまとまります。

利点は、スキーマ再利用の促進と互換性ポリシーの一元化です。一方、同一の完全修飾名を不注意に別スキーマで使うと衝突し得ます。名前空間の設計と命名規約、キー/値で同一レコード名を使わない配慮が重要です。

• Subject例: com.example.events.OrderCreated
• 複数トピック横断で互換性を統一
• 名前空間設計が甘いと衝突リスク
• イベント・スキーマの共有基盤を重視する組織に適合

TopicRecordNameStrategyと3戦略の比較

TopicRecordNameStrategyは、トピック名と完全修飾レコード名を結合してSubjectを作ります。トピック境界の独立性を保ちながら、同一トピック内で異なるレコード名を区別しやすいのが特長です。マルチイベント型のトピックを採用する場合にバランスが良い選択です。

以下の比較表では、3戦略を観点別に整理します。CCDAKでは「互換性がどの範囲に及ぶか」「いつ再利用が効くか」を問われやすい点を押さえてください。

• Subject例: orders-com.example.events.OrderCreated
• マルチイベント型トピックで管理しやすい
• 再利用性はRecordNameStrategyほど強くないが、衝突リスクは低め

互換性と進化: Subjectが境界になるという事実

互換性レベル（Backward/Forward/Full/Transitiveなど）は、グローバル既定とSubject単位の上書きが可能です。どの戦略を採っても、最終的に「そのSubject」で評価されます。したがってRecordNameStrategyを選ぶと、複数トピックで共有する単一Subjectに対して後方互換を守る責務が重くなります。

auto.register.schemas=false と use.latest.version=true の組み合わせは、本番での事前登録・段階的ロールアウトに役立ちます。Producerが勝手に新スキーマを作らないため、互換性の破壊を未然に防ぎやすくなります。

• 互換性はSubject単位。戦略選択＝境界設計
• 同名レコードの衝突はRecordNameStrategyで顕在化しやすい
• キーと値は別Subject。戦略を分けて設定できる
• 大規模組織では命名規約とレビューをプロセスに組み込む

実務チェックリストと移行の考え方

現状のトピックとイベント一覧を作り、どれが複数トピックで共有されるかを確認します。共有が多いならRecordNameStrategy、トピックごとに独立しているならTopicNameStrategyが自然です。マルチイベント型トピックではTopicRecordNameStrategyも検討します。

移行は新しいProducer設定から開始し、既存メッセージはそのままにします。ワイヤ形式はSchema IDで解決されるため、Consumerは影響を受けません。ただし、移行後は新旧のSubjectが並存します。Registry側の互換性ポリシーとSubject数の増加を監視してください。

• キー/値で別戦略を使う場合、同一レコード名の再利用を避ける
• 名前空間を厳格化（例: com.company.domain.event）
• 本番はauto.register.schemasをオフ、事前登録パイプラインを整備
• 移行中はSubject一覧と互換性違反の監視を強化

問題で確認

よくある質問