API 계약 호환성

계약 호환성

계약 호환성은 기존 통합을 위반하지 않고 API가 발전하는 기능입니다. 성장하는 시스템에서 API는 클라이언트 코드보다 더 자주 변경됩니다 호환성을 사용하면 "큰 움직임" 을 정렬하지 않고도 기능을 반복적으로 릴리스 할 수 있습니

핵심 아이디어: 계약은 기본이며 변경 사항은 호환성 규칙에 따라 수행되며 자동으로 확인됩니다.

기본 개념

계약-공식 인터페이스 사양: 리소스/메소드/이벤트, 데이터 스키마, 오류 코드, 제한, SLA, 보안 요구 사항.
공급자 - API의 소유자. 소비자-클라이언트/통합.

호환성:

뒤로: 새로운 공급 업체는 오래된 소비자와 협력합니다.
앞으로: 기존 공급 업체는 새로운 소비자와 협력합니다 (일반적으로 "허용 독자" 가 달성 함).
전체: 앞뒤로 (가장 강력한 옵션) 가 관찰됩니다.
첨가제-기존 요소를 깨지 않고 선택적 요소를 추가하십시오.

정확한 정책

시맨틱 버전 (권장):

메이저-변경 사항 위반 (새 API 라인이 릴리스 된 경우에만: '/v2 ',' 서비스. v2 ').
MINOR - 추가 변경 (새로운 선택 필드/방법).
PATCH-계약을 변경하지 않고 수정합니다.
거부 정책: 쓸모없는 요소 선언, 지원 창 (일몰), 헤더/메타 데이터의 경고, 인출 계획.

안전 대 위험한 변화

보안 (일반적으로 역 호환)

JSON/Protoguy/Avro에 옵션 필드를 추가하십시오.
새 엔드 포인트/방법/이벤트를 추가하십시오.

소비자가 알려지지 않은 값에 견딜 수있는 경우 새로운 값으로 enum을 확장합니

최소값을 조이지 않고 한계 (예: 'maxItems') 를 올립니다.

정확한 기본값으로 무효화할 수 있는 추

설명/예제 텍스트 편집

위험한 (호환성 중단)

필드 이름 바꾸기/삭제, 유형 변경 또는 필수 사항

상태 코드/오류 의미론 변경 (예: '200', '204' 또는 '404' 가 됨).
식별자 형식을 변경합니다.
버전없이 검증 강화 (더 엄격한 최소/패턴).
gRPC 스트림/이벤트에서 순서와 구조를 변경합니다.
새 필드에 대한 태그 번호를 다시 사용하십시오.

상호 작용 스타일별 <> 상호 운용성

REST/SHT + JSON 스키마

첨가제: 새로운 필드를 '선택적 '/' 무효화' 로 표시합니다.
클라이언트의 관용적 독자: 알 수없는 필드를 무시하십시오. 질서에 의존하지 않습니다.
버전: 전공-도중에 ('/v2 ') 또는 미디어 유형 (' 응용 프로그램/vnd. 예. v2 + json ').
ETag/If-Match: 경주없이 안전한 업데이트를 위해.
오류: 단일 형식 ('유형', '코드', '제목', '세부 사항', '추적 _ id') 은 메이저없이 '코드' 값을 변경하지 않습니다.

Pagination: 커서는 오프셋보다 선호됩니다. (PHP 3 = 3.0.6, PHP 4)

gRPC/프로토 타입

태그 번호 매기기는 변경되지 않습니다 삭제된 태그를 재사용할 수 없습니다.
새 필드는 서버에서 합리적인 기본값으로 '선택 사항 '/' 반복' 입니다.
스트리밍 -RPC에서 순서 및 필수 메시지를 변경하지 마십시오.
오류 상태는 안정적입니다 ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' 등). 새로운 의미론 → 새로운 버전의 방법/서비스.

이벤트 중심 (Kafka/NATS/Pulsar) + Avro/JSON 스키마

명명 이벤트: '도메인. 행동. v {major} '.
새로운 필드는 선택 사항입니 코어와 농축 ('농축') 을 분리하십시오.
스키마 레지스터: 테마/이벤트의 호환성 규칙 (BACKWARD/FORWARD/FULL).
enum 확장은 소비자 측 내성 독자에게 유효합니다.
골재 = 파괴 변경에 대한 파티션/주문 키 변경.

그래프 QL

필드/유형을 추가하는 것이 안전합니다. @ 더 이상 사용되지 않음 및 마이그레이션 창을 통해서만 삭제/이름을 변경하십시오.
전공없이 유형/무효를 변경하지 마십시오.
제어 복잡성/깊이-한계는 계약의 일부입니다.

지속 가능한 진화 패턴

첨가제 우선: 파손없이 확장하십시오.
기능 협상: 클라이언트는 서버 조정 (헤더/매개 변수/계약) 을 지원한다고보고합니다.
계약 경계: MGC (최소 보증 계약) 및 별도의 확장 (역 피라미드 모델) 을 수정합니다.

