토렌트 기어

시작시 5 가지 중요한 API 통합 오류

오류 # 1. 퇴각의 dempotence와 "폭풍" 없음

증상: 중복 주문/지불, 금액 불일치, 분쟁 수익률, DLQ 경고가 증가하고 있습니다.

루트: 요청/웹 후크 및 네트워크 플래피의 반복 전달은 정상입니다. "생성/쓰기" 작업이 demmpotent가 아닌 경우, retrays는 손상을 곱합니다.

방법

모든 안전하지 않은 메소드 (POST/PATCH) 에 대한 Idempotency-Key/' operation _ id '.

'operation _ id' 데이터베이스의 고유 인덱스. 재생-이전 결과를 반환합니다.

받은 편지함 테이블을 통한 웹 후크 ('이벤트 _ id + 서명' 별 dedupe). 아웃 바운드 이벤트 - 전송.

Retrai: 안전한 작업을 위해서만 최대 1-2 배, 지수 + 지터.

HTP 규칙 (예):

http
POST/v1/결제
이데올로기 키: ik _ f35a2
콘텐츠 유형: 응용 프로그램/json

{"금액": 5000, "통화": "EUR", "소스": "card _"..}

SQL 보호 (단순화):

sql
ALTER TABLE 지불 ADD CONSTRAINT uniq _ op UNIQue (operation _ id);

지터가있는 Retrai (의사 코드):

범위 (2) 의 i에 대한 파이썬:
시도: return call _ api (페이로드, 타임 아웃 = 0. 6)
시간 초과 제외:
수면 (0. 05 2i + 랜덤. 균일 (0, 0. 05))
UpstreamUnaisable을 올리십시오

체크리스트:

모든 "금전적/생성" 논리에는 'operation _ id' 및 uniq 지수가 있습니다.
demotent 작업자가있는받은 편지함을 통해서만 인바운드 웹 후크.
클라이언트 SDK는 Idempotency-Key를 자동으로 설정합니다.

오류 번호 2. 타임 아웃/배상 대 SLO: 의존성 과열

증상: p95가 갑자기 떠 다니고 대기열이 커지고 회로 차단기가 "강타" 됩니다.

루트: 응답의 총 SLO는 400-600ms이며 외부 API에 대한 타임 아웃은 1-2 초이며 심지어 배송 × 3입니다. 당신은 할 수있는 것보다 오래 걸리고 반복으로 중독을 습격합니다.

방법

예산 타이밍: SLO가 400ms 인 경우 업스트림 타임 아웃: 250-300ms; SLO 지정 요청의 총 타임 아웃.

한계/역압: 각 의존성에 대한 통화를위한 세마포어/작업자 풀. 한 번에 붐비는 → 429/503.

서킷 브레이커: 타임 아웃/5xx로 '오픈', '하프 오픈' 복용.

입학 제어: 동시성 제한 (스레드 당, 엔드 포인트/PSP당).

예 (Go):

gosem: = made (chan strt {}, 64 )//경쟁 한계는 PSP func callPSP (ctx 컨텍스트) 입니다. 컨텍스트, req Req) (Res, 오류) {
{선택
case sem <- strue {} {}:
(PHP 3 = 3.0.6, PHP 4)
c, 취소: = 컨텍스트. 시간 초과 (ctx, 300time. 밀리 초)
취소를 연기합니다 ()
반환 psp. (c, req)
기본값:
끝없는 대기열 대신 Res {}, ErrBusy//즉시 실패 반환
}
}

체크리스트:

타임 아웃은 SLO보다 짧습니다. 레트 레이 2; 지터가 있습니다.
외부 API에 대한 풀/세마포어; 지표가있는 회로 차단기.
번잡 한 노선에서는 연결을 유지하지 않고 429/Reduted-After를 반환합니다.

오류 번호 3. 약한 보안: 웹훅 서명, 비밀, TLS

증상: "다른 사람들의" 웹 후크 통과, 코드/로그의 비밀, MITM 위험.

루트: 서명/신선도 확인 없음, 비밀은 env 파일에 있음, 오래된 TLS 및 약한 헤더.

방법

웹 후크의 시그니처 HMAC-CHA256 + 'X-Timestamp' (창이 5-10 분), 서명을 엄격하게 비교합니다.

중요한 통합 또는 IP 허용 목록을위한 mTLS.

Vault/Cloud KMS를 통한 비밀 회전; 최소 권리; 빼기 감사.

TLS 1. 2/1. 3, HSTS, 올바른 CORS (좁은 소스 목록).

서명 검증 (파이썬):

파이썬 데프 확인 (sig _ hdr, ts _ hdr, 본문, 비밀):
복근이라면 (시간. 시간 () - int (ts _ hdr))> 600: 만료 ()
calc = hmac. 새 (비밀, (ts _ hdr + "." + body). (PHP 3, PHP 4) sha256). 헥스 다이제스트 ()
hmac이 아닌 경우. _ digest 비교 (calc, sig _ hdr): BadSig ()

체크리스트:

모든 웹 후크에 서명하고 확인합니다. 신선도 창이 제한되어 있습니다.
KMS/Vault의 비밀, 회전 및 감사가 있습니다.
TLS/HSTS 활성화; CORS 포인트; 적절한 경우 IP/mTLS.

오류 번호 4. 계약 드리프트: "생명을 살았습니다"

증상: prod는 "일부 클라이언트에서만" 떨어졌고, 로그에서 500/422, SDK 및 API의 다른 버전이 주장합니다.

