GH GambleHub

API 버전 지정 및 계약 호환성

TL; DR

호환성은 운이 아니라 훈련입니다. 명확한 버전 정책 (SemVer) 을 유지하고 수학 ("중단", 그렇지 않은 것), 계약 테스트, 스키마 레지스터 및 일몰 절차를 변경하십시오. 돈과 규정 준수를 위해-vN을 사용한 엄격한 REST/gRPC, UI 집계를 위해-진화론 적 GraphQL은 '@ 더 이상 사용되지 않습니다'. 항상: 카나리아 트래픽, 이전 버전과의 호환성 한 번의 릴리스주기, 마이그레이션 가이드, 현장 원격 측정.

1) 기본 개념과 목표

BC (Backwards-호환): 오래된 클라이언트는 새 서버에 적합합니다.
전달 호환 (FC): 새로운 클라이언트는 이전 서버에 적합합니다 (제한적).
와이어 호환성: "와이어" 의 형식이 깨지지 않습니다 (특히 gRPC/프로토 타입에 중요).
SemVer: 'MAJOR. 미노르. PATCH '-계약을 위반하여 MAJOR를 인상하십시오.

목표는 파괴적인 변화를 최소화하고 예측 가능한 마이그레이션 창을 제공하는 것입

2) 매트릭스 변경: 할 수있는 것과 할 수없는 것

변화의 유형RESTgRPC (프로토)그래프 QL
필드 추가 (응답)+ 안전+ 안전 (새 필드 번호)+ 안전
옵션 필드 추가 (요청)서버가 없음을 허용하는 경우+ 안전+ 안전
필드 삭제- 깨기-번호를 재사용하는 경우'@ 더 이상 사용되지 않음' 이후의 글꼴 → 창 뒤에 삭제
필드 이름 바꾸기- 깨기- (이름 변경, 번호 유지)별칭/두 시간 필드
형식/형식 변경- 깨기-와이어 타입의 변경시-회로를 끊는 경우
상태/오류 의미 변경- 깨기-코드/부품-계약-고객 중단
Enum의 순서 변경가치에 의하여) 는 안전하다에넘 번호가 안정적인 경우+ 이름 안전
새로운 엔드 포인트/메소드+ 안전+ 안전+ 안전
페이지 매김/필터 변경주의 깊게, 옵션 추가+ 새로운 필드를 통해+ 새로운 인수를 통해

3) 다양한 API 스타일에 대한 정책

3. 1 REST

URI의 버전 ('/v1/... ') 또는 도메인 (' api-v1. '). 헤더 버전 - 내부 케이스에만 해당합니다.
다이어그램에서 새 필드 (확인, 오래된 필드) 를 '더 이상 사용되지 않음' 으로 표시하고 한 번 이상 사이클 동안 남겨 두십시오.
상태/오류: 코드 및 구조 오류를 변경하지 마십시오. 코드/오류. 메시지/오류. 세부 사항 '.
이념은 변하지 않습니다. 'Idempotency-Key' 를 사용한 안전한 'POST' 를 '행동 적으로 다른' 도전으로 바꾸지 마십시오.

3. 2 gRPC/프로토 타입

필드 번호는 신성합니다. 삭제 된 번호를 재사용하지 말고 '예약' 으로 표시하십시오.
새로운 옵션/repit 필드 만 추가하면됩니다. "하드 필수" -' 필요하지 않은 '검증을 통해.
버전 패키지: '결제. v1 ',' 지불. v2 '.
서비스 호환성: 새로운 RPC → 새로운 방법; 우리는 예전의 행동을 바꾸지 않습니다.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 그래프 QL

v2없는 진화: 필드/유형 추가; 삭제 - 창 발표와 함께 '@ 더 이상 사용되지 않음 (이유)' 을 통해.
지속적인 쿼리: 공공 고객의 경우 화이트리스트의 쿼리를 사용하십시오. 호환성을 제어하기가 더 쉽습니다.
필드 레벨 저작자 및 원격 측정: 삭제하기 전에 실제로 사용되는 필드를 알고 있습니다.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 웹 후크 4 개

