프로토콜 우선 설계

프로토콜 우선

프로토콜 우선은 구성 요소 (서비스, 고객, 외부 파트너) 간의 상호 작용 계약이 구현 전에 설계 및 수정되는 접근 방식입니다. 코드, 스토리지, 인프라 및 문서는 계약의 적용을받으며 계약에서 자동으로 생성되며 그 반대도 마찬가지입니다.

API가 코드의 부산물 인 코드 우선과 달리 프로토콜은 먼저 프로토콜을 기본 아티팩트로 만듭니다. 도메인 개념, 데이터 모델, 상태, 오류, demempotency 의미론, SLO/SLI 및 버전 정책도 소유합니다.

왜 필요합니까?

조직 전체의 인터페이스의 일관성과 예측 가능성.
빠른 온 보딩 (SDK/안정/클라이언트 자동 생성, 균일 한 오류 및 코드).
신뢰할 수있는 진화 (체계의 호환성, 테스트 계약, 명확한 버전 정책).
제품 초점: 코드 작성 전에 동작, SLA 및 UX 통합에 대해 논의합니다.
자동화: CI/CD는 단일 진실 소스에서 아티팩트 (클라이언트, 서버 스터브, 유효성 검사기) 를 수집합니다.
보안 및 준수: 권리, PII 마스킹, 보존 정책이 계약에 명시되어 있습니다.

핵심 접근

1. SSOT (Single Source of Truth) - 기계로 읽을 수있는 사양:

REST: OpenAPI/JSON 스키마.
이벤트 및 스트리밍: AsyncAPI, Avro/JSON 스키마.
RPC: 프로토 파이 (gRPC), 스리 프트, 스미시.
GraphQL: SDL + 지침/정책.
2. 사전 구현 배열: 도메인 용어집, 오류 코드, demempotency 의미론, 마감일, 배상, 중복 제거.
3. 자동 생성: 클라이언트/서버 스터브, 유형, SDK, 테스트 계약, moks, Postman 컬렉션, Terraform/OpenAPI 게이트웨이 설정.
4. 거버넌스: 라인터/정책 (이름 지정, 페이지 지정, 필터, 오류), API 길드를 통한 검토, 주요 버전의 변경 권고.
5. 호환성: "추가 전용" 확산, 의미 적 버전 지정, 카나리아/소비자 중심 테스트에 대한 엄격한 검증.
6. 계약 수준에서의 관찰 가능성: 상관 ID, 오류 모델, 지연 예산은 프로토콜에 설명되어 있습니다.

프로세스의 모습 (골격)

1. 개시: 제품 요약 → 사용자 여행 → API/Protocol PRD (리소스/메소드/이벤트, SLA/SLO, 오류, 한계).
2. 모델링: 초안 사양 (OpenAPI/AsyncAPI/Proto) + 데이터 스키마, 용어 사전.
3. 계약 및 UX 통합: 페이로드 예, 오류 계약, 상태 맵, 버전 지정 규칙.
4. 검토 및 거버넌스: 라인터/표준, 도메인 불변량에 대한 논의, 잠금 MGC (최소 보증 계약).
5. 자동 생성 아티팩트: SDK, 찌르기, 테스트 수정, 인프라 스터브 (게이트웨이, IAM 스코프).
6. 구현 및 계약 테스트: 공급 업체 및 소비자는 CI에서 호환성 검사를받습니다.
7. 관찰 가능성 및 SLO: 상관 ID 추적, 오류 카탈로그, 재 트레이/타임 아웃 예산.
8. 릴리스 및 진화: 부가 우선, 거부 정책, 카나리아, A/B 기능 플래그.

상호 작용 프로토콜 및 스타일

REST/HTT

표준: 리소스 모델, 'GET/POST/PATCH/DELETE', 페이지 매김 (커서), 필터, 정렬.
필드 및 체계: JSON 스키마, 형식 ('데이트 타임', 'uIS'), 불변 (regex/enum/min-max).
오류: 단일 형식 ('유형', '코드', '제목', '세부 사항', '추적 _ id'), HTT 스택에 매핑.
변경 제어: ETag/If-Match, POST 용 demempotent 키, 명시 적 의미론 409/422.