기본적으로 관용: 클라이언트는 불필요하게 무시하고 알 수없는 enum (폴백) 값을 올바르게 처리합

이중 쓰기/이중 방출: 주요 변경 사항의 경우 'v1' 및 'v2' 를 한동안 병렬로 릴리스하십시오.
일몰 헤더/이벤트: 버전이 제거 될 때 미리 알림.

거버넌스 및 자동화

API 라이터:

OpenAPI/Spectral: 이름 지정, 페이지 지정, 오류 코드, 필드 형식.
버프/프로토: 태그 재사용 금지, 패킷 표기법.
AsyncAPI/Schema Registry: CI 수준 스키마 호환성.
계약 카탈로그 (SSOT): 확산 기록이있는 중앙 집중식 스키마/버전 레지스터.
API 길드: 규칙, 템플릿 및 검토 변경 사항을 채택하는 길드/위원회.
관리 변경: RFC/ADR, 릴리스 노트, 마이그레이션 가이드.

호환성 테스트

CI의 스키마 디프: 블록 브레이킹 케이크 (OpenAPI-diff, Buf 브레이킹, SR 호환성).
소비자 주도 계약 (CDC): 협정/유사-공급 업체 대 소비자 별 계약.
황금 샘플: 회귀를위한 참조 쿼리/응답 및 이벤트.
E2E 카나리아: 트래픽/개별 Consummer 그룹의 지분으로 배포.
혼돈/대기 시간: 시간 초과/재조정 확인-대기 시간 -SLO 변경은 계약 변경으로 간주됩니다.

마이그레이션 및 제거

1. 선언 해제: 항목을 표시하고 일몰 용어 및 대안을 지정하십시오.
2. 호환성 기간 유지: 이중 쓰기/이중 방출, 브리지, 어댑터.
3. 원격 측정 수집: 누가 오래된 것을 사용합니까?
4. 커뮤니케이션: 메일 링, 릴리스 노트, 테스트 스탠드.
5. 제거: 창이 만료 된 후 - 고정 릴리스로 제거.

변화의 예

REST

그것은:

json
{ "id":"p1", "status":"authorized" }

Became (첨가제, 안전):

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

알 수없는 필드를 무시하는 고객은 깨지지 않습니다.

프로토 타입

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

이벤트

'지불. 승인 된. v1 '(코어) +' 결제. 풍부합니다. v1 '(농축). 비판적 경로 소비자는 핵심을 읽고 농축에 의존하지 않습니다.

안티 패턴

Swagger-wash: 공식적으로 사양이 있지만 서비스 동작과 상충됩니다.
스텔스 차단: 새 버전과 마이그레이션 창없이 유형/상태/형식이 변경되었습니다.
공개 계약으로서의 원시 CDC 이벤트: 유출 된 DB 체계, 진화가 불가능합니다.
하드 클라이언트: 알 수없는 필드/값에서 떨어짐; 관용적 인 독자가 없습니다.
원형 태그 재사용: 조용한 데이터 손상.
"비 계약" 으로서의 대기 시간: p95가 예기치 않게 길어졌습니다. 소비자는 타임 아웃이 중단됩니다.

호환성 체크리스트 (병합 전)

변경 사항은 추가 (또는 주요 버전 준비) 입니다.
Linters/diff 검사가 통과되면 호환성 규칙이 녹색입니다.
오류/코드/상태는 의미를 변경하지 않았습니다.
Enum은 오래된 값을 금지하지 않고 확장되었습니다. 고객-내성.
MGC의 경계는 변경되지 않습니다.
샘플/문서/SDK를 업데이트했습니다.
주요-이중 쓰기/이중 방출 계획, 일몰 날짜, comm-plan.
CDC/Golden/E2E 테스트 통과.

FAQ

이전과 호환성이 어떻게 다릅니 까?
뒤로-새 서버는 오래된 클라이언트를 깨뜨리지 않습니다 앞으로-새로운 클라이언트는 기존 서버에서 중단되지 않습니다 (허용 가능한 리더 및 깔끔한 기본값을 통해).

'/v2 '는 언제합니까?
불변/의미가 변경되면 필드/메소드가 삭제되고 새로운 보안 모델이 필요합니다. 새 라인을 시작하는 것이 더 쉽고 정직합니다.

Schema Registry/linter없이 살 수 있습니까?
이론적으로-예, 실제로-이것들은 빈번한 회귀와 "숨겨진" 고장입니다. 자동화는 돈을 지불합니다.

Enum을 확장 할 수 있습니까?
예, 클라이언트가 알려지지 않은 값을 올바르게 처리하면 (폴백/무시 그렇지 않으면-전공.

합계

계약 호환성은 규칙 + 규칙 + 자동화입니다. 추가 설계, 버전 변경, 허용 가능한 리더 적용, 자동 확인 디프 및 CDC, 계획 해제. 이런 식으로 API는 빠르게 발전 할 수 있으며 통합은 안정적으로 유지 될 수 있습니