앞으로 호환성
순방향 호환성
순방향 호환성은 시스템이 원래 설계된 것보다 최신 클라이언트 또는 데이터와 올바르게 작동 할 수있는 기능입니다. 간단합니다. 새 클라이언트가 출시 될 때 이전 서버가 중단되지 않습니다. 오래된 소비자는 새로운 메시지를 보게되면 넘어지지 않습니다.
앞으로는 책임 방향으로 이전 시스템이 이전 클라이언트를 지원할 때 이전 호환성과 다릅니다. 우리는 전체 생태계를 완전히 업그레이드하지 않고 미래의 확장을 "생존" 하는 방식으로 프로토콜과 클라이언트를 설계합니다
기본 원칙
1. 관용 독자 및 내성 작가
독자는 알 수없는 필드/헤더를 무시하고 올바른 폴백으로 새 에넘 값을 허용합니다.
작성자는 서버가 지원되는 기능 (기능) 으로 명시 적으로 선언하지 않은 것을 보내지 않습니다.
2. 역량 협상
악수 단계에서 명시 적 기능 교환 (기능/버전/미디어 유형). 클라이언트는 서버 응답에 대한 동작을 조정합니다.
3. 기본 저하
새로운 기능은 선택 사항으로 간주됩니다. 서버/소비자가 지원하지 않으면 스크립트는 여전히 유용한 최소 (MGC) 로 끝납니다.
4. 안정적인 핵심 (MGC)
최소 보증 계약은 변경되지 않습니다. 혁신은 확장으로 계속됩니다.
5. 프로토콜의 일부로 오류 계약
예측 가능한 코드/이유 ("지원되지 않는 기능", "미디어 유형을 알 수 없음") 를 사용하면 클라이언트가 자동으로 지원되는 모드로 롤백 할 수 있습니다.
6. 놀라움없는 버전
주요 노선이 분리되었습니다 사소한 확장에는 서버/소비자 업그레이드가 필요하지 않습니다.
중요한 곳
통합이 오래 지속되는 공개 API (파트너, 모바일 애플리케이션의 SDK).
많은 독립 소비자가있는 이벤트 플랫폼.
백엔드보다 느리게 업데이트되는 모바일 클라이언트
장치 차량의 일부가 거의 깜박이지 않는 Edge/IoT.
스타일별 구현 패턴
REST/HTT
협상:- 매개 변수가있는 '수락 '/미디어 유형 (' 응용 프로그램/vnd. 예. 차수 + json; v = 1; 프로필 = 위험 ').
- '선호: 포함 =... '선택적 블록의 경우.
- 제목 'X- 기능: 위험 _ 점수, 항목 _ details _ v2'.
- 서버가 기능을 확인한 경우에만 (OPTIONS/desc/lead endpoint를 통해) 기본 형식의 확장으로 요청을 보냅니다.
- '415/406/501' 이 자동으로 지원되는 형식/방법으로 롤백되면.
- 서버 응답: 알 수없는 매개 변수-무시; 추가 필드가 허용됩니다. 안정적인 오류 형식 ('타입/코드/디테일/트레이스 _ id').
gRPC/프로토 타입
안정적인 서비스: 새로운 방법/필드-첨가제; 이전 서버는 알 수없는 요청 필드를 조용히 무시합니다
기능 검색: 'GetCapabilities ()' 메소드는 기능/제한 목록을 반환합니다. 클라이언트는 서버가 선언하지 않는 한 v2 방법을 호출하지 않습니다.
스트리밍: 최소 메시지 세트의 순서를 수정합니다. 이전 클라이언트가 무시하는 확장/유형으로 새로운 "프레임" 을 표시하십시오
그래프 QL
전진 친화적 인: 새로운 필드/유형이 서버에 나타납니다. 오래된 클라이언트는 단순히 요청하지 않습니다.
Guesses는 금지되어 있습니다. 클라이언트는 체계 (내성/코도겐) 를 유지하고 알 수없는 지침/변수를 보내지 않아야합니다.
분해: 서버가 사용자 정의/기능 지침을 모르는 경우 클라이언트는 요청없이 요청을 작성합니다.
이벤트 중심 (Kafka/NATS/Pulsar, Avro/JSON/Proto)
레지스트리에서 체계의 FORWARD 호환성: 오래된 소비자는 새 체계로 작성된 메시지를 읽을 수 있습니다.
채무 불이행이있는 추가 분야: 새로운 생산자는 오래된 소비자를 깰 수 없습니다.
핵심 대 농축: 커널은 동일하게 유지되며 새로운 정보는 '강화' 또는 선택적 필드로 게시됩니다.
디자인 관행
1. 최소 요청 계약 (MGC)
수술에는 모든 서버가 수년 동안 지원할 "좁은 목" 이 있어야합니다.
2. 계약 수준의 기능 플래그
'risk _ score', 'pricing _ v2', 'strong _ idempotency' 라는 명명 된 기능으로 기능을 설명하십시오. 클라이언트에는 명시 적으로 포함
3. "지원되지 않음" 에 대한 명시 적 오류 코드
TP: '501 구현되지 않음', '415 지원되지 않는 미디어 유형',
gRPC: 'UNIMPLEMENTED '/' FAILED _ PRECONDITION'.
이벤트: 'reason = 지원되지 않는 _ feature' 가있는 DLQ 경로.
4. 주문/전체 목록에 의존하지 마십시오
클라이언트는 새로운 enum 값, 새로운 필드 없음 및 "추가" 속성에 대한 준비가되어 있어야합니다.
5. 안정적인 식별자 및 형식
라인 내에서 ID/파티션 키의 형식을 변경하지 마십시오. 이는 리더 측면에서 진행됩니다.
6. "기계 판독 가능" 문서
호스트 디스크립터: OpenAPI/AsyncAPI/Proto 디스크립터/GraphQL SDL. 고객은 해당 기능에 대한 지원을 확인할 수 있습니다.
순방향 호환성 테스트
FORWARD/FULL 모드의 스키마 디프: 새로운 스키마는 이전 소비자/서버를 검증합니다.
클라이언트 계약 테스트: 기능이 활성화/비활성화 된 이전 서버에 대해 새 클라이언트가 실행됩니다
황금 요청: 일련의 "새로운" 요청은 "이전" 서버를 통해 실행됩니다. 중요한 오류없이 예상되는 열화.
혼돈/대기 시간: 타임 아웃/리트레이 확인-새 클라이언트는 이전 서버의 최악의 SLA에서 올바르게 생존해야합니다.
카나리아: 일부 새로운 클라이언트는 이전 서버 버전에서 작동합니다. 오류/저하의 원격 측정을 수집합니다.
관찰 가능성 및 운영 지표
지원되지 않는 기능과 자동 롤백이있는 요청/메시지의 비율.
클라이언트 버전 별 배포 (사용자 에이전트/메타 데이터/클레임).
'지원되지 않는 _ 기능' 이있는 DLQ의 'UNIMPLEMENTED/501/415' 오류 및 경로.
분해 시간: MGC 대 "확장 된" 응답의 경우 p95/p99.
스키마 레지스트리의 <> 호환성 모드
FORWARD: 새 항목은 기존 리더와 호환됩니다 (기본값이 필요하고 선택성).
전체: "FORWARD", "BACKWARD; 공공 계약에 편리합니다.
추천: 이벤트-생산자를위한 BACKWARD 및 소비자를위한 FORWARD (허용 가능한 독자를 통해), 외부 API를위한-FULL.
예
REST (기능 + 저하)
1. 클라이언트는 'GET/meta/factures' → '{"risk _ score": 잘못된, "price _ v2": 참}' 를 만듭니다.
2. 'POST/order' 에서 기본 필드를 보냅니다. 서버가 할 수 없기 때문에 'risk _ score' 는 요청하지 않습니다.
3. 실수로 'Prefer: form = risk _ score' 를 보낸 경우 서버는 'risk _ score' 필드 (또는 'Preference-Applied: none') 없이 200으로 응답합니다. 클라이언트는 충돌하지 않습니다.
gRPC (발견)
'GetCapabilities ()' 는 방법 목록/기능을 반환했습니다. '캡처' 를 사용하고 입력을 지원되는보기로 로컬로 변환하는 대신 클라이언트가없는 경우 'CaptureV2' 라고 호출하지 않습니다.
이벤트 (레지스트리의 FORWARD)
생산자는 'risk _ score' 필드를 추가했습니다 (기본값으로 무효화 가능). 옛 소비자는 그를 무시합니다. 논리는 안정적인 커널 필드 만 사용합니다.
안티 패턴
하드 클라이언트: 화이트리스트 필드로 응답을 필터링하고 익숙하지 않은 속성에 해당
암시 적 기능: 클라이언트는 기능을 확인하지 않고 새 매개 변수를 전송하기 시작합니다
라인 → 이전 서버/소비자에서 ID/키 형식을 변경하면 더 이상 새 요청/메시지를 이해할 수 없습니다.
전체 enum 목록에 대한 유선 가정 (기본값없이 전환).
흐름 제어로 로깅: 계약 코드 대신 오류 문자열 구문 분석.
구현 체크리스트
- MGC 정의; 새로운 기능은 선택 사항으로 표시됩니
- 역량 협상 (엔드 포인트/메타 데이터/핸드 셰이크) 이 설명되고 구현됩니다.
- 고객은 익숙하지 않은 필드를 무시하고 새 enum (폴백) 을 올바르게 처리합니다.
- 오류 계약은 "지원되지 않음" 을 예측 가능하게 캡처합니다 (TH/gRPC/Event).
- 스키마 레지스트리는 해당 아티팩트에 대해 FORWARD/FULL로 설정됩니다.
- 자동 테스트: 스키마 디프 (FORWARD), 클라이언트 대 기존 서버 계약 테스트, 카나리아.
- 메트릭: 클라이언트 버전, 기능 오류, 저하율, p95 MGC.
- 문서/SDK는 기능 및 저하 예제 목록을 게시합니다.
FAQ
전진은 실제로 후진과 어떻게 다릅니 까?
뒤로: 새 서버는 오래된 클라이언트를 깨뜨리지 않습니다. 앞으로: 기존 서버는 새로운 클라이언트 (또는 기존 소비자가 새로운 메시지에서) 에서 벗어나지 않습니다. 이상적으로는 전체에 도달합니다.
항상 기능을 입력해야합니까?
동기식 릴리스없이 활발한 진화를 기대한다면 그렇습니다. 수십 개의 주요 노선을 보유하는 것보다 저렴합니다.
보안은 어떻습니까?
새로운 기능에는 별도의 스코프/클레임이 필요합니다. 서버가 지원하지 않으면 클라이언트는 보안을 줄이지 말고 기능을 포기해야합니다.
서버 버전에서 지원을 "추측" 할 수 있습니까?
바람직하지 않습니다. 명시 적으로 (기능) 요청하거나 미디어 유형/구성표를 보는 것이 좋습니다.
합계
앞으로의 상호 운용성은 기회 협상과 안전하게 저하하는 훈련입니다. 안정적인 핵심, 기능 협상, 추가 확장 및 예측 가능한 버그를 통해 새로운 클라이언트 및 데이터를 대량 릴리스 및 야간 마이그레이션없이 이전 서버 및 소비자와 함께 사용할 수 있습니다.