SDK 디자인 및 언어 지원

1) SDK 목표 및 성공 기준

개발자 경험 (DX): 직관적 인 API, 언어 간 균일 한 의미론.
신뢰성: 박스에서 타임 아웃/후퇴/dedempotency.
보안: 비밀, 서명, 응용 프로그램, 프로시 환경과의 호환성.
관찰 가능성: 로그, 메트릭, 언어 표준 도구의 흔적.
경제: 최소 출구/CPU, 효과적인 페이지 매김, 배치.
안정성: 엄격한 반주, 이전 버전과의 호환성, LTS 지점.

2) 건축 원칙

1. 얇은 클라이언트, 강력한 계약: 숨겨진 비즈니스 로직없이 프로토콜 (REST/gRPC) 을 통한 SDK 래퍼.
2. 통합 표면: 동일한 개념 (클라이언트, 요청, 응답, 오류, 페이지 네이터, WebhookVerifier).
3. 기본적으로 안전: 합리적인 타임 아웃, 지수 백오프 + 지터, 반복 보호.
4. 설정 레이어링: ENV → 설정 파일 → 생성자 → 메소드 파라미터.
5. 플러그 가능 전송: TP/gRPC는 분리 가능하며 연결 proksi/Phiden과 호환됩니다.
6. 테스트 가능성: 인터페이스/페이크, 종속성 주입, 레코드 재생.
7. 오류 I18n: 머신 '오류 _ 코드' 는 안정적입니다. 메시지는 현지화 할 수 있습니다.
8. 접근성: 적절한 경우 비동기 변형 (일반적으로 'AsyncClient').
9. 보안 우선: 비밀은 필요한 경우 로그, PII 버전, FIPS 호환 암호화 라이브러리에 속하지 않습니다.

3) 지원 테이블 및 기회 패리티

4) API 기본 표면 (표준 모델)

공통 엔티티

클라이언트: 전송, 키, 리트레이, 원격 측정 후크 구성.
요청/응답: 유형 안전 모델/DTO, 페이지 매김/커서.
오류: '상태', '오류 _ 코드', 'trace _ id', '검색 가능' 이있는 단일 클래스.
페이지 네이터/아이터: 페이지/커서의 게으른 검색.
WebhookVerifier: HMAC/mTLS 확인, '이벤트 _ id' 로 정리.

미니 예 (타입 스크립트)

ts const client = new GambleHubClient({
apiKey: process. env. GH_API_KEY!,
timeoutMs: 10_000,
retries: { max: 5, strategy: "expo-jitter" }
});

const { items, nextCursor } = await client. reports. list({ from, to, cursor });
for await (const report of client. reports. iter({ from, to })) { /... / }

미니 예 (파이썬, async)

py from gamblehub import AsyncClient, WebhookVerifier

client = AsyncClient(api_key=API_KEY, timeout=10, retries={"max":5})
async for user in client. users. iter(updated_after=ts):
...

verifier = WebhookVerifier(secret=WEBHOOK_SECRET)
if verifier. verify(headers, body): ack()

5) 설정 및 실행 시간

ENV: 'GH _ API _ KEY', 'GH _ ENDPOINT', 'GH _ TIMEOUT _ MS', 'TP _ PROXY/HTTPS _ PROXY', 'GH _ REGEON'.
생성자-오버 라이드 ENV.
통화 당 오버라이드: 메소드 레벨 타임 아웃/리트레이.
인증서/키의 경로, 필요한 경우 CA를 고정합니다.
연결 풀: 계속 살아 있음, TH/2, 동시성 제약.

6) 상자에서 안전

비밀: 기록하지 말고 스택 흔적에 숨기십시오. 편집 ".
서명: 웹 후크 용 HMAC, 'X-Key-ID '/키 회전, "두 키" 활성/다음 지원.
이념성: 쓰기 작업을위한 'Idempotency-Key' 의 투명한 설정 (재시작은 안전 함).
RBAC/Scopes: 범위에 대한 편리한 열거/상수.
PII 정책: 로깅을위한 표준 편집 인터페이스.

7) 신뢰성: 타임 아웃, 후퇴, 지원

기본 시간 초과: 10-15 초; 연결 3-5.
Retrai: 5xx/408/429 ('Redure-After' 존중) 의 경우 지수 백오프 + 지터, 재 시도/시간 제한.
회로 차단기: SDK에서 선택 사항 (또는 타사 lib 권장 사항).

이념적 글쓰기: 키별로 자동 반복; 충돌 → '409를 올립니다. IDEMP _ REPLAY '

8) Pagination, 커서 및 스트리밍

