파이썬 Protobuf 직렬화 호환성 안전하게 유지하는 법 필드 추가부터 reserved 처리까지

📌 Protobuf 호환성의 기본 개념

Protobuf를 쓰는 이유 중 하나는 “지금 보내는 메시지”와 “나중에 받아볼 메시지”가 꼭 같지 않아도 서로 이해할 수 있게 설계되어 있기 때문입니다.
쉽게 말하면 서버와 클라이언트가 버전이 달라도 깨지지 않고 통신하자는 약속입니다.
이게 바로 호환성, 즉 backward compatibility(새 버전 코드가 예전 메시지를 읽을 수 있음)과 forward compatibility(예전 코드가 새 메시지를 읽어도 최소한 망가지지 않음)입니다.

Protobuf 메시지에서 실제로 중요한 건 필드 이름이 아니라 태그 번호(tag number)입니다.
각 필드 옆에 붙는 “= 1”, “= 2” 같은 숫자가 바로 그 번호인데, 이 숫자가 바이너리 데이터에 그대로 들어갑니다.
그래서 이 번호를 한 번 세상에 배포하면 사실상 영구적으로 고정이라고 보면 됩니다.
번호를 다른 의미로 재사용하면, 어떤 인스턴스는 그 숫자를 “나이”라고 이해하고 다른 인스턴스는 “권한 등급”으로 이해해버리는 식의 참사가 생깁니다.
공식 가이드에서도 태그 번호 재사용은 파싱 오류, 심하면 개인 식별 정보(PII) 노출, 데이터 손상까지 이어질 수 있다고 경고합니다.

이 때문에 Protobuf에서는 “필드를 삭제했다”고 끝내지 않습니다.
그 필드에 쓰였던 번호와 이름을 reserved로 남겨서 다시는 아무도 그 번호를 새 의미로 쓰지 못하게 막아야 합니다.
이건 선택이 아니라 안전 수칙입니다.
만약 예약(reserved)하지 않은 채 번호를 재사용하면, 예전 클라이언트는 그 번호를 옛날 타입으로 읽고 새 서버는 새 타입으로 쓰는 상황이 생기고, 그건 곧 서로 다른 현실을 공유하게 된다는 뜻입니다.

파이썬 코드 생성기를 포함한 Protobuf 런타임은, 모르는 필드를 만나면 보통 그 필드를 “unknown field”로 취급하고 무시합니다.
즉 새로운 필드가 추가돼도 예전 클라이언트가 바로 터지지는 않습니다.
하지만 여기서 조심할 점이 하나 더 있습니다.
모르는 필드를 버린다는 건, 로직 입장에서는 “없는 값”처럼 보인다는 의미입니다.
그래서 나중에 서버 쪽에서 “이 값은 항상 온다고 가정”하고 코드를 짜면 구버전 클라이언트와 충돌이 나기 쉬워집니다.

정리하면 Protobuf의 호환성은 크게 다음과 같은 원칙 위에 서 있습니다.

• 🔁필드 번호(tag number)는 한 번 공개되면 바꾸지 않는다. “살짝 바꾸면 되지 않나?”는 통하지 않는다.
• 🚫필드를 없앨 때는 reserved로 봉인한다. 번호 재사용은 사고의 지름길이다.
• 📦새 필드는 자유롭게 “추가”할 수 있지만 기존 의미를 바꾸는 건 금물이다. 타입이나 의미를 바꾸면 구버전이 잘못 해석할 수 있다.
• 🧩알 수 없는 필드는 조용히 무시된다. 즉 “없는 값처럼” 동작하므로, 파이썬 쪽 비즈니스 로직은 그 가능성을 항상 고려해야 한다.
• 🧱Any, Wrapper, oneof 같은 구조는 확장 포인트다. 앞으로 확장될 여지를 미리 만들어두면 스키마 변경 충격을 줄일 수 있다.

여기까지의 내용을 파이썬 시점에서 보면 한 가지 결론으로 모입니다.
.proto를 한 번 배포하면 그건 사실상 API 계약(contract)입니다.
“조금 정리하려고 필드 하나 지웠어” 같은 가벼운 리팩터링도 아무 생각 없이 하면 안 됩니다.
필드 삭제, 필드 재사용, 의미 변경은 바로 장애로 직결될 수 있기 때문에, 안전한 흐름은 오히려 “남겨두고 deprecated 처리”하거나 “reserved로 묶어 봉인”하는 쪽입니다.

