API 계약 테스트

1) 계약 테스트 이유

이 계약은 경로/메소드, 헤더, 바디 스키마, 상태, 오류 의미론 및 제약 조건과 같은 고객의 기대와 제공자 약속을 포착합니다. 목표는 E2E없이 통합 및 출시 버전을 안전하게 출시하기 전에 호환되지 않는 변경 사항을 포착하는 것입니다.

2) 접근

소비자 주도 계약 (CDC): 고객이 기대치를 형성합니다 (협정 및 유사체). 공급자는 정기적으로 확인합니다.
사양: 단일 진실의 원천으로서의 계약 (OpenAPI/Protoquy/GraphQL SDL); 테스트는 사양에 대한 구현을 검증합니다.
이벤트 기반: 메시지 스키마 (Avro/JSON 스키마/프로토 타입) + 브로커/레지스트리 호환성 규칙.

3) TP/REST 사양 스트림

1. 계약: OpenAPI 3. x (다이어그램, 예, 코드).
2. 린트 및 통계 분석: 스타일, 필요한 필드, 균일 한 코드.
3. 구현 검증: Anti-OpenAPI 테스트 생성기 (schemathesis/Dredd 접근 방식) + 수동 네거티브.
4. 스냅 샷: 샘플 응답, ETag 시맨틱, demempotency 헤더 캡처.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (협정 접근)

1. 소비자는 테스트를 작성하고 계약 파일 (예상) 을 생성합니다.

2. 중개인에 게시 (아티팩트).

3. CI의 공급자는 서비스 (또는 계약 랙) 를 높이고 계약을 확인합니다.

4. 브로커는 Can-i-distruction 호환성 매트릭스를 계산합니다.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) gRPC/프로토 타입 계약

계약은 패키지/서비스 버전으로 '.proto' 입니다.
호환성: 태그를 재사용하지 말고 옵션이있는 새 태그 만 추가하고 사용 된 필드를 삭제하지 마십시오. 예비 번호.
테스트: 서버/클라이언트 찌르기 생성, 자동 생성 케이스 렌탈 + 네거티브 (알 수없는 필드, 크기 제한).

6) 이벤트 계약 (Kafka/NATS/...)

확인: Avro/JSON 스키마/프로토콜 스키마 레지스트리.
호환성 정책은 'BACKWARD' (종종 충분) 또는 'FULL' 입니다.
생산자 테스트: 체계에 대한 메시지 검증; 소비자 테스트: 기존 버전과 새 버전을 허용합니다.
불변량: dempotence 키, 순서/반복성, 중복 제거 의미론.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) 호환성 및 버전

역 호환 (권장 최소): 선택한 필드를 추가하고 기존 필드를 끊지 마십시오.
전진 호환: 소비자는 알 수없는 필드를 무시합니다.
전체: 둘 다.
버전: '경로 (/v1)', '수락: 응용 프로그램/vnd. 브랜드. v2 + json ',' 프로토 패키지 v2 '.
편차 정책: 출력 창 (예: 90 일), 경고 헤더/이벤트.

8) 부정적이고 실수도 계약입니다

표준화 코드: 400/401/403/404/409/422/429/5xx, 필수 필드 '코드', '메시지', 'trace _ id'.
크기/제한은 계약의 일부입니다 (413/414/431).
이념성: 반복 동작 (409 대 201 같은 ID).

헤딩: 429/503의 'Redue-After', 'Idempotency-Key', 'Content-Language' 등

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) 계약에 의해 관리되는 데이터

예를 들어 라이브, CI에서 검증되었습니다.
CDC의 정착물은 최소한의 결정 론적입니다.
데이터 생성 - 숫자/날짜에 대한 속성 기반; 그러나 스냅 샷의 안정성을 깨뜨리지 않습니다.

10) CI/CD의 파이프 라인 (참조)

1. 린/유효성: OpenAPI/Proto/Avro ('유효성', 스타일-лине).
2. 게시: 아티팩트로 계약 (브로커/레지스트리).
3. 검증: 공급자는 CDC 패킷/사양 테스트를 실행합니다.
4. 배치 가능 게이트: 녹색 매트릭스 없이는 릴리스가 허용되지 않습니다.
5. Diff는 변경 사항이 의미 론적 diff임을 확인합니다.
6. 보고서: JUnit/HTM, 위반/정의 목록.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) 도구 (작업 클래스 별)

린트/유효성 검사기: openapi-linters, 원형-lint, avro-tools.
CDC: Pact 가족/중개인, Spring Cloud Contract, Hoverfly (HTP 레코드/재생).
사양 러너: 회로도/Dredd와 유사한 접근 방식, Postman 테스트 + JSON 스키마.
Diff: 시맨틱-디프 OpenAPI/Proto/Avro (변경 변경 사항 감지).
컨테이너: 공급자/계약 데스크를 올리는 테스트 컨테이너.

12) 안티 패턴

코드 → 비 동기화와 별도로 "특수 도크". 서비스 근처에 계약을 유지하십시오.
업데이트 중 계약 → 취약성 대신 타사 서비스의 Moki.
→ 플레이크 체계에 바인딩되지 않은 랜덤 응답/생성.

버전없이 유형/필수 필드 변경

알림/감소가없는 조용한 확장.

부정적인 계약 및 오류 코드가 없습니다

13) iGaming/Finance의 세부 사항

머니 필드를 공식화하십시오: '금액' -10 진수, 통화-ISO-4217, 불변 금액.
지불/웹 후크 계약: HMAC/mTLS, 재생 방지 ('X-Timestamp' 창), demempotency, 'React-After'.
지역/테넌트: 필수 헤더 'X-Tenant/X- 지역', 메시지 현지화.
이벤트: 변경되지 않은 로그 (감사), 중복 제거 키, 배송 보증 (적어도 한 번 + idempotent 처리기).

14) 테스트의 "골격" 의 예

14. 1 Schemathesis 스타일 (의사)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 사양 러너로 2 우편 배달부

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 CDC 제공 업체 검증 (의사)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Prod 준비 점검표

• 저장소의 계약, CI는 아티팩트를 검증하고 게시합니다.
• 중요한 통합을 위해 CDC 활성화; 브로커/매트릭스 "ca-i-district" 작업.
• 호환성 정책 (잘/gRPC/이벤트) 문서화; 자동 시맨틱 디프.
• 부정적인 계약: 오류, 크기 제한, demempotence, 'Readed-After'.
• 테스트 데이터는 결정 론적입니다. 예제의 스냅 샷이 지원됩니다.
• 검증 및 삭제: 마감일, 알림, 헤더.
• 이벤트의 경우-Schema Registry 및 호환성 모드; 생산자/소비자는 두 가지 버전을 모두 테스트하
• 아티팩트: JUnit/HTM, diff/cerfess reports, 호환성 매트릭스.
• 사건 절차: 빠른 계약 롤백/기능 플래그, 통합 업체에 알림.

16) TL; DR

계약에 대한 기대치를 캡처하고 자동으로 실행하십시오: 고객 기대에 대한 CDC, 구현에 맞는 사양 테스트, 이벤트에 대한 스키마 등록. 엄격한 호환성 정책과 부정적인 계약 (오류, 한계, demotence) 을 유지하십시오. 녹색으로 배포 할 수있는 매트릭스와 시맨틱 디프가 없으면 변경을 중단하지 않고는 해제 할 수 없습니다.