gRPC 서비스에 대한 자동화된 계약 테스트를 구현하는 것은 전통적인 REST 검증과는 근본적으로 다른 접근 방식을 요구합니다. 프로토콜 버퍼(protobuf)는 인간이 읽을 수 있는 텍스트 대신 이진 직렬화에 의존하기 때문입니다. 전략은 세 가지 기둥에 집중해야 합니다: 스키마 진화 관리, 이진 페이로드 무결성, 언어 비구조적 직렬화 확인.
buf(프로토콜 버퍼 빌드 시스템)를 활용하여 CI/CD 파이프라인에서 린트 규칙과 파괴적 변경 감지를 시행하십시오. buf breaking 명령을 설정하여 현재 proto 정의를 이전 Git 커밋 또는 Protobuf 스키마 레지스트리 기준선과 비교하여 필드 번호가 변하지 않도록 하고 삭제된 필드가 올바르게 예약되어 와이어 형식 손상을 방지하도록 하십시오.
크로스 언어 검증을 위해 gRPC 플러그인 지원이 있는 Pact를 사용하거나 Java, Go, Python에서 스텁을 생성하여 한 언어에서 직렬화된 메시지가 다른 언어에서 올바르게 역직렬화되는지 확인하는 사용자 정의 이진 검증 스위트를 구현하십시오. 이는 언어별 구현이 기본값이나 포장된 반복 필드를 다르게 해석할 수 있는 미세한 문제를 잡아냅니다.
또한 prototool 또는 buf generate를 Bazel과 통합하여 생성된 클라이언트 라이브러리가 서비스 배포와 동기화 상태를 유지하도록 하여 소비자가 오래된 proto 계약을 기반으로 컴파일하는 "임피던스 불일치"를 방지하십시오.
문제 설명
한 핀테크 회사가 Java 기반 모놀리스를 사용하여 gRPC로 결제 처리를 마이그레이션하여 새로운 Go 마이크로서비스가 리스크 계산을 처리하는 간섭을 개선했습니다. 프로덕션에서 3주 후 Java 서비스가 업데이트된 Go 서비스와 통신할 때 잘못된 리스크 점수를 계산하기 시작했습니다. 조사 결과 Go 팀이 proto 필드를(이름 변경) risk_factor에서 risk_score로 바꾸고 같은 배포에서 필드 번호를 5에서 6으로 변경한 것으로 나타났습니다. 이름 변경이 안전하다고 가정했지만 Java 클라이언트는 여전히 태그 5로 이진 데이터를 전송하고 있었고, Go 서비스는 이를 다른 필드(부울 is_flagged)로 해석하여 직렬화 실패 대신 조용한 논리적 오류를 발생시켰습니다.
고려된 다양한 솔루션
Pull 요청을 통한 수동 proto 파일 검토 : 팀은 proto 변경 사항에 대한 pull 요청을 시각적으로 검사하여 코드 소유자가 파괴적인 수정을 잡도록 하였습니다. 장점: 제로 인프라 비용, 기존 GitHub 워크플로우 활용. 단점: 인간 리뷰어는 필드 이름이 동시에 업데이트될 때 필드 번호 변경을 계속 놓치며, 이진 페이로드의 호환성이 자동으로 보장되지 않으며, 일일 배포로 15개 이상의 마이크로서비스에서 확장성이 좋지 않았습니다.
buf 파괴 감지를 이용한 정적 분석: CI 파이프라인에서 proto 파일을 기본 브랜치와 비교하여 필드 태그가 수정되거나 예약 없이 제거될 경우 빌드를 실패시키는 자동화된 buf 파괴 검사를 구현했습니다. 장점: 즉각적인 피드백(서브 초 실행), 특정 필드 번호 변형 문제 예방, 경량 통합. 단점: 스키마 정의만 검증하고 실제 이진 직렬화 동작 또는 언어별 엣지 케이스(예: Go가 nil 슬라이스를 처리하는 방법 vs Java가 빈 리스트를 처리하는 방법)를 검증하지 않았으며, 두 서비스가 올바른 스키마를 사용했지만 다른 protobuf 라이브러리 버전이 알 수 없는 필드를 다르게 해석하는 문제를 잡지 못했습니다.
이진 페이로드 검증이 포함된 양방향 계약 테스트: Pact gRPC 확장을 사용하여 Java 클라이언트가 예상되는 이진 요청/응답 페이로드를 기록하고, Go 제공자가 이를 소비 및 생성할 수 있는지 검증하는 소비자 주도 계약을 생성합니다. 또한 Docker Compose를 사용하여 제안된 변경 사항에서 생성된 proto 스텁과 함께 두 서비스를 실행하기 위해 크로스 언어 통합 테스트를 구현합니다. 장점: 실제 직렬화/역직렬화 왕복을 검증하고, 언어별 기본값 불일치 문제를 잡아내며, 두 서비스가 배포 전에 와이어 형식에 동의하도록 보장했습니다. 단점: 초기 설정이 복잡하며, 두 팀이 공유 계약 저장소를 유지해야 했고, 멀티 컨테이너 오케스트레이션으로 인해 CI 실행 시간이 빌드당 4분 증가했습니다.
선택된 솔루션 및 근거
팀은 기능 브랜치에서 즉각적인 개발자 피드백을 제공하는 buf 파괴 검사와 Pull 요청 빌드 중 Pact 계약 검증을 결합한 하이브리드 접근 방식을 선택했습니다. buf 도구는 초기 사건을 유발한 필드 번호 변형을 예방하는 내부 개발을 위한 필요한 속도를 제공했습니다. Pact 계층은 특히 Java가 빈 문자열을 길이 구분 없는 제로 바이트로 직렬화하고 Go는 protobuf optional 문자열에 대해 필드가 없음을 기대하는 엣지 케이스를 포착하여 이진 호환성에 중요한 안전망을 추가했습니다. 이 조합은 실행 속도와 포괄적인 안전성을 균형 있게 유지했습니다.
결과
구현 후, 파이프라인은 첫 달에 12개의 파괴적인 proto 변경 사항을 감지했습니다(3개의 필드 번호 변형 및 2개의 예약 필드 충돌 포함), 모두 프로덕션이 아닌 개발 중에 포착되었습니다. 배포 후 6개월 동안 직렬화와 관련된 사건이 발생하지 않았습니다. 계약 위반을 감지하는 평균 시간은 4.2일(생산 디버깅)에서 3분(CI 실패)으로 단축되었고, 크로스 언어 테스트 스위트는 Java와 Go 엔지니어링 팀 간의 API 버전 논의의 진실의 근원이 되었습니다.
계약 테스트 시 protobuf 메시지에서 필드를 영구적으로 제거할 때 하위 호환성을 어떻게 처리합니까?
후보자들은 종종 단순히 .proto 파일에서 필드 줄을 삭제하라고 제안합니다. 올바른 구현은 reserved 키워드를 사용하여 필드 번호의 미래 재사용을 방지하고, 필드를 제거하기 전 최소 하나의 주요 버전 주기 동안 [deprecated=true] 주석을 사용하여 마크하는 것입니다. 계약 테스트는 제거된 필드가 오류 없이 기본값 또는 명시적 기본값으로 새 메시지를 파싱할 수 있도록 하여 이전 소비자가 여전히 새 메시지를 파싱할 수 있는지(전진 호환성)를 검증해야 합니다. 또한 테스트는 پروتو버프 컴파일러가 예약 태그를 재사용하려는 새로운 필드를 거부하는지 확인해야 하며, 일반적으로 buf lint 규칙 PROTO3_FIELDS_NOT_RESERVED와 제거된 필드에 대한 해당 예약 선언이 없는지 검사하는 맞춤 CI 게이트를 통해 시행됩니다.
프로토콜 계약 진화에서 필드 번호와 필드 이름의 중요성은 무엇이며, 이 구별이 자동화된 테스트 전략에 어떤 영향을 미칩니까?
많은 후보자들은 필드 이름이 인간이 읽을 수 있는 JSON 표현이나 디버깅 도구에서 나타나기 때문에 필드 이름에 집중합니다. 이진 직렬화에서는 필드 번호(태그)만 중요한 식별자입니다. "customer_id"를 "user_id"로 이름을 바꾸는 것은 이진 호환성을 유지하지만 태그 1을 태그 2로 변경하면 기존 소비자에게 영향을 미칩니다. 따라서 자동화된 테스트는 이름의 안정성보다 태그의 불변성을 우선시해야 합니다. 전략에는 필드 태그 변형을 위한 buf 파괴 규칙을 구현하고, 역직렬화된 개체가 아닌 이진 와이어 형식에 대한 주장을 하는 단위 테스트를 작성하며, gRPC 반사 서비스가 버전 간에 일관된 필드 번호를 반환하는지 확인하는 것이 포함됩니다. 또한 테스트는 이름이 중요한 경우(예: Envoy 또는 gRPC-Gateway에서 일반적) JSON 변환 시나리오를 다루어야 하며, REST-to-gRPC 변환 계층에 대한 별도의 검증이 필요합니다.
계약 테스트에서 gRPC 스트리밍 메서드(서버 측, 클라이언트 측, 양방향)와 유니타리 RPC 메서드를 어떻게 테스트합니까?
유니타리 방법은 단일 요청/응답 페이로드를 검증하지만, 스트리밍은 메시지 순서, 흐름 제어(역압), 연결 생명주기 관리와 같은 복잡성을 도입합니다. 서버 측 스트리밍의 경우, 계약 테스트는 소비자가 부분적 스트림 실패를 처리하고 적절한 컨텍스트 취소 전파를 구현하는지 검증해야 합니다. 클라이언트 측 스트리밍의 경우, 테스트는 서버가 메시지를 올바르게 누적하고 스트림 종료(하프 종료) 이벤트를 처리하는지 검증해야 합니다. 양방향 스트리밍은 서로 교차하는 메시지 교환 및 장기 연결에 대한 타임아웃 처리를 테스트해야 합니다. 구현에는 수동 검증을 위한 gRPCurl, 스트림 처리량 부하 테스트를 위한 ghz, 메시지 시퀀스를 기록하기 위한 Pact v4(스트리밍 지원)가 포함됩니다. 놓칠 수 있는 주요 측면에는 스트림이 비정상적으로 종료될 때 리소스 누수 테스트(활성 스트림 수를 보여주는 Prometheus/grpc 클라이언트 메트릭을 통해 검증)와 스트리밍 컨텍스트 전반에 걸쳐 Deadline 전파가 제대로 작동하여 프로덕션에서 멈춘 연결을 방지하는 것이 포함됩니다.