API 버전 지정 전략

다양성이 필요한 이유

클라이언트보다 API가 빠르게 변경됩니 Versioning을 사용하면 통합을 깨지 않고 기능을 릴리스하고 오류를 편집하고 변화의 의식을 설정하며 진화를 예측할 수 있습니다. 키: 기본 추가 변경, 전공-파손 전용, 자동 호환성 검사 및 사려 깊은 일몰 정책.

기본 원칙

1. 첨가제 우선: 새로운 옵션 필드/방법/이벤트-OK; 삭제 및 의미 변경-전공.
2. MGC (최소 보증 계약) 는 안정적입니다. 강화-기능을 통한/'? = '를 포함합니다.
3. 관용 독자: 클라이언트는 알려지지 않은 필드를 무시하고 enum 확장을 올바르게 유지합니다.
4. 시맨틱 버전: 'MAJOR. 미노르. 아티팩트, SDK 및 이벤트를위한 PATCH '.
5. 자동화: 스키마-디프, 라인터 및 CDC 테스트는 차단 변경을 차단합니다.

버전을 저장할 위치 (주소 지정 메커니즘)

REST/HTTPNAME

² 버전: '/v1/order '→ 경로가 쉽고 게이트웨이에 편리합니다. 마이너스- 아이디어의 진화를 "모호하게한다".
미디어/헤더: '수락: 응용 프로그램/vnd. 예. 주문. v1 + json '-정확한 형식 제어; 토론하기가 더 어렵습니다.
쿼리 버전: '? 아피 버전 = 1 '-A/B에 편리하지만 캐시/로그에서 쉽게 잃을 수 있습니다.
권장 사항: 메이저 라인 + 기능/기능 플래그 및 사소한 확장을위한 컨텐츠 부정.

gRPC/프로토

패키지/서비스: '패키지 결제. v1; 서비스 PaymentsV1; '- 명시 적 라인.
태그 번호 매기기는 변경되지 않습니다 삭제 된 태그를 재사용할 수 없습니다.
새로운 필드- '선택 사항'; → 새로운 '.v2' 를 깨뜨립니다.

그래프 QL

DM에 명시적인 전공이없는 스키마. @ 더 이상 사용되지 않는 마이그레이션 창을 통한 "실제" 전공은 새로운 엔드 포인트 체계입니다.
제어 복잡성/깊이는 계약의 일부입니다.

이벤트 중심 (Kafka/NATS/Pulsar)

이벤트 이름: '결제. 승인 된. v1 '은 유형의 버전입니다.
호환성 모드 (BACKWARD/FORWARD/FULL) 가있는 스키마 레지스트리 (Avro/JSON 스키마/프로토 타입).
전이 기간 동안 주요 → 이중 방출 'v1' 및 'v2'.

버전 모델 및 변경 정책

시맨틱 버전

메이저-변경 사항 삭제: 필드 삭제/이름 변경, 멤버십 키 변경, 상태의 다른 의미, 검증 강화.
MINOR-첨가제: 새로운 옵션 필드/엔드 포인트/이벤트, 내성 판독기가있는 새로운 enum 값.
PATCH-계약 및 의미를 변경하지 않고 수정합니다.

우울증 및 일몰

더 이상 사용되지 않는 마크 ('더 이상: 참', '@ 더 이상 사용되지 않음'), 일몰 날짜, 대체 및 마이그레이션 가이드를 게시하십시오.
HTTP에서 헤더 '일몰', '우울증'; 이벤트에서-별도의 '.depreca. 통지 '.
삭제 여부를 결정하는 원격 측정 사용.

스타일별 검증 전략

REST

/ v1 ,/v2의 주요 회선.
MINOR: 스키마 확장, '? fields = ',? = '; 안전한 enum 확장.
비 파괴 일관성을위한 ETag/If-Match 및 demempotent POST.
오류 - 안정적인 형식 ('유형', '코드', '추적 _ id').

gRPC

'PaymentsV2. 캡처 '.
오류 상태 및 마감일 의미는 계약의 일부입니다. → 새로운 방법/서비스 변경.
스트리밍: 메시지 순서에 동의하고 미성년자로 변경하지 마십시오.

그래프 QL

필드와 유형을 자유롭게 추가하십 삭제 - '@ 더 이상 사용되지 않음' + 마이그레이션 창을 통해; 큰 재 설계 → 새로운 체계 ('/graphql-v2 ').
내성 및 설명-고객 마이그레이션에 필수적입니다.

이벤트

핵심 대 풍부: 핵심은 안정적이며 근처에 풍부하게 살며 별도로 다양합니다.
파티션 키는 메인 라인 내에서 변경되지 않습니다.
주요 마이그레이션- '이중 방출' + 프로젝션/소비자 마이그레이션.

협상 및 기능 플래그

기능: 클라이언트는 'X-Capabilities: risk _ score, price _ v2' 를 보냅니다. 서버가 확장보기로 응답합니다.
부분 응답을 선호하고 힌트를 제공합니다.
소켓/스트림-지원되는 확장 목록이있는 악수 메시지.

고통없이 주요 버전의 출시

