이벤트에 필드를 하나 추가하거나 이름을 바꾸면 생산 서비스는 정상인데 구독 서비스가 멈출 수 있습니다. 이벤트는 보낸 뒤 여러 시스템이 각자의 속도로 읽는 계약입니다. 생산자만 보고 스키마를 바꾸지 않으려면 호환성과 전환 기간을 설계해야 합니다.
이벤트의 의미부터 고정한다
같은 '주문 완료'라도 결제 완료인지 배송 준비 완료인지에 따라 구독자의 행동이 달라집니다. 필드 타입뿐 아니라 발생 조건과 기준 시각을 계약에 적습니다.
한 이벤트에 서로 다른 의미를 계속 덧붙이면 소비자가 분기문으로 가득해집니다. 의미가 달라졌다면 새 이벤트 유형을 만들지 검토합니다.
읽는 쪽의 배포 속도를 고려한다
생산자가 새 필드를 보내도 이전 구독자는 한동안 기존 스키마로 동작할 수 있어야 합니다. 필수 필드 삭제나 타입 변경은 하위 호환성을 깨뜨리기 쉽습니다.
새 필드를 선택적으로 추가할 때도 기본값과 누락 의미를 정의합니다. 값이 없다는 것이 '아직 모름'인지 '해당 없음'인지 다르면 처리 결과도 달라집니다.
오래된 이벤트를 재처리해 본다
장애 복구나 신규 구독자는 과거 이벤트를 다시 읽을 수 있습니다. 현재 코드가 과거 버전을 읽을 수 있는지 확인해야 합니다. 최근 데이터만 통과하는 테스트로는 부족합니다.
스키마 레지스트리나 계약 테스트를 사용해 예상치 못한 변경을 배포 전에 발견합니다. 도구가 있어도 업무 의미의 변화까지 자동 검증해 주지는 않습니다.
가상 사례: 금액 단위 변경
금액 필드가 원 단위였는데 갑자기 소수 단위 값으로 바뀌었다고 가정해 봅시다. 필드 이름과 자료형이 그대로면 기술적 스키마 검사는 통과해도 정산이 틀립니다.
새 필드를 만들고 단위를 명시하거나 이벤트 버전을 나누어 소비자가 전환할 시간을 줍니다. 예시는 이벤트 계약의 위험을 설명하기 위한 가정입니다.
전환 종료 조건을 확인한다
모든 구독자가 새 버전으로 옮겼는지 사용량과 배포 상태를 확인합니다. 오래된 필드를 너무 빨리 없애면 드물게 실행되는 배치 작업이 깨질 수 있습니다.
변경 기록에는 스키마 버전, 배포 시각, 영향받는 구독자와 되돌리기 방법을 남깁니다. 이벤트 계약은 코드보다 오래 살아남는 경우가 많습니다.
현장에 적용할 때의 순서
- 이벤트 업무 의미와 단위를 명시한다
- 이전 구독자로 새 스키마를 시험한다
- 과거 이벤트 재생을 검증한다
주의할 실패: 자료형이 같아도 금액 단위가 바뀌면 계약 테스트를 통과한 채 정산이 틀릴 수 있다.
관찰할 지표: 구독자 버전별 실패와 구형 필드 사용량을 기록한다.
적용 전 체크리스트
- 필드의 업무 의미와 단위가 문서화돼 있는가
- 과거 이벤트 재처리가 가능한가
- 구독자 전환 완료를 확인한 뒤 구형 필드를 제거하는가
참고 자료
Confluent Schema Evolution 문서. 공식 문서는 스키마 호환성 유형을 설명합니다. 이벤트의 업무 의미와 배포 전환 절차는 별도 설계가 필요합니다.
이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.
#이벤트스키마 #스키마진화 #이벤트계약 #데이터아키텍처 #메시지큐 #하위호환성 #마이크로서비스 #데이터정합성 #백엔드 #버전관리