경로 버전 ('/webhooks/v1/payment ') 및 고정 이벤트 엔벨로프 (' 이벤트 _ id ',' 유형 ',' ts ',' data ').
서명/NMAS를 변경하지 않은 상태로 유지하십 플래그가있는 옵션으로 새로운 알고리즘.
확장 - 새로운 필드 데이터를 통해서만. '및' 헤더 '-이전 헤더를 삭제하지 않고.

4) 게이트웨이 API 및 버전 라우팅

규칙 기반 라우팅: 접두사 '/v1 ', 헤더' X-Api-Version ', 도메인.
Shadow/Canary: 새 버전의 프로덕션 트래픽 중 일부를 "그림자로" 반영하고 답변을 비교하십시오.
버전 당 요율/쿼타: 마이그레이션 중에 오래된 클라이언트를 보호합니다.

REST 용 선셋 헤더:
  • '일몰: ' - 버전 종료 날짜
  • 'Deprencation: True' -버전이 더 이상 사용되지 않습니다
  • '링크: ; rel = "deprencation" '-변경/마이그레이션 가이드
예 (Nginx 스타일, 단순화): 
nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) 계획 등록 및 계약

OpenAPI/JSON Schema 계정 REST; 프로토 타입 디스크립터는 gRPC; SDL 레지스트리

CI 검사: PR의 라인터 + "파괴 변경 확인".
소비자 주도 계약 (CDC): 소비자 테스트 (협정/아날로그) -눈에 띄지 않는 휴식으로부터 보호합니다.
Changelog: 기계 판독 가능 (예: 'CHANELOG. 레지스트리의 md '+ 릴리스 노트).

6) 필드의 진화: 경험의 규칙

ID/키: 새 필드 '_ v2' 와 전환 기간이 없으면 형식 (Utillint) 을 변경하지 마십시오.
시간/통화: UTC-8601/epoch 및 m액 _ minor + 통화를 유지하십시오. 확장하지 마십시오 (페니/센트).
Enum: 값 추가-확인; 오래된 것의 의미를 바꾸지 마십시오. REST의 경우 인트가 아닌 문자열 값을 제공하십시오.
페이지 기반: 커서 기반보다 안정적입니다. 커서의 의미를 변경하지 마십시오.

7) 고갈 및 "일몰" 절차

1. 발표 (T-90/60): 변경 로그, 파트너에게 우편, 'Deprencation/Sunset' 헤드 라인.
2. 중복주기: V1과 V2는 병렬로 작동합니다. V1에는 응답/로그에 경고가 표시됩니다.
3. 사용 원격 측정: 누가 V1이라고 부르나요? 포인트 연락처.
4. V1 동결: 버그 수정/기능 없음.
5. Sunset-410 Gone 또는 마이그레이션 명령어 블록 페이지.

8) 통증이없는 릴리스: 전략 마련

파란색/녹색 또는 가중 라우팅: 1-5-25-50-100% 트래픽.
호환성 창: 외부 API의 경우 최소 1-2 개의 사소한 릴리스, 더 자주 6-12 개월.
업그레이드하지 않고 새로운 논리 필드/분기를 포함하는 기능 플래그.
읽기/쓰기 분할: 먼저 새 필드를 읽을 수있는 지원을 추가 한 다음 쓰기 시작하십시오.

9) 상호 운용성 테스트 (실습 제품군)

이전 버전의 응답에 대한 황금 테스트.
회로의 Diff 테스트: CI에서 파손되지 않습니다.
재생 생산은 V2 (그림자) 를 준비 할 때 실행됩니다.
백/포워드 스크립트: 이전 서버의 새 클라이언트 및 그 반대 (FC가 유효한 경우).
웹 후크의 계약 테스트: 서명, 형식, 시간 검증.

10) 버전 지정 프로세스의 측정 및 SLO

