피드로 돌아가기
Dev.toBackend
원문 읽기
Implicit Contract 제거를 통한 배포 후 API Breaking Change 원천 차단
Why Your API Contract Breaks in Production (And How to Fix It in the Spec)
AI 요약
Context
구두 합의와 Slack 기반의 암묵적 계약(Implicit Contract)으로 인한 런타임 오류 빈번 발생. 구현 후 문서화하는 전통적 방식의 한계로 인해 하위 호환성 판단 오류 및 소비자 사이드 장애 유발.
Technical Solution
- Spec-first 워크플로우 도입을 통한 Define → Review → Build → Validate 순서의 설계 프로세스 확립
- Error Taxonomy 정의를 통한 400(Invalid Input), 409(Business Block), 422(State Prevent), 503(Transient) 구분으로 소비자 측 Retry 전략 최적화
- Idempotency Key(UUID) 및 유효 윈도우(24h) 명시를 통한 상태 변경 API의 안정적 재시도 메커니즘 설계
- Breaking Change 기준(필드 삭제, 타입 변경, 필수 필드 추가 등)을 명문화하여 엔지니어의 주관적 판단 배제
- OpenAPI Spec 기반의 oasdiff/openapi-diff를 CI 파이프라인에 통합하여 Breaking Change 감지 시 빌드 즉시 실패 처리
- Consumer-Driven Contract Testing(Pact 등) 적용으로 생산자와 소비자 간 기대 동작 동기화
실천 포인트
- 모든 신규 엔드포인트 설계 시 Error Taxonomy와 Idempotency 여부를 Spec에 명시했는가? - 필드 이름 변경이나 타입 수정 시 Version Bump 기준에 따라 처리했는가? - CI 단계에서 OpenAPI Diff 도구를 통해 하위 호환성 검증 자동화가 이루어지고 있는가? - 구현 전 소비자 팀과의 Contract Review 세션을 통해 필수/선택 필드 합의를 마쳤는가?