새 기능을 배포하고 나서야 "이전 버전 클라이언트가 아직 살아 있었다"는 사실을 알게 되는 상황은 드물지 않다. 롤링 배포 중 서버 절반이 새 스키마를 쓰고 나머지 절반이 구 스키마를 쓰는 상태, 외부 연동사가 이전 API 규격으로 계속 요청을 보내는 상태, 메시지 큐에 쌓인 오래된 이벤트를 새 소비자가 다시 읽어야 하는 상태. 이 세 장면은 모두 같은 질문으로 이어진다. 이전 버전을 언제까지 지원해야 하고, 그 기간에 무엇을 보장해야 하는가.
이 글은 "기술적으로 호환되는 변경이 무엇인가"보다 "운영 환경에서 신구 버전이 겹치는 기간을 어떻게 설계하고 종료 조건을 어떻게 정하는가"에 초점을 둔다.
하위 호환성이 필요한 상황과 그렇지 않은 상황
모든 변경이 이전 버전과의 호환을 요구하지는 않는다. 판단 기준은 하나다. 내가 직접 제어할 수 없는 소비자가 존재하는가.
다음 네 가지 중 하나라도 해당한다면 호환 계획이 필요하다.
- 외부 기업이나 파트너가 현재 API나 데이터 형식에 의존하고 있다.
- 배포 방식이 롤링 또는 블루/그린이어서, 일정 시간 구버전 서버가 신버전 서버와 동시에 요청을 처리한다.
- 메시지 큐나 이벤트 로그에 이미 발행된 데이터가 나중에 재처리될 수 있다.
- 모바일 앱처럼 사용자가 스스로 업데이트 시점을 고르는 클라이언트가 있다.
반대로 완전히 격리된 내부 서비스 간 변경이고, 배포를 한 번에 교체하며, 재처리 대상이 없다면 엄격한 호환 요건 없이 진행할 수 있다. 중요한 것은 이 조건을 배포 계획서에 명시하는 것이다. 막연하게 "내부 서비스니까 괜찮겠지"가 아니라, 실제로 그 조건이 충족되는지 확인한 뒤 결정해야 한다.
호환성의 세 층위: 어디서 깨지는지를 먼저 나눠야 한다
변경이 안전한지 판단하려면 무엇이 '통한다'는 의미인지 구분해야 한다. 세 층위로 나눠 보면 실패 지점을 훨씬 빠르게 찾을 수 있다.
빌드 호환성: 이전 코드가 새 버전 라이브러리나 인터페이스로도 컴파일되고 실행되는가. 메서드 이름이나 매개변수를 바꾸면 여기서 먼저 깨진다.
통신 호환성: 이전 클라이언트가 새 서버에 요청을 보내고 응답을 받을 수 있는가. 필수 필드를 새로 추가하거나 기존 응답 필드를 삭제하면 여기서 깨진다.
의미 호환성: 통신은 성공했지만 값의 해석이 달라지지 않았는가. 상태값 READY가 "결제 전"에서 "처리 중"으로 의미가 바뀌었을 때 HTTP 200이 돌아오더라도 서비스 동작은 달라진다.
세 번째 층위가 가장 찾기 어렵다. 테스트에서 파싱 오류 없이 통과했다고 안전하다고 볼 수 없는 이유가 여기에 있다. 변경 전에 확인해야 할 질문은 "기존 필드와 새 필드의 업무적 의미가 정말 같은가"다.
상황별 판단: 롤링 배포, 외부 API, 이벤트 재처리
롤링 배포 중 데이터베이스 스키마를 바꿀 때
롤링 배포는 서버 인스턴스를 순차적으로 교체한다. 첫 번째 서버가 마이그레이션을 실행하고 새 스키마를 쓰기 시작해도, 나머지 서버는 아직 구 스키마를 기준으로 동작한다. 두 버전이 같은 데이터베이스에 동시에 읽고 쓰는 시간이 반드시 발생한다.
이 상황에서 기존 컬럼을 삭제하거나 이름을 바꾸는 것은 배포 완료 전까지 구버전 서버를 즉시 고장낸다. 안전한 순서는 이렇다.
- 새 컬럼을 추가하되 기존 컬럼은 그대로 유지한다.
- 새 버전 코드를 배포한다. 이 코드는 새 컬럼에 쓰면서 기존 컬럼에도 동시에 값을 기록한다.
- 배포가 완전히 끝나고 이전 버전 인스턴스가 없어지면, 기존 컬럼에 쓰는 코드를 제거한다.
- 기존 컬럼 자체는 그다음 배포에서 삭제한다.
단계를 건너뛰고 싶은 유혹이 강하지만, 배포 중에 오류가 발생하면 롤백 비용이 훨씬 크다. 각 단계는 별도 배포로 분리하는 것이 원칙이다.
외부 연동사가 있는 B2B API를 변경할 때
여러 기업이 같은 API를 사용하고 있다면, 제공자가 새 규격을 배포한다고 해서 연동사가 같은 날 코드를 바꿀 수 없다. 각사의 개발 일정과 검증 절차가 다르다.
이때 결정해야 하는 것은 두 가지다.
얼마나 오래 병행 지원할 것인가. 기존 필드와 새 필드를 얼마나 오래 함께 처리할지는 연동사 수, 전환 난이도, 비즈니스 의존도에 따라 달라진다. Google은 Gemini API 모델별로 지원 종료 일정을 공식 문서로 미리 공개하고 있는데, 이처럼 종료 일정을 배포 시점에 함께 알리는 방식은 연동사가 전환 계획을 세울 수 있게 해준다.
어떤 조건이 충족되면 구 필드를 제거할 것인가. "이전 형식으로 오는 요청이 0이 될 때" 같은 측정 가능한 기준이 없으면 임시 호환 코드가 영구 코드가 된다. 로그 기반으로 구버전 사용량을 추적하고, 일정 기간 이상 사용량이 0에 수렴하면 제거 검토를 시작하는 절차를 처음부터 설계해야 한다.
이벤트 형식을 바꿀 때
API와 달리 이벤트는 발행자와 소비자가 반드시 함께 배포되지 않는다. 주문 서비스가 새 필드를 담아 이벤트를 발행해도, 알림 서비스나 정산 서비스는 각자의 일정에 따라 나중에 배포될 수 있다. 메시지 큐에 쌓인 오래된 이벤트를 새 소비자가 나중에 재처리하는 상황도 고려해야 한다.
여기서 "누가 먼저 배포되는가"에 따라 확인해야 할 방향이 달라진다.
- 소비자를 먼저 배포한다면, 새 소비자가 이전 형식의 이벤트를 처리할 수 있어야 한다. 재처리 시나리오에서도 마찬가지다.
- 발행자를 먼저 배포한다면, 이전 소비자가 새 형식의 이벤트를 받았을 때 오류로 빠지거나 잘못된 상태로 해석하지 않아야 한다.
필드 추가는 상대적으로 안전하지만 소비자가 알 수 없는 필드를 어떻게 처리하는지에 따라 결과가 달라진다. 새로운 상태값 추가는 더 위험하다. 소비자가 PAID와 CANCELED만 알고 있는데 REFUNDED를 받으면, 오류로 처리하거나 기존 상태 중 하나로 잘못 해석할 수 있다. 이 경우 소비자가 모르는 상태값을 안전하게 무시하거나 별도로 기록해 두는 처리 방식이 이벤트 형식 변경 전에 이미 배포되어 있어야 한다.
지원 종료 조건을 처음부터 문서에 넣어야 하는 이유
호환 기간을 정해 두지 않으면 문제는 반드시 두 곳에서 생긴다.
하나는 임시 호환 코드가 제거되지 않고 쌓이면서 시스템이 점점 복잡해지는 것이다. 새 규격과 구 규격을 동시에 처리하는 분기가 늘어날수록 변경 비용도 함께 늘어난다.
다른 하나는 종료 일정이 없으면 연동사나 팀이 전환 계획을 세우기 어렵다는 점이다. "언제까지 지원된다"는 정보가 있어야 상대방이 일정을 잡을 수 있다.
지원 종료 조건은 배포 계획서나 API 변경 공지에 처음부터 포함되어야 한다. 예를 들어 "구 필드는 신 필드 배포 후 90일간 병행 지원하며, 이후 로그상 사용량이 0으로 확인되면 제거 일정을 별도 공지한다"처럼 측정 기준과 절차를 함께 명시하는 방식이 실용적이다.
PM이 배포 계획서에 먼저 적어야 할 것들
하위 호환성 문제는 개발 단계에서 코드로 해결하는 것이 아니라, 배포 계획 단계에서 운영 조건으로 결정된다. PM이 기능 요구사항을 정리할 때 함께 확인해야 할 항목을 정리하면 다음과 같다.
- 이 변경에 영향을 받는 외부 연동사나 내부 팀의 수와 전환 가능 일정
- 롤링 또는 블루/그린 배포 여부, 그리고 배포 중 구버전 서버가 얼마나 오래 남는지
- 메시지 큐나 로그에서 재처리 대상이 될 이벤트의 존재 여부
- 구 형식 지원 종료 조건과 그것을 확인할 방법
- 신구 버전 병행 기간 동안 어떤 모니터링 지표로 이상을 감지할 것인지
이 항목들이 배포 전에 결정되어 있다면, 개발팀이 구현 단계에서 무엇을 만들어야 하는지도 명확해진다. 이 정보 없이 "새 기능을 구현해 달라"고만 요청하면 코드 밖의 운영 맥락은 빠지기 쉽다.
새 버전이 준비됐다는 사실과 이전 버전을 제거해도 된다는 사실은 같은 시점에 성립하지 않는다. 두 시점 사이의 간격을 얼마나 의식적으로 설계하느냐가 배포 전략의 핵심이다. 그 간격을 정의하는 일을 배포 이후로 미루지 않는 것이 출발점이다.
