스키마와 직렬화

직렬화 형식 비교

Kafka의 Serializer/Deserializer는 무엇이든 될 수 있습니다. 선택 기준은 스키마 진화를 감당할 수 있는가와 페이로드 크기, 그리고 팀이 쓰는 언어 생태계입니다.

Schema Registry 아키텍처

Schema Registry는 스키마를 중앙에 보관하고 정수 ID를 발급하는 HTTP 서비스입니다. 핵심 흐름은 네 단계입니다.

1. 프로듀서가 직렬화 시점에 스키마를 subject 아래로 등록합니다. Registry가 schema id를 돌려줍니다.
2. 프로듀서는 메시지 앞에 그 id를 붙여 Kafka에 씁니다. 스키마 본문은 붙이지 않습니다.
3. 컨슈머는 메시지 앞의 id를 읽어 Registry에 스키마를 조회합니다(그리고 캐시합니다).
4. 조회한 writer 스키마와 컨슈머가 가진 reader 스키마로 역직렬화합니다.

subject · version · schema id

wire format 바이트 레이아웃

직렬화된 메시지의 앞부분은 고정된 구조를 갖습니다. Confluent 직렬화기의 소스에서 확인한 값은 MAGIC_BYTE_V0 = 0x0, ID_SIZE = 4입니다.

바이트  0        1  2  3  4              5 ...
      ┌──────┬──────────────────────┬─────────────────────────┐
      │ 0x00 │  schema id (4 bytes) │  직렬화된 payload        │
      └──────┴──────────────────────┴─────────────────────────┘
        │         │                      │
        │         │                      └─ Avro binary / Protobuf wire / JSON 본문
        │         └─ 부호 있는 32비트 정수, big-endian (ByteBuffer.putInt 기본)
        └─ magic byte. 0x00 = "4바이트 schema id 형식"

예시 (schema id = 42, Avro payload 가 이어짐)
      00 00 00 00 2A  
      ^^  ^^^^^^^^^^^
     magic  42

Protobuf 는 schema id 뒤에 message index 배열이 추가됩니다
(한 .proto 파일 안의 여러 message 중 어느 것인지 지시).

subject naming strategy 3종

subject 이름을 어떻게 만들지가 호환성 검사의 단위를 결정합니다. Confluent 직렬화기 소스에서 확인한 세 전략의 산출 규칙입니다.

value.subject.name.strategy=io.confluent.kafka.serializers.subject.TopicRecordNameStrategy
key.subject.name.strategy=io.confluent.kafka.serializers.subject.TopicNameStrategy

호환성 모드 7종 — 무엇을 어느 방향으로 비교하는가

모드가 하는 일은 두 개의 축으로 완전히 결정됩니다. ① 검사 방향(누가 reader이고 누가 writer인지)과 ② 비교 범위(직전 버전만인지 모든 버전인지)입니다. Confluent Schema Registry의 CompatibilityChecker 소스가 이를 명시적으로 정의합니다.

Avro 스키마 해석 규칙 — 매트릭스의 근거

허용/거부는 임의로 정해진 것이 아닙니다. Confluent의 AvroSchema.isBackwardCompatible()은 Avro의 SchemaCompatibility.checkReaderWriterCompatibility(reader, writer)를 직접 호출합니다. 따라서 매트릭스의 모든 칸은 Avro의 해석 규칙에서 유도됩니다.

호환성 매트릭스 — 이 장의 핵심 산출물

위의 두 표를 결합하면 매트릭스가 계산됩니다. 각 칸의 판정 방법은 항상 같습니다 — BACKWARD는 reader=새 스키마, FORWARD는 reader=옛 스키마로 두고 Avro 해석 규칙을 적용합니다.

*_TRANSITIVE 모드는 위 표의 판정을 직전 버전 대신 모든 이전 버전에 대해 반복합니다. 한 버전이라도 거부되면 전체가 거부됩니다. 즉 비-TRANSITIVE에서 ✕인 것은 TRANSITIVE에서도 ✕이고, 비-TRANSITIVE에서 ✓라도 TRANSITIVE에서는 ✕일 수 있습니다.

배포 순서 — 매트릭스에서 곧바로 나옵니다

