API 호환성 및 업데이트

1) 호환성 기본

첨가제 우선: 오래된 필드/엔드 포인트, 새로운 enum 값을 깨지 않고 새 필드를 추가하십시오.
안정적인 계약: "사양 작업에서 약속 된 것"; 문서화 된 행동.
뒤로> 앞으로: 이전 호환성 우선 순위; 내성 독자를 통해 전진이 허용됩니다.
문서는 기본입니다. 진실의 유일한 원천은 구성표의 레지스트리 버전 (OpenAPI/AsyncAPI/Proto) 입니다.
명백한 진화: 속보 - 새로운 주요 버전과 마이그레이션 가이드를 통해서만.

2) 변화의 분류

2. 1 호환 가능 (MINOR/PATCH)

선택한 필드/헤더, 새 엔드 포인트, 기본값으로 쿼리 매개 변수를 추가합니

(PHP 3 = 3.0.6, PHP 4)

클라이언트가 "알 수 없음" (허용 리더) 을 무시하면 enum 값을 추가하십시오.

2. 2 모호한 (행동)

기본값 변경, 정렬 순서, 얇은 타임 아웃, 할당량-비즈니스 로직을 "파괴" 할 수 있습니다. RFC + 발표 및 카나리아가 필요합니다.

2. 3 속보 (MAJOR)

필드 이름 바꾸기/삭제, 유형/형식 변경, 오류 코드 교체, 계약/인증 체계의 역 비 호환성.

3) 정책 수정

전략: '경로 버전' ('/v1 ', '/v2').
사소한/패치: "추가, 깨지지 마십시오".
데이트 헤더 (옵션): 소프트 증분 변경을위한 'X-API-Version-Day'.
미디어 유형 (Op.): '수락: 응용 프로그램/vnd. acme. 미세 과립을위한 v1 + json '.

4) 우울증과 일몰

4. 커뮤니케이션 헤더 1 개

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 철회 명령 2 개

1. 포털/메일 링리스트/SDK 릴리스 메모 발표.
2. 경고 창은 90-180 일 이상입니다.
3. 입양 대시 보드의 상태.
4. 일몰 후-합의 된 경우 유예 기간 동안 410 Gone 또는 "읽기 전용" 모드.

5) 버전의 마이그레이션 및 공존

보고서와의 전환 및 조정에서 이중 쓰기/이중 읽기.

어댑터 (임시): 기존 페이로드 → 새로운 체계의 게이트웨이 변환; 어댑터 수명이 제한되어 있습니다

SDK 도움말: 감소 경고 (프로세스 당 1 회) 와 함께 두 버전을 모두 지원하는 릴리스.
기능 플래그: 키/테넌트 목록에 따라 새로운 의미론이 포함됩니다.

6) 앞뒤로 호환성

6. 1 뒤로 (오래된 클라이언트의 새 서버)

형식/필수 형식을 변경하지 마십시오.

새로운 필드는 선택 사항 일뿐입니

(PHP 3 = 3.0.6, PHP 4)

6. 2 Forward (신규 클라이언트 기존 서버)

'OPTIONS '/'/버전' 을 통해 기능을 확인하십시오.
유예 행동: 클라이언트는 누락 된 기능에 견뎌야합니다.

7) 계약 및 자동 점검

레지스트리: 스키마 버전 저장; PR 발굴 → 깨기/깨지 않는 보고서.
라이터: 이름/유형, demotency, pagination, 안정적인 코드.
CDC (Consumer-Driven Contracts): 공급 업체의 CI (Pact 및 유사체) 에서 통합 테스트.
게이트: '주요 범프 '/RFC없이 중단 될 때 PR이 차단됩니다.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) 카나리아 확장 및 역전

카나리아: 트래픽의 10% → 25% → 50% → 100%; SLO 열화에 대한 자동 롤백 (5xx/latency/429).
베타 키: 허용리스트별로 새 버전에 액세스하십시오.
방출 동결: 연소 중 오류 예산.
수락 분석: 새 버전의 트래픽/클라이언트 공유, 마이그레이션 시간.

