API 라이닝 및 정적 분석

1) API를 연결하는 이유

• 호환되지 않는 암시 적 변경 방지
• 통일 상태, 오류, 페이지 매김, 보안;
• 사양을 기계 검증 가능하게 만들고 릴리스를 예측할 수 있습니다.
• 검토 및 온 보딩 시간을 줄입니다.

원칙: "계약은 자동으로 확인됩니다. 녹색 린팅이없는 PR은 유지되지 않습니다. "

2) 연결 시설

1. 계약: OpenAPI/AsyncAPI/GraphQL SDL, Protoguy/Avro/JSON 스키마.
2. 구현: REST/gRPC 펜, 미들웨어, 상태 코드/헤더.
3. 인프라: 보안 헤더, 제한, 캐시 정책.
4. 관련 아티팩트: 예, Postman 컬렉션, 오류 체계.

3) TP API의 기본 규칙 (권장 프로필)

3. 1 표기법 및 탭

JSON 본체의 snake _ case, 경로의 케밥 케이스 또는 균일 한 케밥 케이스/'/v1/... '.
리소스 - 복수: '/v1/payment ', 중첩- '/v1/wallets/{ id }/travesses'.
경로 파람으로 식별 자: '/v1/payment/{ payment _ id} '(유형: 문자열, 형식: uIS).

3. 2 가지 방법 및 상태

'GET' - 200/206; ' POST '- 201 (+' 위치 '), 충돌 - 409; 검증 - 422; 한계 - 429 (+ '재시도 후').
오류는 200을 되돌리지 마십시오. 조건부 쿼리-304 by 'If-None-Match'.

3. 3 오류 (단일 형식)

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"...", "details":[{"field":"amount","reason":"min:1"}] }

필수: '코드', '메시지', 'trace _ id'; 로케일-' 콘텐츠 언어 '를 통해.

3. 4 Pagination/필터

커서 기반: '페이지 _ 사이즈', '페이지 _ 토큰', от봉합사: '다음 _ 페이지 _ 토큰'.
필터 및 정렬-' 매개 변수 '에 문서화 된 화이트리스트.

3. 5 안전

통일 보안 체계: OAuth2/OIDC 스코프 또는 mTLS; 'http' ('https' 만) 을 거부합니다.

민감한 헤더를 반환하지 않습니다. 예제에서 토큰을 마스크하

3. 6 제한 및 치수

제목/신체 제한: 413/414/431; 허용되는 최대 값을 문서화하십시오.

4) 도구 및 생태계

4. 1 OpenAPI

스펙트럼 (JSON/YAML 린트), Redocly linter, oas-diff/openapi-diff (의미 적 diff), 회로도/dredd (진행 중 확인).

4. 2 프로토 타입/gRPC

pu (lint + breaking chesk), 프로톨 린트, SDK 생성기; 분석을위한 영지.

4. 3 그래프 QL

graphql-schema-linter, graphql-inspector (파괴).

4. 코드 라이터 및 SAST 4 개

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API 냄새 및 보안 템플릿).

5) 규칙 예: Spectral/Redocly

5. 1 스펙트럼 (예: '스펙트럼. yaml ')

yaml extends: ["spectral:oas", "spectral:asyncapi"]
rules:
openapi-tags: off info-contact: error no-http: error path-kebab-case:
description: "Paths must be kebab-case"
given: "$.paths[]~"
severity: error then:
function: pattern functionOptions: { match: "^/(?:[a-z0-9]+(?--[a-z0-9]+)/?)+$" }
response-error-schema:
description: "Error responses must use standard schema"
given: "$.paths[][].responses[?(@property >= '400')]"
then:
field: "content.application/json.schema.$ref"
function: truthy id-as-uuid:
given: "$..parameters[?(@.name =~ /.id$/i)]"
then:
field: schema.format function: enumeration functionOptions: { values: ["uuid"] }

5. 2 Redocly (조각 .redocly. yaml ')

yaml apis:
main: openapi.yaml lint:
extends:
- recommended rules:
no-ambiguous-paths: error operation-2xx-only: off operation-success-response:
severity: error where:
subject: response filterInParentKeys: ["200","201","204"]
operation-security-defined: error no-plain-http: error

6) 프로토 타입/gRPC: 프로파일

6. 1 '파이. 샘 '

yaml version: v2 modules:
- path: proto lint:
use:
- DEFAULT except:
- PACKAGE_VERSION_SUFFIX # используем v1 в package breaking:
use:
- WIRE_JSON deps: []

• 필드 번호를 재사용하지 마십시오. 삭제 - '예약'.
• 새 필드- '선택적' 또는 기본값으로; 유형/의미를 변경하지 마십시오.

7) 시맨틱 디프 및 "파괴" 변경

7. 1 HTTPNAME

• 필드 유형/필수 변경
• 상태/경로/매개 변수 삭제
• 에넘/범위 좁아짐;
• (PHP 3 = 3.0.6, PHP 4)

• 선택한 필드 추가
• 행복한 경로에 영향을 미치지 않는 새로운 상태 (예: 문서화 된 '422')
• 에넘 확장.