이것은 암기 사항이 아니라 모드의 정의에서 논리적으로 따라 나오는 결론입니다. 각 모드가 무엇을 보장하는지 다시 보면 순서가 자동으로 정해집니다.

BACKWARD면 왜 컨슈머 먼저인가

BACKWARD가 보장하는 것은 "새 스키마가 옛 스키마로 생산된 데이터를 읽을 수 있다"입니다. 보장되지 않는 것은 그 반대 — 옛 스키마가 새 데이터를 읽는 것입니다.

따라서 새 코드는 옛 데이터를 안전하게 읽을 수 있고, 옛 코드는 새 데이터를 못 읽습니다. 새 스키마의 데이터가 토픽에 나타나기 전에 컨슈머를 모두 새 버전으로 올려야 합니다. 컨슈머를 먼저 배포하면, 전환 기간 동안 새 컨슈머가 옛 데이터를 읽습니다 — 이것이 BACKWARD가 보장하는 방향입니다.

순서를 뒤바꿔 프로듀서를 먼저 배포하면, 아직 옛 스키마를 쓰는 컨슈머가 새 스키마의 데이터를 만나 역직렬화에 실패합니다. 예를 들어 v2에서 default 있는 필드를 추가했다면(BACKWARD ✓, FORWARD도 ✓라 안전하지만), v2에서 default 없는 필드를 추가한 경우 BACKWARD에서는 애초에 거부되고, 필드를 삭제한 경우(BACKWARD ✓, FORWARD ✕) 옛 컨슈머는 자신이 요구하는 필드를 새 데이터에서 찾지 못해 실패합니다.

FORWARD면 왜 프로듀서 먼저인가

FORWARD가 보장하는 것은 "새 스키마로 생산된 데이터를 옛 스키마가 읽을 수 있다"입니다. 즉 옛 컨슈머가 새 데이터를 안전하게 읽습니다.

그래서 프로듀서를 먼저 올려도 됩니다. 컨슈머는 아직 옛 버전이지만 새 데이터를 문제없이 처리합니다. 컨슈머는 여유를 두고 나중에 전환합니다.

순서를 뒤바꿔 컨슈머를 먼저 배포하면, 새 컨슈머가 아직 옛 스키마로 생산되는 데이터를 읽어야 합니다. 그런데 FORWARD는 그 방향(새 reader ← 옛 writer)을 보장하지 않습니다. v2에서 default 없는 필드를 추가한 경우(FORWARD ✓, BACKWARD ✕), 새 컨슈머는 옛 데이터에서 그 필드를 찾지 못하고 default도 없어 실패합니다.

안전한 스키마 진화 규칙

매트릭스에서 실무 규칙을 추출하면 다음과 같습니다. Registry 기본값이 BACKWARD이므로 그 기준으로 정리합니다.

// v1
{
  "type": "record",
  "namespace": "com.example",
  "name": "OrderCreated",
  "fields": [
    { "name": "orderId",  "type": "string" },
    { "name": "amount",   "type": "int" },
    { "name": "status",   "type": { "type": "enum", "name": "Status",
                                    "symbols": ["NEW", "PAID"],
                                    "default": "NEW" } }
  ]
}

{
  "type": "record",
  "namespace": "com.example",
  "name": "OrderCreated",
  "fields": [
    { "name": "orderId",  "type": "string" },

    // ✓ 타입 승격 int → long : reader(v2) long ← writer(v1) int 허용 → BACKWARD OK
    //   (FORWARD 로는 거부됩니다 — 모드가 BACKWARD 임을 전제합니다)
    { "name": "amount",   "type": "long" },

    // ✓ enum 심볼 추가 : reader(v2) 심볼 집합이 writer(v1) 를 포함 → BACKWARD OK
    //   default 심볼이 있으므로 FORWARD 도 완화됩니다
    { "name": "status",   "type": { "type": "enum", "name": "Status",
                                    "symbols": ["NEW", "PAID", "REFUNDED"],
                                    "default": "NEW" } },

    // ✓ default 있는 필드 추가 : 모든 모드에서 통과
    { "name": "currency", "type": "string", "default": "KRW" },

    // ✓ nullable + default null : 나중에 제거할 때도 안전합니다
    { "name": "couponId", "type": ["null", "string"], "default": null }
  ]
}