1. RFC/ADR: 전공이 필요한 이유, 파괴, 위험 행렬.
2. 이중 실행: 'v1' 및 'v2' 의 병렬 출시 (이중 이벤트 게시, 2 개의 게이트웨이 라우트, 트래픽 미러링).
3. 마이그레이션 어댑터: 무거운 클라이언트를위한 프록시/프록시.
4. 카나리아: 게이트웨이의 고객 그룹/주제/태그.
5. 일몰 계획: 날짜, 통신, 스탠드, 테스트 데이터, 사용 모니터링.

플랫폼 및 인프라 역할

API 게이트웨이/서비스 메시: 버전, 헤더, 경로 별 라우팅; 버전 당 속도 제한 참조.
스키마 등록 및 카탈로그: 역사가 어려운 사양/체계에 대한 진실의 출처.
CI/CD: линтер달러 (Spectral, Buf), 스키마 디프 (OpenAPI-diff, Buf breaking), CDC (Pact).
관찰: 버전은 로그/트레일/메트릭에 포함되어야합니다.

버전 테스트

PR의 스키마 디프: 블록 파괴.
소비자 주도 계약: 공급자는 실제 소비자 계약에 대해 테스트됩니다.
황금 샘플: 버전에 대한 참조 응답.
E2E 카나리아: p95/p99의 비교, 버전 간 오류 및 타임 아웃.
이벤트 재생: 프로젝션은 불일치없이 v2로 재 조립됩니다.

데이터 및 데이터베이스 마이

REST/gRPC의 경우: 데이터베이스 마이그레이션은 확장 및 계약을 통해 조정됩니다 (열을 추가하여 → 쓰기 → 스위치 읽기 → 이전 삭제).

이벤트: 이중 방출 및 소비자 마이그레이션; 때때로-새로운 프로젝션에 대한 로그를 재생합니다

"큰 폭발" 을하지 마십시오-롤백이있는 단계로 나뉩니다.

보안 관계

버전 당 스코프: v1/v2에 대한 개별 OIDC 스코프/역할.
토큰의 비밀/청구는 계약의 일부입니다. 그들의 변화 = 전공.
PII/PCI-불필요하게 페이로드를 확장하지 마십시오. 최소한의 권한을 가진 새로운 분야.

반 패턴

Swagger-wash: 사양이 업데이트되었으며 서버가 아닙니다 (또는 그 반대).
원형 태그를 재사용하는 것은 조용한 데이터 손상입니다.
전공없이 의미를 변경합니다.
글로벌 '/v2 '"화장품을 위해": 깨는 사실이없는 버전.
일몰/사용 지표를 잊어 버렸습니다. 이전 버전을 안전하게 제거 할 수 없습니다.
다른 전공에 대한 하나의 공통 주제: 주문과 키가 혼합되어 있습니다.

시험판 점검표

• 변경 사항이 추가 적이거나 별도의 주요 회선이 준비됩니다.
• 라이터와 스키마 디프는 녹색입니다 (파손이 크롤링되지 않음).
• 업데이트 된 SDK/예/문서, 호환성 각주.
• 고객에 대한 내성 독자 활성화; 에넘-폴백 테스트.
• 주요 이중 실행 계획, 어댑터, 카나리아, 일몰 날짜 및 메일 링의 경우.
• 메트릭/로그/트레일에는 버전과 세분화가 포함되어 있습니다.
• v1을 비교하기위한 스탠드와 골든 세트가 있습니다.
• 이벤트의 경우 스키마 레지스트리는 BACKWARD/FULL 모드에 있으며 파티션 키는 변경되지 않습니다.

샘플 템플릿

REST (URI + 협상)

경로: '/api/v2/orders/{ id} '

가수: '선호: 항목, 고객', 'X-Capabilities: risk _ score'

비난: '일몰: 2026-06-30', '링크: ; rel = "대체" '

프로토 마이크/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

이벤트

'지불. 캡처. v2 '(핵심) 및' 지불. 풍부합니다. v2 '(세부 사항).
전환 기간 동안 생산자는 'v1' 및 'v2' 로갑니다.

FAQ

'/v2 '가 정확히 언제 필요합니까?
불변/의미론이 변경되면 필드/메소드가 제거되고 식별자 형식, 분할 키, SLA/타이밍이 변경되어 클라이언트가 중단됩니다.

REST에서 명시 적 버전없이 살 수 있습니까?
작은 시스템에만 해당됩니다. 외부 통합의 경우 명시 적 주요 라인이 더 좋습니다.

오래된 버전을 유지하는 데 얼마나 걸립니까?
생태계에 따라 다릅니다. 외부 파트너의 경우 일반적으로 6-12 개월 동안 조기 통지 및 카나리아가 있습니다.

이벤트 버전은 API와 어떻게 다릅니 까?
이벤트 - 추가 전용; 새로운 의미론 = 새로운 유형 '.v2' 및 이중 방출. 파티션 키는 계약의 일부입니다.

결과

검증 전략은 기본 추가 진화, 명확한 주요 라인, 기능 협상, 이중 실행 및 일몰 등 프로세스 및 도구입니다. 자동 호환성 검사, 사용 원격 측정 및 문서 분야를 추가하면 "야간 마이그레이션" 및 예기치 않은 고객 감소없이 API가 빠르게 발전합니다.