gRPC/RPC

프로토 타입: 삭제 된 필드의 재사용을 허용하지 않는 안정적인 태그 번호 매기기 '옵션'.
계약의 마감일 및 우선 순위; 안정적인 상태 (OK, INVALID _ ARGUMENT, FAILED _ PRECONDITION 등).
스트리밍: 메시지 주문 사양, 역압, 최종 트레일러.

이벤트 중심 (Kafka/NATS/SNS/SQS)

AsyncAPI: 테마/채널, 파티션 키, 중복 키 규칙, 보류, 정확히 한 번 의미론 "vs" 적어도 한 번 "

핵심 이벤트 및 강화: 최소 페이로드 및 확장을 분리합니다. '이벤트 _ 유형 '/' 스키마 _ 버전' 버전.
이념성: '이벤트 _ id', '프로듀서 _ id', 배상 및 중복 제거에 대한 정책.

그래프 QL

계약으로서의 SDL, 탈퇴 지침, 깊이 및 복잡성 제한, 오류 코드/확장 계약.

건축 원칙과의 통합

역 피라미드/중요 경로 우선: 사양에서 MGC (필수 최소), 확장-' 를 강조하십시오 = '/기능을 포함합니다.
포장 도로: 기성품 사양 템플릿 (결제, KYC, 감사, 검색, 파일) + 린터 세트.
API 게이트웨이 및 서비스 메쉬: 계약 기반 정책 (속도 제한, 지정 범위, 재 시도, 회로 차단기).

버전과 진화

• 마이너 = 추가 필드/채널 만.
• 주요 = 변경 중단 (삭제, 이름 변경, 의미 변경).
• 거부 정책: 창, '일몰' 헤더, 알림 이벤트를 지원합니다.
• CDC (Consumer-Driven Contracts): 현재 API가 특정 소비자를 충족한다는 것을 확인합니다.
• 스키마 디렉토리: 이력 및 호환성 규칙 (BACKWARD/FORWARD/FULL) 이있는 스키마 레지스트리/아티팩트 레지스트리.

안전 및 준수

계약의 일부로 인증/인증 (OAuth2/OIDC scopes, mSL, JWT claims).
PII/PCI: 마스킹, 토큰 화 형식, 특수 저장 모드/TTL이있는 필드.
감사 정책: 필요한 속성 ('배우', '주제', '행동', '발생', '추적 _ id').
한도: 속도 제한 헤더, 할당량, 메시지 크기, 마감일.

계약 관찰 가능성

상관/요청 ID: 사양에 필요합니다.
오류 카탈로그 - 해결할 고정 코드 목록 및 SLA.
SLI/SLO: p50/p95 대기 시간, 성공적인 응답 비율, 호환 가능한 이벤트 비율, dempotent 반복 비율.

테스트 및 품질

계약 테스트 (공급자), CI의 스키마 diff, 모의 서버 생성.
황금 샘플: 요청/응답의 참조 예, e2e 비품.
혼돈/대기 시간 분사: 타임 아웃/리트레이 확인, MGC 저장시 확장 저하.

샘플 도메인 템플릿

지불 (REST + 이벤트)

'결제 _ id', '상태 = 승인 된' 으로 'POST/결제' → '201 생성'

이벤트 지불. 승인 된. v1 '(을):' {결제 _ id, 금액, 통화, 방법, 일어났다} '.
확장 결제. 풍부합니다. v1 ': 위험률, 지리, 장치 지문.
오류: '422' (검증), '402' (지불 필요), '409' (중복).
SLA: 인증 커널 이벤트는 2c 지연 p95입니다.

KYC (gRPC + 큐)