💬 Protobuf 공식 가이드는 “필드 번호는 절대 재사용하지 말라”, “삭제한 필드는 reserved로 막아라”라고 못 박고 있습니다. 이것만 제대로 지켜도 서비스 간 데이터 해석 불일치, 즉 서로 다른 버전이 같은 바이트를 다르게 읽어버리는 최악의 상황을 상당히 줄일 수 있습니다.

📌 필드 추가와 역직렬화 기본값 처리

Protobuf의 가장 큰 장점은, 새 필드를 추가해도 기존 코드가 깨지지 않는다는 점입니다.
즉, backward compatibility(하위 호환성)을 자연스럽게 보장합니다.
예를 들어 서버가 새로운 필드 user_level을 추가했더라도, 예전 버전의 클라이언트는 이 필드를 모른 척하고 나머지 데이터를 정상적으로 읽을 수 있습니다.
이건 파이썬에서 메시지를 역직렬화할 때도 동일하게 적용됩니다.
모르는 필드는 내부적으로 “unknown field set”으로 분류되고, 접근 시점까지는 메모리에도 로드되지 않습니다.

하지만 여기서 주의할 점은, 기본값(default value)의 존재입니다.
Protobuf는 누락된 필드를 단순히 None으로 처리하지 않습니다.
정수형이면 0, 문자열은 “”, 불리언은 False, enum은 첫 번째 값으로 자동 채워 넣습니다.
따라서 역직렬화 시 “이 값이 명시적으로 들어온 건지” 혹은 “그냥 기본값으로 채워진 건지”를 구분하기 어렵습니다.
이는 실무에서 버그의 씨앗이 되기 쉽습니다.

파이썬에서 이를 피하려면 Wrapper 타입을 활용하는 것이 좋습니다.
예를 들어 google.protobuf.Int32Value나 StringValue 같은 래퍼를 사용하면, 값이 존재하지 않을 때는 None처럼 구분 가능합니다.
즉, 필드 존재 여부를 명확하게 인식할 수 있어 역직렬화 로직이 훨씬 안전해집니다.
이런 Wrapper는 JSON 변환 시에도 null 값이 명시적으로 표현되므로, REST API와 Protobuf를 함께 사용하는 경우 특히 유용합니다.

syntax = "proto3";

import "google/protobuf/wrappers.proto";

message UserProfile {
    string name = 1;
    google.protobuf.Int32Value age = 2;  // 값이 없을 수 있음
}

이렇게 정의하면, 클라이언트가 age 필드를 안 보냈을 때 파이썬 코드에서 단순히 0으로 채워지지 않고, None처럼 취급됩니다.
즉, “이 값이 원래 존재했는가?”를 명확하게 알 수 있는 것입니다.
이는 데이터 유효성 검사나 조건 분기에서 아주 중요합니다.
예를 들어 사용자의 나이를 기준으로 로직을 분기할 때, 단순히 0이 아니라 “아예 값이 없다”는 상태를 구분할 수 있으니까요.

또 하나 실무에서 자주 나오는 오해가 있습니다.
“Protobuf는 기본값이 있으니 모든 필드가 항상 초기화돼 있겠지?”라고 생각하기 쉽지만, 그렇지 않습니다.
기본값은 단순히 직렬화 시점에 적용되는 표현상의 값일 뿐입니다.
즉, 실제 메시지에 해당 필드가 없을 수 있으며, 직렬화된 데이터에는 그 부분이 아예 존재하지 않을 수도 있습니다.
그래서 “필드가 존재하는가”와 “필드 값이 기본값인가”는 서로 다른 이야기입니다.

결국 필드 추가는 자유롭지만, 기본값 처리의 함정까지 이해하고 있어야 진짜 안전합니다.
서버가 새 필드를 추가했을 때, 클라이언트가 모르는 필드를 무시하면서도 기존 로직이 엉키지 않도록 설계해야 합니다.
이때 Wrapper를 통한 명시적 null 지원, 혹은 oneof 구조로 필드 존재 여부를 표현하는 방식이 파이썬 쪽에서도 가장 현실적입니다.

📌 필드 삭제 금지와 reserved가 필요한 이유

Protobuf를 사용할 때 가장 많이 발생하는 실수는 바로 필드를 삭제하는 것입니다.
“이제 안 쓰는 값이니까 지워도 되겠지?” 하고 .proto 파일에서 필드를 제거하면, 예전 버전의 시스템이 여전히 그 번호를 포함한 데이터를 전송할 때 심각한 문제가 발생합니다.
서버는 그 바이트를 전혀 다른 의미로 읽거나, 아예 알 수 없는 데이터로 인식하게 되죠.

