개발자 도구 · UUID 생성기
멱등성 키: 안전한 재시도를 위해 클라이언트 생성 UUID 사용
· 그것이 중요한 이유
uuid 암호화 브라우저 API
결제 요청 시간 초과로 인해 결제 요청이 처리되었는지 여부를 확신할 수 없습니다. 멱등성 키를 사용하면 안전하게 재시도할 수 있으며 CSPRNG에서 생성된 UUID가 자연 키입니다. 이 게시물에서는 패턴을 끝까지 설명합니다.
고객에게 두 번 요금을 청구했을 수 있는 시간 초과 — 이를 해결하기 위해 오류 모드 멱등성 키가 존재합니다.
결제 요청 중 시간 초과는 클라이언트와 시스템에 진정한 불확실성을 야기합니다. 귀하의 HTTP 클라이언트가 응답 대기를 포기했지만, 연결이 종료되거나 시간 초과되기 전에 결제 서버가 거래를 처리했을 수 있습니다. 동일한 요청을 다시 시도하면 고객에게 비용이 두 번 청구될 수 있습니다. 재시도하지 않으면 결제가 완료되지 않습니다. 결제 시스템이 불행한 중간 지점에 실패합니다. 고객의 돈이 없어졌을 수도 있고, 내일 도착할 수도 있고, 처리 대기열에 갇히거나, 계좌에서 전혀 나가지 않았을 수도 있습니다. 이러한 모호함은 금융 시스템에서는 용납될 수 없습니다.
멱등성 키 작동 방식 - 서버는 첫 번째 응답을 키 아래에 저장하고 반복을 위해 재생합니다.
멱등성 키는 재시도를 안전하고 결정적으로 만들어 이 문제를 우아하게 해결합니다. 클라이언트는 결제, 이체, 청구 등 각 인텐트에 대해 고유한 키를 생성하고 이를 모든 요청에 포함합니다. 서버는 결제를 처리하고 해당 키 아래에 응답을 캐시하며 키와 결과를 모두 저장합니다. 보존 기간 내에 동일한 키가 다시 도착하면 서버는 결제를 다시 처리하지 않고 캐시된 응답을 재생합니다. 고객은 정확히 동일한 키가 몇 번이나 전송되든 항상 동일한 결과를 낳는다는 사실을 확신하고 재시도할 수 있습니다. 이 패턴은 모호성을 제거하고 재시도 논리를 안전하게 만듭니다.
첫 번째 시도 전에 생성 - 요청이 떠나기 전에 키가 존재해야 하고 재시도 시 그대로 재사용되어야 하는 이유
이 패턴은 최신 HTTP 사양보다 오래되었지만 광범위한 재정적 손실과 중복 청구로 인한 고객 불만으로 인해 결제 분야에서 두각을 나타냈습니다. 이제 모든 결제 API와 많은 웹 서비스 API가 멱등성 키를 지원합니다. CSPRNG에서 생성된 UUID는 추측할 수 없고 클라이언트 간의 조정 없이 고유하며 서버 측 할당이나 중앙 권한이 필요하지 않기 때문에 키에 대한 자연스러운 선택입니다. 클라이언트는 첫 번째 시도 전에 이를 생성하고, 재시도할 때마다 그대로 재사용하며, 매번 동일한 응답을 받습니다. 키 생성을 조정하는 데 서버 측 상태가 필요하지 않습니다.
카운터 또는 페이로드 해시가 아닌 임의의 UUID인 이유 — 조정이 필요 없는 고유성 및 인텐트 전체에서 우발적인 재사용이 없음
재시도 시 키 생성이 너무 늦어서 멱등성을 보장할 수 없으므로 요청이 클라이언트를 떠나기 전에 키가 있어야 합니다. 첫 번째 요청이 성공하여 고객에게 비용이 청구된 경우 재시도 시 새 키를 생성하면 문제가 가려지고 다시 비용이 청구됩니다. 클라이언트는 첫 번째 시도 전에 키를 커밋하고, 이를 메모리나 영구 저장소에 저장하고, 시간 초과나 재시도가 필요할 경우 동일한 키를 재사용해야 합니다. 수동 API 테스트의 경우 ToolAcre 생성기는 컬 또는 REST 클라이언트에 붙여 넣을 수 있는 키를 생성하고 여러 요청에서 복사 및 재사용하여 멱등성 동작을 테스트합니다.
범위 및 수명 — 작업당, 계정당 키 및 서버가 이를 기억해야 하는 기간
멱등성 키에 대해 해시 또는 순차 카운터 대신 UUID을 사용하는 이유는 무엇입니까? 요청 페이로드의 해시는 직관적인 것처럼 보입니다. 동일한 페이로드는 동일한 해시와 동일한 키를 얻습니다. 하지만 이 사용 사례에서는 해시가 약합니다. 금액, 수신자 또는 매개변수가 서로 다른 두 개의 거의 동일한 요청이 완전히 다른 해시를 생성하여 별도의 요금을 생성하기 때문입니다. 이는 정확하지만 필요한 모든 보호를 제공하지는 않습니다. 순차 카운터에는 조정 및 분산 상태가 필요합니다. 두 클라이언트가 모두 인프라에서 카운터 기반 키를 생성하는 경우 해당 카운터가 충돌할 수 있습니다. UUID에는 중앙 권한이 필요하지 않으며 추측할 수 없으며 전체 인터넷에서 우연히 충돌할 가능성이 거의 없습니다.
작업된 예 — 클라이언트가 보내는 것과 서버가 매번 반환하는 것을 보여주는 동일한 키를 사용한 재시도 시퀀스
서버 측 구현은 키 아래에 응답을 저장하고 반복 시 캐시된 응답을 반환합니다. 실제 운영 질문을 결정하는 데에는 복잡성이 있습니다. 보존 기간, 키를 기억할 기간, 캐시 크기, 기억할 키 수, 동일한 키를 사용하는 두 개의 동시 요청이 결제를 두 번 처리하는 것을 방지하는 방법, 키를 잊어버릴 때 정리 등이 있습니다. 이는 UUID 생성기 범위를 벗어나는 저장 및 안정성 질문입니다. 클라이언트의 임무는 좋은 키를 생성하고 재시도 시 이를 재사용하는 것입니다. 서버의 임무는 캐시를 정확하고 내구성 있게 구현하는 것입니다.
여기서 다루지 않는 내용 — 별도의 디자인인 패턴을 구현하는 데 필요한 서버 측 저장소 및 잠금
작업된 예는 실제로 일반적인 순서를 보여줍니다. 모바일 앱은 멱등성을 지원하는 API를 사용하여 친구에게 돈을 이체해야 합니다. 요청을 보내기 전에 앱은 로컬 암호화 라이브러리를 사용하여 UUID을 생성하거나 테스트 목적으로 ToolAcre 생성기(3fa85f64-5717-4562-b3fc-2c963f66afa6)에서 하나를 가져옵니다. 앱은 JSON 본문과 HTTP 헤더 Idempotency-Key(3fa85f64-5717-4562-b3fc-2c963f66afa6)를 사용하여 /transfers에 POST 요청을 보냅니다. 서버는 전송을 처리하고 3fa85f64-5717-4562-b3fc-2c963f66afa6 → {status: "success", transferId: "xfer-12345"}를 캐시에 저장하고 결과와 함께 200 응답을 반환합니다.
요약: 하나의 의도, 하나의 키 - ToolAcre 생성기는 통합을 직접 테스트할 때 키로 사용할 CSPRNG 지원 UUID을 제공합니다.
네트워크 시간이 초과되고 클라이언트가 첫 번째 시도에서 응답을 볼 수 없습니다. 앱은 새로운 UUID을 생성하지 않고 동일한 멱등성 키를 사용하여 동일한 요청을 재시도합니다. 서버는 캐시에 있는 키를 인식하고 캐시된 응답을 찾은 후 새로운 전송을 처리하거나 고객에게 다시 요금을 청구하지 않고 즉시 {status: "success", transferId: "xfer-12345"}를 반환합니다. 작업은 멱등적입니다. 다시 시도하면 매번 동일한 관찰 가능한 결과가 생성됩니다. 작업된 테스트의 경우 ToolAcre 생성기가 키를 제공할 수 있습니다. UUID를 생성하고 헤더에 포함시킨 후 응답을 관찰하고 동일한 키로 다시 전송하여 서버가 캐싱을 올바르게 구현하는지 확인하세요.