마지막 MINOR 고객의% (일몰 전 대상 80% 이상).
릴리스 당 호환성/사용할 수없는 오류 (대상 0).
레거시 호출의 공유 (일몰으로 감소).
클라이언트 마이그레이션 시간 (중간/p95).
버전 간 대기 시간/회귀 델타 (기본보다 나쁘지 않음).

11) 인공물 예

OpenAPI (조각, 필드 박탈): 
yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }
프로토 (예약 및 v2 패킷): 
proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }
GraphQL (고갈): 
graphql type Query { payout(id: ID!): Payout }

12) 인접한 채널 수정

SDK/CLI: SemVer + API 버전 종속성, README에 규정 된 호환성.
이벤트/스트림 (WS/Kafka): '엔벨로프 버전. 버전 '; 새로운 속성-선택 사항; 디드 업 및 재개는 버전간에 동일하게 작동합니다.
보고/CSB: 파일 이름/헤더의 버전; 오른쪽에 열을 추가하면 순서/유형이 변경되지 않습니다.

13) 거버넌스 및 역할

계약 소유자 (도메인 소유자), Steward API (규칙 및 린터), 릴리스 관리자 (일몰/통신).

비즈니스 정당화, 마이그레이션 계획, 아티팩트, 날짜 등 변경 사항을 해결하기위한 LF 프

통합 API 디렉토리: 다이어그램, 버전, 일몰 달력, 연락처가 표시됩니다.

14) 반 패턴

"조용한" 중단: 버전없이 상태/오류/필드 유형을 변경하십시오.
원형 번호 재사용-재생 및 오래된 고객을 파괴합니다.
현장 원격 측정이없는 그래프 QL-터치 제거.
글로벌 v2 총-포인트 진화 대신 메가 미그레이션.
공개 API에 대한 쿼리 매개 변수의 버전은 명백하지 않고 취약한 체계입니다.
마이그레이션 가이드와 예는 없습니다. 파트너가 멈추고 마감일이 중단됩니다.

15) 새 버전의 확인 목록 릴리스

  • 업데이트 된 스키마 (OpenAPI/Proto/SDL), 라인터 및 파손 점검이 통과되었습니다.
  • 통합 및 계약 테스트 (CDC) 가 추가되었습니다.
  • SDK/샘플 코드/마이그레이션 가이드 및 Changelog 준비.
  • 우울증/일몰 활성화 (이전 버전) + 페이지 마이그레이션 방법.
  • 지표를 비교 한 카나리아/그림자 계획, 경고 및 대시 보드.
  • 합의 된 기간 동안 후진 호환성이 유지됩니다.
  • 롤백 계획 및 위험 매트릭스가 동의했습니다.

요약

안정적인 API는 "한 번이 아니라 모두를위한 프로세스입니다. "규칙에 따라 라이브: SemVer + 애드전용 진화 + 회로 레지스터 + 계약 테스트 + 일몰 절차. 별도의 스타일 (REST/gRPC/GraphQL) 및 해당 정책, 게이트웨이 API로의 경로 버전, 카나리아 출시, 효과를 측정합니다. 이러한 방식으로 "놀라움을 깨기" 를 피하고 파트너 통합을 가속화하며 통화 및 규정 준수에 중요한 영역에 대한 예측 가능성을 유지하십

Contact

문의하기

질문이나 지원이 필요하시면 언제든지 연락하십시오.우리는 항상 도울 준비가 되어 있습니다!

Telegram
@Gamble_GC
통합 시작

Email — 필수. Telegram 또는 WhatsApp — 선택 사항.

이름 선택 사항
Email 선택 사항
제목 선택 사항
메시지 선택 사항
Telegram 선택 사항
@
Telegram을 입력하시면 Email과 함께 Telegram에서도 답변드립니다.
WhatsApp 선택 사항
형식: +국가 코드 + 번호 (예: +82XXXXXXXXX).

버튼을 클릭하면 데이터 처리에 동의하는 것으로 간주됩니다.