커서/반복자: 게으른 무차별 힘, 일시적인 오류에 대한 자동 반복.
키셋 페이지화: 안정적인 순서 '(업데이트 된 _ at, id)'.
역압: 동시 요청 제한; "async-SDK" - 'async for '/' 채널'.
스트리밍 (사용 가능한 경우): '시퀀스' 에 의한 자동 재 연결 및 중복 제거가있는 SSE/WebSocket/gRPC 스트림.

9) 실수와 계약

• 'ApiError' (게 일어 났을 때) (429), 'ValidationError (422)', '세르 베르 오류 (5xx)'.
• 계정: '상태', '오류 _ 코드', '메시지', 'trace _ id', '검색 가능', '세부 사항'.
• 모범 사례: 메시지는 사람이 읽을 수 있고 '오류 _ 코드' 는 안정적입니다.

10) 언어 관용구

타이프 스크립트/JS

페이지 매김을위한 약속 기반 + 생성기; ESM + CJS 패킷.
트리 쉐이킹, 최소 폴리 필, 신호 중단 ('AbortController').

파이썬

동기화 + Async (aiohttp/, Px), 컨텍스트 관리자, 'pydantic' 모델 (또는 데이터 클래스).
바퀴가 있으면 바퀴/마코/창; 프록시/NO _ PROXY 지원.

자바

'완전한 미래' (필요한 경우), '자동 폐쇄 가능', '지속 시간', '집행자'.
HTP 클라이언트: 'java. 그물. http '또는 OkHttp; 로그에 대한 SLF4J.

이동

상황의 맥락. 문맥 ',' http. 클라이언트 '튜닝 된 전송, 테스트 인터페이스.
오류 포장 ('fmt. Errorf ("% w", 실수) '), 센티넬 오류 의미론.

.NET

'HttpClientFactory', 'CancellationToken', 'IAsyncEnumerable <T>'.
폴리 정책 (재 시도/회로 차단기).

... PHP/Ruby (PSR-18, Faraday/Net::: HTT) 등의 경우.

11) 로깅, 메트릭, 추적

로그: 레벨 (ERROR/WARN/INFO/DEBUG), 상관 관계 'trace _ id', 민감한 데이터 비활성화

많은 정보를 제공합니다. '요청', '오류 _ 전체 {상태}', '재시도 _ 카운트', '대기 시간 _ ms', '스로틀드 _ total'.
추적: OpenTelemetry 후크 (API 호출, 종점, 상태, 재 시도 속성에 이르기까지).
디버그 모드: 환경 변수 'GH _ SDK _ DEBUG = 1' - 비밀없이 HTP 헤더 인쇄 및 시간.

12) 문서 및 예

빠른 시작 5 분: 조정, 첫 번째 요청, 페이지 매김, 429 처리.
요리 책: 웹 후크 (서명 확인), dememotent 쓰기, 재생.
API 참조: OpenAPI/Protoqua의 Autogen이지만 "수동" 예제가 있습니다.
스니펫: 인기있는 작업을위한 기성품 코드 (파이썬/TS/Java/Go/.NET).

13) 세대 vs 수동 코딩

결합 된 접근 방식: 인체 공학을위한 코드겐 (모델/클라이언트) + 수동 "펜".
템플릿: 균일 한 메소드 이름 ('생성/가져 오기/목록/업데이트/삭제'), 찌르기. 서명.
리겐 후 "디프 호환성" 확인 (CI-gate).

14) 수정, 호환성 및 우울증

SemVer: 소. 속보-전공 만 해당.
안정성 정책: 사소한 릴리스-필드/메소드를 추가하고 계약을 변경하지 마십시오.
비난: 주석/속성 @ adber/Obsolete, 프로세스 당 한 번 런타임 경고, 90 일 이상 창.
LTS 지점: 크리트 픽스의 백 포트 (새로운 기능 없음).

15) 체인 출시 및 공급

CI/CD: 라인터/포머터, 단위 + 통합, 계약 테스트, e2e 대 샌드 박스.
아티팩트 서명: Sigstore/GPG, 릴리스 체크섬.
출판: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems (변경 로그 및 릴리스 노트 포함).
SemVer 게이트: 공개 API의 호환성을 자동 확인합니다 (예: 'apirestary diff').

16) 테스트 (품질 매트릭스)

단위: 모델, 직렬화, 검증, 배상/타임 아웃.
계약: OpenAPI/프로토 타입 체계 (음수/에지 사례) 에 대해 설명합니다.
통합: 대 샌드 박스 (demotency, 429/5xx, webhooks).
하중/담그기: 페이지 매김/스트림, 역압.
퍼즈: 필드/헤더/시간 경계.
Compat-오래된 SDKs는 새로운 API를 제공하고 그 반대도 마찬가지입니다.
연기 팩: CI에서 회귀를 잡는 데 5 분.