9) 호환성 세부 사항: 오류, 페이지 매김, demmpotence

9. 오류 1 개

기존 스크립트에서 보기 상태를 변경하지 마십시오.
'오류 _ 코드' - 안정; 새 코드 만 추가합니다.
'응용 프로그램/문제 + json' 은 단일 형식입니다.

9. 2 Pagination

이전 '오프셋/한계' 가 지원되는 경우 커서/키셋 = MINOR로 전환하십시오.

(PHP 3 = 3.0.6, PHP 4)

9. 3 이념성

충돌시 'Idempotency-Key' + '409 IDEMP _ REPLAY' 를 작성하십시오.
이주는 demempotency의 의미를 변경해서는 안됩니다.

10) 게이트웨이 변환 (적절한 경우)

지도 v1 → v2 필드, 오류 정규화, 날짜/돈 형식 변환.
가드 레일: 변형은 투명하고 논리적입니다. 파괴를 숨기지 말고 시간 제한 브리지로 사용하십시오.

11) 커뮤니케이션 및 포털

Changelog ('추가/변경/더 이상 사용되지 않음/제거/고정 됨').

버전 카드: 상태 (베타/GA/더 이상 사용되지 않음), 일몰 날짜, 가이드 링크

알림 웹 후크: '비난. 알림 ',' 버전. ',' 계획을 발표했습니다. 변경 '.
SDK 릴리스 노트 + 포털 배너.

12) 성공 지표

입양률 v2 (요청/클라이언트 당).
후방 컴파트 사건.
릴리스 전/후 오류 믹스 (4xx/5xx/429 공유).
입양 시간 중앙값.
지원로드 (티켓/주).
서비스 비용.

13) 템플릿 및 예

13. 버전 제목 및 감소 1 개

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 버전 정책 (YAML 조각)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 OpenAPI 필드 추가 호환 가능

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) 릴리스 체크리스트 (MINOR/MAJOR)

미노르

• DIFF: 깨지지 않는 린터 그린
• 문서/SDK 업데이트 (예/코덱스)
• 카나리아 + 자동 SLO 롤백
• Comm Plan, 포털 페이지
• 입양 및 오류 대시 보드

메이저

• RFC/ADR, 일몰 날짜 및 이하 90 창 -180 일
• v1 v2 브리지 및 마이그레이션 가이드
• 이중 쓰기/읽기 및 조정
• API + 경고가 모두있는 SDK
• 키 적분기가있는 파일럿

15) 구현 계획 (3 회 반복)

1. 재단 (2 주):

CI의 체계, 상인방 및 자동 디프 등록; 호환성 정책; 'Deprencation/Sunset' 타이틀.

2. 관리 릴리스 (3-4 주):

카나리아, 기능 플래그, SLO 경고; 버전 포털; SDK는 2 개의 지점을 지원하여 릴리스합니다.

3. 자동화 및 스케일 (연속):

CI의 소비자에 대한 CDC 테스트, 채택 추세, 자동 알림 및 알림에 대한 일몰 예측.

16) 미니 -FAQ

전공없이 필드 유형을 변경할 수 있습니까?
아니요, 그렇지 않습니다. "stroka → chislo" 조차도 깨지고 있습니다. 새 필드를 입력하면 오래된 필드가 제거됩니다.

Enum: 값을 추가 할 수 있습니까?
예, 고객이 관용 독자 인 경우. 그렇지 않으면 먼저 경고와 베타.

이전 버전을 얼마나 보유해야합니까?
지금까지 새로운 9% 95% 의 채택이 유지되었습니다. 정책의 마감일을 수정하십시오.

합계

API 호환성은 추가 접근 방식, 공식 체계 및 디프, 카나리아 릴리스, 명확한 감소 및 관리 마이그레이션과 같은 분야입니다. 변경 정책을 통합하고, 수표 및 통신을 자동화하고, 채택을 측정하며, 업데이트로 인해 고객 파괴가 중단되고, 신뢰성을 잃지 않으면 서 진화 속도가 빨라집니다.