마이크로서비스 Contract Testing 가이드

도입

마이크로서비스에서 가장 흔한 장애 원인은 네트워크가 아니라 인터페이스 불일치다. 상대 서비스가 사소하게 응답 포맷을 바꿔도 소비자 입장에서는 즉시 장애가 된다. 이 글은 소비자 주도 계약 테스트를 실무에 정착시키는 방법을 소개한다.

마이크로서비스 Contract Testing 가이드 커버 — Wikimedia Commons 기반 무료 이미지

문제 정의

통합 테스트만으로는 서비스 간 계약 회귀를 빠르게 잡기 어렵다.

문서와 실제 응답이 달라도 배포 전에 탐지되지 않는다.
하위 호환 정책이 없어서 필드 추가/삭제 시 장애가 발생한다.
서비스 팀 간 배포 순서 의존성이 커져 릴리즈가 병목된다.

계약 테스트의 핵심은 책임 이동이다. 소비자가 기대하는 계약을 명시하고 제공자가 이를 검증하는 구조가 가장 효과적이다.

핵심 개념

관점	설계 기준	검증 포인트
계약 작성	소비자 기대 명세	테스트 케이스 충실도
제공자 검증	Provider CI에서 pact 검증	배포 전 실패 탐지율
버전 정책	하위 호환 우선	breaking change 건수
협업	계약 변경 리뷰 프로세스	팀 간 충돌 감소

계약 테스트는 QA 추가가 아니라 배포 체계 개선이다. 팀 간 의존성을 줄이고 독립 배포를 가능하게 한다.

코드 예시 1: 소비자 계약 정의

import { PactV3, MatchersV3 } from "@pact-foundation/pact";

const provider = new PactV3({ consumer: "web-app", provider: "user-service" });

provider
  .given("user 1001 exists")
  .uponReceiving("a request for user profile")
  .withRequest({ method: "GET", path: "/users/1001" })
  .willRespondWith({
    status: 200,
    body: {
      id: MatchersV3.string("1001"),
      name: MatchersV3.string("moriya"),
      role: MatchersV3.string("admin"),
    },
  });

코드 예시 2: Provider 검증 파이프라인

#!/usr/bin/env bash
set -euo pipefail

pact-broker can-i-deploy \
  --pacticipant user-service \
  --version "$GIT_SHA" \
  --to-environment production

npm run test:contract:provider

아키텍처 흐름

Mermaid diagram rendering...

트레이드오프

계약 테스트를 도입하면 초기 설정 비용이 있지만 통합 장애를 크게 줄인다.
소비자 주도 모델은 명확하지만 팀 간 합의 프로세스를 추가로 요구한다.
검증 게이트를 강화하면 배포 속도는 줄 수 있으나 릴리즈 안정성이 높아진다.

정리

마이크로서비스의 독립 배포를 원한다면 계약 테스트가 필수다. 소비자 기대를 명문화하고 제공자 CI에서 검증하면 인터페이스 회귀를 배포 전에 차단할 수 있다.

이미지 출처

Cover: source link
License: CC BY-SA 4.0 / Author: Zeljko.filipin
Note: Wikimedia Commons 무료 라이선스 이미지를 다운로드 후 1600px 기준 JPG로 최적화했습니다.

도입