17) 원격 측정 및 개인 정보 보호 정책

옵션 선택: PII가없는 집계 된 SDK 메트릭 (버전, 언어, 상태) 모음.
설정: '원격 측정:' 익명 '전체' (기본값은 꺼져 있습니다/익명).
투명성: 무슨 일이 일어날 지, 왜 그런지 문서화; 연결 해제 상자를 확인합시다.

18) 성능 및 FinOps

배칭: 작은 쿼리를 결합하십시오. 한계 RPS; gzip/br.
ETag/If-None-match 캐싱, 조건부 GET.
경제 모델: 모든 것을 메모리에로드하는 대신 게으른 반복자.
한계가있는 동시성: API를 "DDOS" 하지 않도록 'max _ 동시성'.

19) 전형적인 SDK 구성 요소 (골격)

오류 (타이프 스크립트)

ts export class ApiError extends Error {
constructor(
readonly status: number,
readonly errorCode: string,
readonly traceId?: string,
readonly retriable?: boolean,
readonly details?: unknown
) { super(`${status} ${errorCode}`); }
}

페이지 네이터 (파이썬)

py class Paginator(Generic[T]):
def __init__(self, fetch_page):
self._fetch = fetch_page self._cursor = None async def __aiter__(self):
while True:
page = await self._fetch(self._cursor)
for item in page. items:
yield item if not page. has_more: break self._cursor = page. next_cursor

WebhookVerifier (Go)

go func Verify(body []byte, signatureHeader, secret string) bool {
parts:= strings. SplitN(signatureHeader, "=", 2)
mac:= hmac. New(sha256. New, []byte(secret))
mac. Write(body)
expected:= base64. StdEncoding. EncodeToString(mac. Sum(nil))
return hmac. Equal([]byte(parts[1]), []byte(expected))
}

20) 지원, SLA 및 커뮤니티

SDK 별 SLA: 중요한 버그-ETA 수정, 통신 채널, 호환성 매트릭스 (SDK 년도 애플리케이션).
발행 템플릿: 버그/기능/질문, 언어/버전 별 자동 심사.
로드맵/레이블: "좋은 첫 번째 문제", "도움을 원했습니다".

보안 정책: 'SECURITY. 다른 사람들은 그렇게 생각하지 않아요

21) SDK 품질 점검표

• 단일 모델 오류 ('상태', '오류 _ 코드', 'trace _ id', '검색 가능').
• 타임 아웃/후퇴/지터, '재생 후' 에 대한 존중.
• Idempotency 작성, 자동 'Idempotency-Key'.
• 커서 페이지 매김, 게으른 반복자/스트림.
• HMAC/mTLS를 사용한 WebhookVerifier 및 중복 제거.
• ENV/생성자/매개 변수를 통한 설정.
• 로깅/메트릭/OTel 후크, 비밀이없는 디버그 모드.
• SemVer, 90 일 이상 감소, LTS 지점.
• 인기있는 작업에 대한 예와 요리 책을 완성하십시오.
• CI의 언어 간 기능 패리티 행렬.

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

1. MVP (2-3 주): 기본 클라이언트, 지정, 3-5 키 끝점, 페이지 매김, 단일 오류 모델, retrai/타임 아웃; TS + 파이썬.
2. 스케일 (3-5 주): Java/Go/.NET, WebhookVerifier, dememotency 쓰기, 원격 측정 후크, OpenAPI에서 모델 생성.
3. Pro (연속): 스트리밍/SSE/gRPC, perf 최적화, LTS 지점, 확장 요리 책, 마이그레이션/감소 도구.

23) 미니 -FAQ

모든 것을 만들거나 손으로 쓰십니까?
모델/클라이언트 및 인체 공학 (페이지 네이터, 리트레이, demempotency, 편리한 서명) 을 수동으로 생성하십시오.

별도의 async-SDK가 필요합니까?
파이썬 - 차이나 ('AsyncClient'); JS에서 - 기본적으로; v.NET/Java-가능한 경우 비동기 호출.

언어의 패리티를 유지하는 방법?
CI의 매트릭스 기능은 "지연되는" 자동보고와 함께 "벨트 별" (TS → Py → Java → Go → .NET) 을 릴리스합니다.

합계

강력한 SDK는 모든 언어에서 동일한 단일 표면, 신뢰할 수있는 채무 불이행 및 예측 가능한 계약입니다. 개발자에게 안전한 설정, 이해할 수있는 오류 모델, 웹 후크의 편리한 페이지 매김 및 검증을 제공하고 고품질 문서와 엄격한 준버로이를 완료하십시오. 그런 다음 통합이 빠르고 지원이 저렴하며 생태계가 지속 가능하고 확장 가능합니다.