그래서 Protobuf 공식 문서에서는 명확하게 이야기합니다.
“필드를 제거할 때는 반드시 reserved 키워드를 사용하라.”
이 reserved 선언은 “이 번호와 이름은 앞으로 절대 다시 사용하지 않는다”는 약속이자, 호환성을 위한 안전장치입니다.
즉, 이미 사용된 태그 번호는 재사용하지 않고 예약만 남겨두는 것이죠.
이렇게 해야 새 메시지를 정의할 때, 과거 클라이언트가 보낸 데이터를 다른 의미로 해석하지 않게 됩니다.

message UserProfile {
    string name = 1;
    int32 age = 2;
    // int32 gender = 3;  // 더 이상 사용하지 않음
    reserved 3;          // 태그 번호 3은 재사용 금지
    reserved "gender";   // 이름도 재사용 금지
}

이 예시에서처럼 필드를 완전히 삭제하는 대신, 그 번호와 이름을 reserved로 명시해두면 훨씬 안전합니다.
만약 reserved 선언 없이 그냥 지워버리면, 나중에 새로운 필드를 3번 번호로 추가했을 때 예전 클라이언트가 “gender”로 인식해버리는 문제가 생길 수 있습니다.
서로 다른 의미로 같은 태그를 사용하는 건 Protobuf에서 가장 위험한 실수 중 하나입니다.

또 하나 흔한 착각은 “필드 이름만 다르면 괜찮겠지?”입니다.
하지만 Protobuf는 직렬화 시 이름이 아닌 번호로 데이터를 식별하므로, 이름만 바꿔봤자 무의미합니다.
이름은 컴파일 시점의 문서 역할일 뿐, 실제 통신에서는 태그 번호가 전부입니다.
결국 reserved는 이름보다도 번호를 보호하기 위한 기능입니다.

파이썬으로 코드를 생성할 때도 reserved는 그대로 유지됩니다.
즉, 예약된 번호에 필드를 추가하려 하면 컴파일 오류가 발생하므로, 사람이 실수로 덮어쓰는 일을 막을 수 있습니다.
이는 장기적으로 스키마를 안정적으로 관리할 때 매우 큰 도움이 됩니다.

결국 Protobuf 스키마의 안정성은 ‘변하지 않는 번호’에서 시작됩니다.
이 단순한 원칙 하나로 수많은 버전 충돌을 막을 수 있고, 장기적으로는 서비스 전반의 신뢰성을 높여줍니다.
파이썬 서비스가 수년간 발전하면서도 동일한 메시지를 안전하게 주고받을 수 있는 이유가 바로 여기에 있습니다.

📌 oneof으로 선택적 변화 안전하게 설계하기

Protobuf에는 여러 필드 중 단 하나만 값을 가질 수 있도록 정의하는 oneof이라는 구조가 있습니다.
이 구조는 메시지 스키마가 앞으로 변화할 가능성이 있는 경우 특히 유용합니다.
예를 들어, 사용자 프로필에서 로그인 방식을 ID 기반에서 소셜 로그인 기반으로 확장하려고 할 때, 완전히 새로운 필드를 추가하는 대신 oneof으로 묶어두면 호환성을 유지하면서 확장이 가능합니다.

message LoginInfo {
    oneof login_method {
        string username = 1;
        string google_id = 2;
        string apple_id = 3;
    }
}

위 예시에서 로그인 방식이 여러 가지일 수 있지만, 동시에 여러 값이 들어오면 안 됩니다.
Protobuf는 oneof 내부에서 단 하나의 필드만 설정될 수 있도록 강제합니다.
즉, username을 세팅하면 google_id나 apple_id는 자동으로 비워집니다.
이런 제약 덕분에 서로 다른 타입의 확장을 안전하게 다룰 수 있습니다.
또한 기존 클라이언트는 모르는 필드가 oneof 안에 들어와도 무시해버리므로, forward compatibility도 자연스럽게 확보됩니다.

파이썬에서 oneof은 속성 접근을 통해 어떤 필드가 설정돼 있는지 쉽게 확인할 수 있습니다.
예를 들어 which_oneof() 메서드를 사용하면 현재 활성화된 필드명을 알 수 있습니다.
이를 통해 클라이언트나 서버에서 조건 분기를 명확하게 처리할 수 있습니다.

info = LoginInfo(google_id="abc123")
print(info.WhichOneof("login_method"))  # 출력: 'google_id'

이 메커니즘 덕분에 서비스가 확장되더라도, “한 시점에는 한 로그인 방식만 존재”한다는 제약이 유지됩니다.
oneof을 사용하지 않고 필드를 여러 개 두면, 클라이언트가 동시에 두 필드를 채워버려서 혼란스러운 상태가 만들어질 수 있습니다.
이런 데이터 불일치는 나중에 역직렬화 로직에서 큰 오류로 이어질 수 있습니다.