루트: 계약, 역 호환 변경, "조용한" 필드, 동일한 이름에 대한 다른 의미에 대한 엄격한 설명이 없습니다.

방법

계약 우선: OpenAPI/AsyncAPI + 서버/클라이언트 생성; 이벤트의 경우-Avro/Proto + Schema Registry.

동사: 'v1 → v2' (복수/헤더), 편차 계획, 유예 기간.

후방 컴파트: 사소한 릴리스의 추가 변경 사항 만; v-bump없이 삭제/이름을 바꿀 수 없습니다.

계약 테스트: Pact/Buf-제공자/consummer는 CI에서 테스트됩니다.

예:

yaml
OpenAPI: 소량 _ 마이너 단위의 명확한 합계 유형:
유형: 정수 최소: 0 설명: 최소 통화 단위 합계 (정수)

체크리스트:

계약은 git에 저장되며 CI는 호환되지 않는 경우 유효성 검사/중단됩니다.
스키마는 "뒤/앞으로" 호환성을 위해 이벤트를 등록합니다.
변경 사항의 도킹 페이지, 박탈 날짜, 파트너를위한 테스트 벤치.

오류 번호 5. "블라인드" 출시: 메트릭/로그/트레일 및 샌드 박스 없음

증상: "아무것도 보이지 않습니다", 지지대가 채워집니다.

루트: 관찰 가능성이 포함되지 않았으며, 합성물이 없으며, 샌드 박스가 "단어로" 테스트되었습니다.

방법

RED/USE 메트릭: 경로/방법에 따라 각 엔드 포인트의 속도/오류/대기 시간.

상관 관계: 모든 로그 및 응답에서 'trace _ id'; 자 프로스 번들 vebkhuk.

합성: 건강 테스트 (로그인/예금 모래), 웹 후크에 대한 SLA 모니터링 T + 60.

샌드 박스/스테이지: 완전히 격리 된 키/도메인, 가상의 PSP, 항목 "보고서에 포함되지 않음"

추적 ID로 응답:

http
HTT/1. 1202 허용
추적: 7f2b3d8e9c1a4
위치 :/v1/ops/req _ 42/상태

체크리스트:

RED/USE 지표, 대시 보드, 경고 (증상 + 원인).
엔드 투 엔드 트레일; JSON 로그, PII 없음, 'trace _ id'.
주요 지역의 합성; 다른 키가 필요합니다.

프리 런치 계획 (T-7 → T-0)

T-7 일:

최종 계약 스캔: 호환되지 않는 변경 사항이 있습니다. 동결 계획.
비밀/인증서: 회전, 액세스, KMS 정책을 확인하십시오.
합성 24 × 7, 경고는 통화와 관련이 있습니다.

T-3 일:

미니 런 로딩 (버스트 2-5 분): 녹색 영역의 p95/풀/대기열.
DRY-RUN 웹 후크 (리플레이, 5xx, 지터), DLQ 확인.
파트너의 "전화 번호부": L1/L2 연락처, 전쟁 실 채널.

T-0:

SLO 게이트의 채널 트래픽 5% → 25% → 50%; 롤백 준비.
위험한 기능에 대한 킬 스위치/기능 플래그가 포함되어 있습니다.
전쟁 실이 활성화되어 있으며 상태 템플릿이 준비되어 있습니다

롤백 계획 (문제가 발생한 경우)

1. 이전 안정 버전/경로로 트래픽을 릴리스하십시오.

2. phicheflag 논란의 여지가있는 변경 사항

3. 대기열/수영장을 안정화하고 폭풍 속에서 퇴각을 중지하십시오.

4. 사고 후: 타임 라인, 루트, 작업 수집 (고정 전달/계약 수정).

자체 테스트 테이블 시작 (짧은)

블록	질문	그래, 아니
이데올로기	모든 "생성" 메소드에 Idempotency-Key/' operation _ id '및 uniq 인덱스가 있습니까?
배상/타임 아웃	타임 아웃은 SLO보다 짧습니다. 레트 레이 2; 지터?
안전	Webhooks가 서명하고 신선도 창이 10 분, KMS의 비밀은 무엇입니까?
계약	OpenAPI/AsyncAPI 고정, CI는 비 호환성을 포착합니까?
관찰 가능	RED/USE, 트레일, 합성 T + 60, 샌드 박스 분리?
롤백	/ 킬 스위치 롤백 버튼, 통신 계획이 있습니까?

"어떻게"... 라고 자주 물었습니다.

... 공급자가 Idempotency-Key를 지원하지 않습니까?

'해시 (본문)' + 'partner _ 요청 _ id' 를 저장하고 demempotency를 입력하십시오.

... 웹 후크는 때때로 대답을 "전에" 온다?

'operation _ id' 를 유지하고 일시적으로 "알 수없는 → 조정" 상태를 유지하십시오. 정기적 인 화해 자는 불일치를 막을 것입니다.

... 오래된 고객과 새로운 고객을 지원해야합니까?

헤더/URI로 경로 인 엔드 포인트 ('/v1 '및 '/v2') 버전은 최소 N 개월 동안 이전 버전과 호환됩니다.

요약 다시 시작

통합 실패는 거의 항상 같은 것입니다. 계약을 미리 수정하고 관찰 가능성을 높이고 제한/백프레서를 배치하고 모든 외부 상호 작용에 서명하고 합성을 실행하십시오. 그런 다음 파트너가 실패한 경우에도 레트라에서 돈을 잃지 않고 팀 전체에 잠 못 이루는 밤없이 릴리스를 관리 할 수 있습니다.