7. 2 gRPC/프로토 타입

'예약 '/번호 변경없이 필드를 삭제-중단

입력 변경 (int32 → 문자열) -파괴

옵션으로 새 태그를 추가하는 것이 일반적으로 안전합니다.

8) 계약 및 코드 연결

일관성은 두 가지 스레드로 제공됩니다

1. 계약 → 코드: SDK/서버 스터브 생성, 테스트의 부정적인 예.
2. 계약 → 코드: 사양 테스트, 상태/헤더의 자동 확인.

• '오류! = nil' 을 반환하지 않습니다.
• 쓰기 결제 경로에 대한 필수 'Idempotency-Key';
• 로그에 토큰을 마스킹합니다.

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

pre-commit: spectral lint, redocly lint
PR gate:  openapi-diff (base..PR), buf breaking-check, graphql-inspector build:   schemathesis smoke, unit/integration linters (ESLint/golangci-lint)
release:  publish contracts (artifact/broker), sign & tag

다음과 같은 경우 PR이 떨어

기본 규칙이 위반되었습니다 (상태/보안/오류)

파손이 있습니다.
매개 변수의 예/설명은 없습니다.

10) 규칙 카탈로그 (조직의 템플릿)

식별자 및 유형

'_ id' - '문자열', '형식: uIS'.
머니 필드- '문자열 '/' 10 진수'; 통화-ISO-4217.

실수

통합 제도 (§ 3 참조) 3), 코드: '400/401/403/404/409/422/429/5xx'.
항상 'trace _ id'; ' 429/503의 재시도 후.

페이지 네이션

커서 만; (PHP 3 = 3.0.6, PHP 4)

안전

모든 작업- '보안' 블록; '스코프' 가 설명되어 있습니다.
아니요 'http:' 링크; TLS 1. 2+.

캐시/dedempotency

게트- 'ETag/Last-Modified'; 쓰기 - 'Idempotency-Key' (해당되는 경우).

문서

'요약', '설명', 요청/응답의 예 (유효).

11) 자동 점검의 예

11. 1 필수 보안 헤더 검증 (스펙트럼)

yaml security-headers:
given: "$.paths[][].responses['200'].headers"
then:
function: truthy

11. 2 openapi-diff (의사 CI 단계)

openapi-diff --fail-on-incompatible base.yaml pr.yaml

11. 3 개의 파괴 점검

buf breaking --against '.git#branch=main'

12) 계약 품질의 관찰 가능성

메트릭: 오류 연결, 수정 시간, 위반 시도 횟수, 규칙에 따른 "부채" 와의 PR 공유.
대시 보드: 통합 오류 체계로의 마이그레이션 진행, 예제 적용 범위, 버전 안정성.

13) 안티 패턴

"Doc" 은 코드 → 비 동기화와 별도로 존재합니다. 계약을 서비스에 가깝게 유지하고 버전이있는 아티팩트를 릴리스하십시오.
손으로 만 라인터. 단단한 PR 게이트가 필요합니다.
임의의 예 (비 결정적) -체크 플레이크.
부정적인 예와 오류 코드가 없습니다.
각 서비스에 대한 오류 체계의 재발 명.
체크 무시 ("눈으로" 태그 변경).

14) iGaming/Finance의 세부 사항

통화 필드-고정 스케일/반올림; 플로트 금지.
필수 헤더 'X-Tenant', 'X-Region' 및 'traceparent' 추적.
결제 쓰기 핸들: 'Idempotency-Key', 'Redure-After' 및 올바른 409/201 의미론을 확인하십시오.
Webhooks PSP/KYC: HMAC/mTLS는 'securitySchemes' 에 설명되어 있습니다. 재생 방지 ('X-Timestamp', 창).
지역 제한 및 오류 현지화 ('컨텐츠 언어').

15) Prod 준비 점검표

• 스펙트럼/재 도크 프로파일은 사전 커밋 및 PR 게이트로 설계 및 연결됩니다.
• 단일 오류 패턴 및 상태-커밋 및 확인.
• openapi-diff/GraphQL Inspector/guy-차단 차단 변경.
• 요청/응답의 예는 유효합니다. 페이지 매김/필터 문서화.
• SecuritySchemes 및 scope가 채워집니다. http 링크가 없습니다.
• 프로토 타입: 삭제 된 태그에 '예약'; 새로운 필드-선택 사항.
• Semgrep/코드 린터 활성화; 로그에 비밀을 숨기십시오.
• CI는 계약 아티팩트 및 린팅 보고서를 게시합니다.
• 플레이 북: 브레이킹 디파 (롤백, 핫픽스, 통합 업체에 알림) 에서 작동하는 방법.

16) TL; DR

자동 계약 린팅 (Spectral/Redocly, GraphQL Inspector) 및 시맨틱 diff를 구현하고 단일 오류/상태/페이지/보안 체계를 수정하고 PR 게이트를 연결하고 계약을 아티팩트로 게시하십시오. 모든 파손은 브레이크 라이트입니다. 돈/지불의 경우-특별 규칙 (dedempotency, 'Readed-After', HMAC/mTLS).