후방 호환성
이전 버전과의 호환성
이전 호환성-시스템이 업데이트 될 때 기존 클라이언트/소비자를 수락하고 올바르게 처리하는 시스템의 속성. 간단하게: 새로운 버전의 서비스/이벤트를 릴리스하고 기존 통합은 계속 변경되지 않습니다.
열쇠: 계약을 위반하지 마십시오. 모든 진화는 이미 발표 된 것을 재건하는 것이 아니라 추가하는 것입니다.
기본 원칙
1. 첨가제 우선
새로운 필드/메소드/이벤트가 선택적으로 추가됩니다 존재하는 것은 제거되지 않으며 의미를 변경하지 않습니다
2. 최소 보증 계약 (MGC)
스크립트의 의미를 잃지 않는 필드/작업 세트 인 커널을 정의하십시오. 핵심은 안정적입니다. 다른 모든 것은 확장입니다.
3. 관용 독자
고객은 알 수없는 필드를 무시하고 새 enum (폴백) 값을 올바르게 처리합니다.
4. 버전 정책
변경 사항 위반-주요 회선 ('/v2 ',' 지불. v2 ',' 이벤트. v2 '). 미성년자-첨가제.
5. 관찰 가능성-계약의 일부
클라이언트 버전, 형식, 기능 플래그는 로그/트랙 및 메트릭으로 표시됩니다. 이를 통해 마이그레이션을 관리 할 수 있습니다.
안전 대 위험한 변화
일반적으로 안전 (BC-OK)
선택한 필드 (JSON/Avro/Proto '옵션 '/' nullable') 를 추가합니다.
새로운 엔드 포인트/메소드/이벤트를 추가하
추가 값이있는 Enum 확장 (내약성 판독기 포함).
검증 약화 (최대화, 대체 형식 추가).
의미없는 헤더/메타 데이터를 추가하십시오.
위험한 (깨기)
필드 삭제/이름 변경, 기존 필드의 유형 또는 필수 변경
상태/오류 코드 의미론 변경.
다른 필드에 프로토 태그를 재사용하십시오.
이벤트 분할 키를 변경합니다 (집계 순서를 나눕니다).
SLA/타임 아웃을 강화하여 오래된 고객이 떨어지기 시작했습니다.
상호 작용 스타일별
REST/SHT + JSON
첨가제: 새로운 필드- '선택', 서버에는 이전 클라이언트의 필드가 필요하지 않습니다.
버전: 전공-운송 중 ('/v2 ') 또는 미디어 유형; 미성년자-확장을 통해 및 '? = '/' 를 포함합니까? fields = '.
오류: 균일 한 형식; 전공없이 코드/의미를 변경하지 마십시오.
ETag/If-Match: 경주없이 안전한 업데이트를 위해.
이념성: POST를위한 'Idempotency-Key' - 오래된 고객은 퇴각에 미치는 영향을 두 배로 늘리지 않습니다.
gRPC/프로토 타입
태그는 변경되지 않습니다. 삭제된 태그를 재사용할 수 없습니다.
새로운 필드- '선택 '/' 반복'; 기본 값은 이전 코드에서 올바르게 처리됩니다.
스트리밍: 미성년자 내에서 메시지의 순서/의무를 변경하지 마십시오.
오류-안정적인 상태 세트; 새로운 의미론 → 새로운 방법/서비스 ('.v2').
이벤트 중심 (Kafka/NATS/Pulsar) + Avro/JSON/Proto
명명: '도메인. 행동. v {major} '.
코어 vs 농축: 코어 안정; 농축 - 개별 유형/테마 ('농축').
스키마 호환성 모드: 더 자주 BACKWARD; CI는 호환되지 않는 변경 사항을 차단합니다
파티셔닝: 키 (예: 'payment _ id') - 계약의 일부; 그것을 바꾸십시오-깨기.
그래프 QL
필드/유형 추가-OK; '@ underled' 및 마이그레이션 창을 통해 삭제/이름을 변경하십시오.
메이저없이 "nullable → nulable" 을 올리지 마십시오.
모니터 복잡성/깊이-한계 변경 = 계약 변경.
BC를 보존하는 데 도움이되는 <> 패턴
역 피라미드 모델: 코어를 안정화하고 선택적으로 확장하십시오.
기능 협상: 클라이언트 보고서 지원 기능 ('X-Capabilities '/handshake), 서버 조정.
이중 실행/이중 방출: 마이그레이션 중에 'v1' 과 'v2' 를 동시에 유지하십시오.
어댑터: 프록시/게이트웨이는 "무거운" 클라이언트에 대한 'v1 ² v2' 요청을 변환합니다.
확장 및 계약 (DB 용): 먼저 새 것을 추가하고 쓰기/읽기 시작한 다음 이전 것을 삭제하십시오.
거버넌스 및 프로세스
1. 계약 카탈로그 (Schema Registry): 호환성 정책이있는 단일 진실 소스.
2. CI/CD의 라이터 및 diff 검사: OpenAPI-diff, Buf-breaking, Avro/JSON Schema 호환성 검사.
3. CDC/소비자 주도 계약: 공급자는 실제 소비자 계약에 대해 테스트됩니다.
4. 황금 샘플: 회귀를위한 참조 쿼리/응답/이벤트.
5. 관리 변경: 속보, 일몰 계획, 커뮤니케이션에 대한 RFC/ADR.
이전 버전의 제거 및 제거
더 이상 사용되지 않는 마크 ('@ 더 이상 사용되지 않음', 설명, 헤더 'Deprencation', 'Sunset').
마이그레이션 창: 사전 발표 된 날짜, 테스트 벤치, 코드 예.
사용 원격 측정: 누가 'v1' 에 있습니까? 버전 별 세그먼트 메트릭/로그.
트래픽이 0으로 이중으로 실행 된 다음 삭제하십시오.
관찰 가능성 및 운영 지표
버전 별 요청/메시지 비율.
릴리스 후 구형 클라이언트의 오류/타임 아웃 공유
호환되지 않는 페이로드의 비율 (게이트웨이/스트림 필터의 체계에 의한 검증).
소비자 마이그레이션 지연 (얼마나 많은 사람들이 'v1' 을 듣는가).
후진 호환성 테스트
Schema-diff: 실패하십시오.рNL이/이름 변경/유형 변경을 제거/변경합니다.
계약 테스트: 기존 SDK/클라이언트는 새로운 구현과 경쟁합니다.
E2E 카나리아: 새 버전으로의 이전 트래픽 중 일부, p95/p99 비교, 코드, 배송.
이벤트 재생: 프로젝션은 불일치없이 이전 로그에서 새로운 논리로 수집됩니다.
결함 주입: 지연/부분 응답-오래된 클라이언트는 떨어지지 않습니다.
예
REST (첨가제)
그것은:json
{ "id": "p1", "status": "authorized" }json
{ "id": "p1", "status": "authorized", "risk_score": 0. 12 }'risk _ score' 를 무시하고 오래된 고객은 계속 작동합니다.
프로토 타입 (태그)
proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2이벤트 (핵심 + 강화)
'지불. 승인 된. v1 '- 커널 (최소 사실).
'지불. 풍부합니다. v1 '- 부품; 핵심 소비자는 농축에 의존하지 않습니다.
안티 패턴
Swagger-wash: 구성표가 업데이트되었지만 서비스는 이전 방식으로 (또는 그 반대로) 동작합니다.
숨겨진 휴식 시간: 버전없이 필드/상태의 의미를 변경했습니다.
원형 태그의 재사용: "조용한" 데이터 손상.
열심히 일하는 고객: 익숙하지 않은 분야/enum에 속합니다. 관용적 인 독자가 없습니다.
메가 엔드 포인트: 올인원-모든 변경 사항이 잠재적 스크랩이됩니다.
시험판 점검표
- 변화는 추가 적입니다. 핵 (MGC) 은 손대지 않았습니다.
- Linters/diff 점검이 통과되었습니다. 깨는 깃발이 없습니다.
- 클라이언트 SDK가 업데이트되었습니다 (또는 추가 확장에 필요하지 않음).
- 고객을위한 내성 독자 활성화; 에넘 폴록이 확인되었습니다.
- 메트릭/로그에는 버전 및 기능 플래그가 포함되어 있습니다.
- 잠재적 인 파손의 경우 '/v2 ', 이중 실행 및 일몰 계획이 있습니다.
- 문서/예제가 업데이트되었으며 황금 세트가 있습니다.
FAQ
앞뒤로-차이점은 무엇입니까?
뒤로-새로운 서버는 이전 클라이언트와 협력합니다. 앞으로-새로운 클라이언트는 기존 서버에서 올바르게 작동합니다 (허용 가능한 리더 및 깔끔한 기본 전체 원-전체 호환성.
큰 변화를 위해 항상 '/v2 '를해야합니까?
예, 불변/유형/키/의미가 깨지면. 그렇지 않으면 선을 유지하고 추가 적으로 진화하십시오.
에넘은 어떻습니까?
이전 값의 의미를 변경하지 않고 새 값을 추가하십시오. 고객은 알 수없는 값으로 대체해야합니다.
이미 "파손" 했다면 어떨까요?
이중 실행, 통신 및 마이그레이션 가이드가 포함 된 롤백, 핫 픽스 어댑터, 'v2' 릴리스.
합계
뒤로 호환성은 진화의 원칙입니다. 커널을 안정화시키고, 추가 적으로 확장하고, 허용 가능한 리더를 구현하고, 자동화 된 점검을 자동화하고, 의식적인 비난을 유지하십시오. 이렇게하면 고객이 "보이지 않는" 변화의 잔해에 빠지지 않고 플랫폼을 빠르게 개발할 수 있습니다.