oneof은 “서로 배타적인 상태”를 표현하는 데 최적화되어 있으며, 선택지 확장에 매우 강력합니다.
하지만 반대로 이미 존재하는 필드를 oneof 안으로 옮기는 것은 위험합니다.
이는 메시지의 인코딩 방식 자체를 바꿔버리는 행위로 간주되기 때문입니다.
즉, oneof 추가는 가능하지만, 기존 필드를 oneof에 재배치하는 건 금지입니다.

결론적으로, oneof은 필드 간의 관계를 명확하게 표현하고 미래의 확장을 대비할 수 있는 강력한 수단입니다.
파이썬 Protobuf 코드에서는 간결하게 처리할 수 있고, 런타임에서도 어떤 필드가 설정됐는지 쉽게 확인할 수 있어 유지보수성이 높습니다.
서비스가 커질수록 이런 구조적인 안전장치는 필수적입니다.

📌 Any와 Wrapper 타입으로 유연한 확장 만들기

Protobuf를 이용하다 보면, 앞으로 어떤 데이터가 들어올지 확실하지 않은 경우가 많습니다.
이럴 때 메시지 구조를 계속 바꾸는 대신, Any나 Wrapper 타입을 사용하면 훨씬 유연한 확장이 가능합니다.
이 두 가지는 호환성과 버전 관리에서 매우 중요한 역할을 하며, 특히 파이썬 환경에서는 동적 데이터 처리에 강점을 보입니다.

Any 타입은 메시지 안에 “어떤 타입의 메시지든” 넣을 수 있도록 설계된 특수한 타입입니다.
내부적으로는 type_url과 value 두 필드로 구성되어 있으며, 메시지를 직렬화할 때 타입 정보를 함께 저장합니다.
덕분에 서로 다른 서비스나 버전 간에, 미리 알지 못한 타입의 데이터를 전달할 수 있습니다.

syntax = "proto3";

import "google/protobuf/any.proto";

message Event {
    string event_id = 1;
    google.protobuf.Any payload = 2;
}

위 예시에서 payload는 어떤 메시지든 담을 수 있습니다.
예를 들어 UserProfile, OrderInfo 등 서로 다른 메시지를 하나의 Event 안에 넣을 수 있죠.
파이썬에서는 Any.Pack()과 Any.Unpack() 메서드로 실제 메시지를 안전하게 직렬화/역직렬화할 수 있습니다.
이 구조는 이벤트 시스템이나 알림, 로그 데이터 전송 등 다양한 상황에서 “알 수 없는 타입”을 안전하게 처리하는 데 활용됩니다.

반면, Wrapper 타입은 기본형(scalar)을 nullable 형태로 감싸기 위한 구조입니다.
google.protobuf.Int32Value, BoolValue, StringValue 등이 대표적입니다.
이 타입들은 값이 없을 때 None으로 구분할 수 있어, 기본값(0, “”, False)과 “값이 아예 없음”을 명확히 구분할 수 있습니다.
즉, Wrapper는 명시적 결측값 표현에 초점을 둔 타입입니다.

syntax = "proto3";

import "google/protobuf/wrappers.proto";

message Product {
    string name = 1;
    google.protobuf.Int32Value price = 2;  // null 가능
}

파이썬에서 이 메시지를 역직렬화하면, price가 설정되지 않았을 때 단순히 0이 아니라 None처럼 처리됩니다.
이는 “값이 실제로 전달되지 않았다”는 의미를 코드로 명확히 구분할 수 있게 해줍니다.
이런 구조는 REST API나 gRPC 양쪽 모두에서 데이터를 일관되게 다루는 데 큰 장점을 줍니다.

결국 Any와 Wrapper는 Protobuf 호환성의 마지막 퍼즐입니다.
새로운 요구사항이 추가되더라도 스키마를 변경하지 않고 데이터를 확장할 수 있고, 파이썬 코드에서도 타입 안정성을 유지할 수 있습니다.
이런 구조를 미리 설계에 반영해두면, 향후 서비스 확장 시 불필요한 버전 충돌이나 역직렬화 오류를 크게 줄일 수 있습니다.

❓ 자주 묻는 질문 (FAQ)

💎 핵심 포인트:
Protobuf 호환성은 “지우지 말고, 추가하라”는 원칙으로 요약됩니다. 필드 삭제 금지, reserved 처리, Wrapper를 통한 null 구분, oneof과 Any로의 확장—all 이 네 가지가 서비스의 데이터 안정성을 결정합니다.