역사: 단일 아키텍처에서 API 변경은 통합 테스트 단계를 통해 관리할 수 있었으나, 마이크로서비스 도입으로 인해 서비스 의존성이 분산되어 단일 깨지는 변화가 수십 개의 하류 소비자에서 연쇄적인 실패를 초래하는 "버전 지옥"이 발생했다. 이로 인해 수동 OpenAPI 검토에서 자동화된 계약 주도 검증 게이트로의 전환이 필요했다.
문제: 전통적인 테스트는 API가 독립적으로 작동하는지 검증하지만, 요청/응답 스키마의 수정이 기존 소비자와의 묵시적 계약을 위반하는지 여부는 감지하지 못한다. 수동 사양 검토는 오류가 발생하기 쉬우며, 수백 개의 상호 의존하는 서비스에 걸쳐 확장할 수 없다. 이로 인해 비활성화된 필드가 여전히 활성 사용 중일 때 제거되어 운영事故가 발생할 수 있다.
솔루션: OpenAPI 차이 분석과 소비자 주도 계약 테스트를 통합한 다층 검증 파이프라인을 구현한다. Optic 또는 Swagger Diff와 같은 도구를 활용하여 변경 사항을 깨지는(필드 제거, 타입 변경) 것과 비깨지는(선택적 추가) 것으로 분류한다. Pact를 통합하여 제공자의 변경이 기록된 소비자의 기대를 충족하는지 확인한다. 파이프라인이 감지된 변경 심각도에 따라 필요한 버전 증가를 계산하고 증가가 불충분할 경우 배포를 거부하도록 의미적 버전 관리 자동화를 시행한다.
validate_api_compatibility: stage: test script: - optic diff openapi.yaml --base main --severity breaking - pact-verifier --provider-app-version $CI_COMMIT_SHA --publish-verification-results - python scripts/check_semver.py --schema-diff-report optic-report.json rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"
우리 팀은 12개의 내부 마이크로서비스와 3개의 외부 은행 파트너를 위한 Payment Gateway API를 유지 관리했다. 3D Secure 2.0 인증 필드를 추가하는 동안, 한 개발자는 비활성화된 transactionReference 문자열 필드를 제거하고 객체 구조로 대체했다.
문제 설명: 변경 사항은 새로운 구조가 데이터를 올바르게 처리했기 때문에 단위 및 통합 테스트를 통과했다. 그러나 세 개의 구식 회계 마이크로서비스는 여전히 평면 문자열 필드를 기대하고 있었다. 수동 OpenAPI 검토는 이 구조적 변경의 파괴적인 성격을 간과했다. 배포 후, 조정 작업이 역직렬화 오류로 실패하여 4시간의 중단을 초래했다.
고려된 다양한 솔루션:
체크리스트가 있는 수동 동료 리뷰: 모든 OpenAPI 변경을 파괴적인 변경 체크리스트를 사용하여 검토하도록 고위 엔지니어에게 요구한다. 이 접근법은 인간 주의에 의존하지만 압박 하에서는 본질적으로 신뢰할 수 없으며, 빠른 배포 주기와 함께 확장할 수 없으며, 숨겨진 소비자 의존성을 고려할 수 없다.
자동화된 JSON 스키마 비교: 구조적 차이를 오류로 플래그 표시하는 기본 차이 도구를 구현한다. 이것은 빠른 피드백을 제공하지만 추가적인 변경(새로운 선택적 필드)을 위반으로 간주하여 과도한 오탐지를 발생시켜 팀이 부담스러운 예외 목록을 유지하게 하고 경고 피로로 인해 경고를 무시하게 만든다.
의미적 버전 관리 게이트와 함께하는 소비자 계약 테스트: 소비자 주도 계약을 위해 Pact를 배포하고 OpenAPI 차이 분석을 위해 Optic CLI를 결합한다. 이는 실제 기록된 소비자 상호작용에 대해 변경 사항을 검증하여 진정으로 파괴적인 수정만 실패를 유발하도록 한다. 자동으로 의미적 버전 상승을 제안하고 비활성화 일정 준수를 유지한다. 단점은 소비자 팀을 온보딩하는 데 필요한 초기 투자와 계약 아티팩트에 대한 저장 오버헤드가 필요하다는 것이다.
선택한 솔루션 및 이유: 우리는 소비자 계약 테스트를 선택했다. 이는 마이크로서비스 아키텍처의 자율 배포 필요성과 연쇄 실패 방지에 부합하기 때문이었다. 수동 검토와는 달리 수평적으로 확장할 수 있다. 기본 차이 도구와는 달리 의미적 영향을 이해한다. 우리는 초기에는 주요 서비스 경로에 대해서만 계약 테스트를 의무화하여 온보딩 비용을 수용했다.
결과: 파괴적인 변경이 향후 8개월 동안 생산 릴리스에서 제거되었다. 배포 빈도가 격주에서 매일로 증가했으며 팀은 자동 게이트를 신뢰하게 되었다. 나중에 동일한 리팩토링을 시도했을 때, Pact 검증이 끊임없이 실패하여 레거시 서비스와의 비호환성을 강조했다.
REST API 검증에서 구문적 파괴적 변경과 의미적 파괴적 변경을 어떻게 구별하나요?
구문적 변경은 필드 제거 또는 타입 변경과 같은 OpenAPI 스키마 차이로 감지할 수 있는 구조적 수정이다. 의미적 변경은 구조를 유지하지만, 선택적 매개변수의 기본값을 변경하거나 반환된 배열의 정렬 순서를 수정하는 것과 같이 동작을 변경한다. 순수 스키마 검증은 의미적 실패를 간과하기 때문에 행동 테스트 또는 계약 테스트 또는 그림자 트래픽 비교를 통해 변경된 비즈니스 논리 출력을 감지해야 한다.
확장-계약 패턴이란 무엇이며, 자동화는 이를 어떻게 시행해야 하나요?
확장-계약 패턴은 새로운 기능을 추가한 다음 소비자를 마이그레이션하고 마지막으로 이전 코드를 제거하는 것을 요구한다(확장, 계약). 자동화는 필드 비활성화 메타데이터를 추적하여 단당일에 제거되면 빌드를 실패시키고, 이전 엔드포인트에서 트래픽이 없음을 검증해야 한다. 이를 통해 소비자가 진정으로 준비되었는지를 보장해야 한다.