{
  "type": "record",
  "namespace": "com.example",
  "name": "OrderCreated",
  "fields": [
    // ✕ 이름 변경 (orderId → order_id, alias 없음)
    //   → BACKWARD: reader(v2) 의 order_id 가 writer(v1) 에 없고 default 없음 → 거부
    { "name": "order_id", "type": "string" },

    // ✕ default 없는 필드 추가 → BACKWARD 거부
    //   READER_FIELD_MISSING_DEFAULT_VALUE
    { "name": "channel",  "type": "string" },

    // ✕ 타입 축소 int → 유지했더라도, long → int 였다면 BACKWARD 거부
    //   TYPE_MISMATCH (reader int ← writer long 은 승격 경로가 아님)
    { "name": "amount",   "type": "int" }
  ]
}

{
  "name": "order_id",
  "type": "string",
  // alias 는 reader 쪽에서만 해석됩니다.
  // reader(v2) 가 writer(v1) 의 orderId 필드를 이 alias 로 찾아냅니다 → BACKWARD OK.
  // 반대로 FORWARD 는 reader 가 v1 이고 v1 에는 alias 가 없으므로 거부됩니다.
  "aliases": ["orderId"]
}

직렬화기 설정과 REST API

KafkaAvroSerializer 설정

bootstrap.servers=kafka-1:9092,kafka-2:9092,kafka-3:9092
key.serializer=org.apache.kafka.common.serialization.StringSerializer
value.serializer=io.confluent.kafka.serializers.KafkaAvroSerializer

schema.registry.url=http://schema-registry-1:8081,http://schema-registry-2:8081

# 스키마 등록은 CI/CD 에서만. 애플리케이션은 등록하지 않습니다.
auto.register.schemas=false
# 이미 등록된 최신 버전을 사용합니다.
use.latest.version=true
# 의미상 동일한 스키마의 중복 등록을 방지합니다.
normalize.schemas=true

key.deserializer=org.apache.kafka.common.serialization.StringDeserializer
value.deserializer=io.confluent.kafka.serializers.KafkaAvroDeserializer

schema.registry.url=http://schema-registry-1:8081,http://schema-registry-2:8081

# 생성된 Avro 클래스로 역직렬화 (기본값 false → GenericRecord)
specific.avro.reader=true

Registry REST API — 주요 엔드포인트

# 새 스키마를 등록하지 않고 판정만 받습니다.
curl -sS -X POST \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{\"type\":\"record\",\"name\":\"OrderCreated\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"orderId\",\"type\":\"string\"}]}"}' \
  http://schema-registry:8081/compatibility/subjects/orders-value/versions/latest
# {"is_compatible": true}   또는  {"is_compatible": false, "messages": [...]}

# subject 별 호환성 모드 확인 · 변경
curl -sS http://schema-registry:8081/config/orders-value
curl -sS -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"compatibility": "BACKWARD_TRANSITIVE"}' \
  http://schema-registry:8081/config/orders-value

# 전역 기본값 확인 (Registry 기본값은 BACKWARD)
curl -sS http://schema-registry:8081/config

흔한 오해

시험 포인트 요약

확인 문제

호환성 매트릭스의 각 칸과 배포 순서, wire format 바이트 구성이 집중적으로 나옵니다.

이어서 볼 곳

• 9장 · Kafka Connect converter와 SMT, 내부 토픽, DLQ — 스키마가 실제로 쓰이는 곳. CCDAK Kafka Connect
• 7장 · 스토리지·리텐션·컴팩션 보관 기간이 길수록 옛 스키마의 데이터를 계속 읽어야 합니다. CCDAK Fundamentals
• 케이스 9 · 배포 순서를 뒤바꿨다 BACKWARD 토픽에 프로듀서를 먼저 올렸을 때의 실제 전개. 실수 케이스
• 예제 7 · Avro와 Schema Registry 동작하는 프로듀서·컨슈머와 스키마 진화 실험. 실무 예제
• CCDAK · Fundamentals 23% 도메인 압축 정리. 호환성 매트릭스 요약 포함. 자격증
• CCDAK 함정 사전 BACKWARD vs FORWARD, TRANSITIVE vs 비-TRANSITIVE 비교표. 자격증