RPC 'StartVerification (user _ id)' → 'operation _ id'.
'kyc 주제의 진행 이벤트. 상태. v1 '(' PENDING '→' APPROVED/REJECTED ').
계약은 PII 필드, 유효 기간, 마스킹, 인과 고장 코드를 규정합니다.

감사 (이벤트 전용)

'감사. 기록. v1 '(차량 계정):' 행위자 ',' 주제 ',' 행동 ',' 원인 ',' 추적 _ id '.
농축: IP, 장치, 지오 - 별도의 이벤트/스레드는 커널을 차단하지 않습니다.

도구 및 자동화 (대략적인 스택)

확인: OpenAPI/AsyncAPI/Proto/Avro/GraphQL SDL.
확인: 스펙트럼, OpenAPI Diff, Buf (원형), Confluble SR 호환성 검사.
차이가 있는 사람은 누구인지 알아볼 수 있습니다.
게이트웨이: Kong/Apigee/Azure/GCP GW, 특사.
계약/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
등록: 체계 + Schema Registry/Artifact Registry의 위트 디렉토리.
문서: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

반 패턴

우연히 코드 우선: "컨트롤러에서 먼저 MVP", 사실 사양, 문서와 동작의 불일치.
Swagger-wash: 실제 규칙 (오류, 제한, SLA, 버전) 이없는 공식 OpenAPI.
호환성 중단: 주요 버전없이 제거 된 필드/변경된 유형; 원형 태그 재사용.
페이지 매김/필터가없는 "두꺼운" 응답; demopotency의 부족.
계약 외 보안: 가정/스코프는 위키에 설명되어 있지만 사양에는 설명되어 있지 않습니다.

프로세스 조직과의 관계

API 길드: 표준 관리위원회, 변경 검토, 교육.
설계 문서: 각 API-PRD, ADR (솔루션), SLA, 위험 행렬.
관리 변경: RFC 프로세스, 릴리스 메모, 마이그레이션 가이드, 편차 일정.
포장 도로 및 템플릿: 사양의 서비스 프레임 워크 생성기 (핸들러 스켈레톤, 검증, 로깅).

점검표

시작하기 전에

• PRD와 도메인 용어집이 있습니다.
• 선택된 스타일 (REST/gRPC/Event/GraphQL) 및 스키마 형식.
• MGC, 오류, SLA/SLO, demempotency 규칙이 정의되었습니다.

개발 중

• 사양은 라인터와 검토를 통과합니다.
• SDK/Stable/Fixture 자동 생성이 구성됩니다.
• 계약 테스트 (CDC) 는 CI에 포함됩니다. 스키마-디프는 호환되지 않는 변경 사항을 차단합니다.

출시 전에

• 예제 및 오류 코드가있는 통합 문서.
• 계약 상 관찰 가능: 상관 관계 ID, 오류 카탈로그, SLI 대시 보드.
• 검증 정책 및 비난이 선언됩니다.

FAQ

프로토콜 우선 API와 어떻게 다릅니 까?
종종 용어는 상호 교환 적으로 사용됩니다. 의정서 우선, 이 기사에서는 SLA, 안전 및 관찰 성을 포함한 계약의 엄격함과 모든 스타일 (REST/RPC/Events/GraphQL) 의 적용 범위를 강조합니다.

이것이 개발을 늦출 것인가?
시작은 조금 더 길어질 수 있지만 통합, 안정성 및 병렬 개발 속도 (자동 생성, 안정적인 SDK) 에서 승리합니다.

빠른 실험으로 무엇을해야합니까?
"초안" 버전의 체계 (초안) 를 사용하고 기능 플래그와 샌드 박스를 사용하지만 라인터와 기본 호환성 규칙을 건너 뛰지 마십시오.

합계

프로토콜 우선 설계는 계약을 아키텍처의 중심으로 만듭니다. 우리는 행동을 조정하고, 체계를 수정하고, 생성 및 테스트를 자동화하고, 추가 적으로 발전합니다. 결과적으로, 우리는 규모와 명령의 변화에 대한 예측 가능한 통합, 고속 개발 및 시스템 저항을 얻습니다.