공식 문서 출처

Schema Registry는 Apache Kafka 본체가 아니므로, 이 장의 사실 확인은 Confluent Schema Registry와 Apache Avro의 공개 소스에서 했습니다. 각 항목이 어디서 확인되었는지 명시합니다.

• Confluent — Schema Registry Concepts — subject · version · schema id 모델, Registry 아키텍처.
  확인 근거: confluentinc/schema-registry의 CompatibilityLevel(7종 열거), SchemaRegistryConfig의 schema.compatibility.level 기본값 backward
• Confluent — Wire Format — magic byte + schema id + payload.
  확인 근거: io.confluent.kafka.serializers.schema.id.SchemaId의 MAGIC_BYTE_V0 = 0x0 · MAGIC_BYTE_V1 = 0x1 · ID_SIZE = 4, idToBytes()/guidToBytes()/fromBytes() 구현, Protobuf의 message index 추가분, PrefixSchemaIdSerializer
• Confluent — Subject Name Strategy — 3종 전략.
  확인 근거: TopicNameStrategy(topic + "-key"/"-value"), RecordNameStrategy(레코드 FQN), TopicRecordNameStrategy(topic + "-" + recordName), 그리고 KEY/VALUE_SUBJECT_NAME_STRATEGY_DOC의 "By default, <topic>-key is used as subject" 서술
• Confluent — Schema Evolution and Compatibility — 7개 모드와 배포 순서.
  확인 근거: CompatibilityChecker의 소스 주석과 구성 — BACKWARD=canReadStrategy()+validateLatest() ("새 스키마가 이전 스키마로 생산된 데이터를 읽을 수 있는지"), FORWARD=canBeReadStrategy()+validateLatest(), FULL=mutualReadStrategy(), *_TRANSITIVE=validateAll(), NONE=no-op. 그리고 SchemaValidatorBuilder가 각 전략에서 isBackwardCompatible의 인자 순서를 뒤집어 방향을 만드는 구현
• Apache Avro — Schema Resolution — 매트릭스의 모든 판정 근거.
  확인 근거: Avro SchemaCompatibility의 checkReaderWriterCompatibility · checkReaderWriterRecordFields(reader 전용 필드의 default 요구) · lookupWriterField(reader 측 alias만 사용) · schemaNameEquals(reader aliases) · 타입 승격 분기(LONG←INT, FLOAT←INT/LONG, DOUBLE←INT/LONG/FLOAT, BYTES↔STRING) · checkReaderEnumContainsAllWriterEnumSymbols(enum default 예외) · union 분기 검사 · SchemaIncompatibilityType 6종(NAME_MISMATCH, FIXED_SIZE_MISMATCH, MISSING_ENUM_SYMBOLS, READER_FIELD_MISSING_DEFAULT_VALUE, TYPE_MISMATCH, MISSING_UNION_BRANCH). Confluent의 AvroSchema.isBackwardCompatible()이 이 함수를 (reader = this, writer = previousSchema)로 직접 호출하는 것도 확인했습니다
• Confluent — Schema Registry API Reference — REST 엔드포인트.
  확인 근거: SubjectsResource(/subjects), SubjectVersionsResource(/subjects/{subject}/versions), CompatibilityResource(/compatibility/subjects/{subject}/versions/{version}), ConfigResource(/config, /config/{subject}), SchemasResource(/schemas/ids/{id}, /schemas/types), ModeResource(/mode)의 @Path·@GET/@POST/@PUT/@DELETE 애너테이션
• Confluent — Serializer/Deserializer Configs — 직렬화기 설정 기본값.
  확인 근거: AbstractKafkaSchemaSerDeConfig의 AUTO_REGISTER_SCHEMAS_DEFAULT = true, USE_LATEST_VERSION_DEFAULT = false, LATEST_COMPATIBILITY_STRICT_DEFAULT = true, USE_SCHEMA_ID_DEFAULT = -1, NORMALIZE_SCHEMAS_DEFAULT = false, MAX_SCHEMAS_PER_SUBJECT_DEFAULT = 1000
• Apache Kafka — Producer Configs — key.serializer/value.serializer 규약