API 사용 시 주문 중복: 원인과 방어

왜 한 번의 작업 후에 중복이 생기는가

패널 소유자가 버튼을 한 번만 눌러도 팔로워, 조회수, 반응 또는 다른 서비스에 대한 동일한 주문이 여러 개 표시될 수 있습니다. 일반적으로 문제는 클릭 자체가 아니라 클라이언트, API, 데이터베이스, 공급자 사이의 체인에 있습니다.

서버 관점에서 '하나의 요청'이 항상 하나인 것은 아닙니다. 클라이언트가 응답을 받지 못해 전송을 반복했는데, 첫 번째 작업은 이미 저장되었을 수 있습니다. 때로는 주문이 패널 데이터베이스에 한 번 생성되지만 공급자에게 두 번 전송됩니다. 이는 서로 다른 시나리오이며, 각각 다르게 수정됩니다.

타임아웃은 주문이 생성되지 않았다는 의미가 아니다

가장 흔한 원인은 클라이언트가 제한된 시간 동안만 응답을 기다리는 것입니다. 서버는 요청을 받아 주문을 생성하지만, 설정된 타임아웃보다 늦게 응답합니다. 클라이언트는 작업이 실패했다고 판단하고 다시 전송합니다.

결과적으로 첫 번째 주문은 이미 데이터베이스에 있고, 두 번째 요청이 또 하나를 생성합니다. 특히 외부 API의 느린 응답, 과부하된 큐 또는 서비스 간 불안정한 연결에서 자주 발생합니다.

타임아웃은 응답이 없다는 것만 알려줄 뿐, 요청 처리가 없다는 것을 의미하지 않습니다.

클라이언트 측 자동 재시도

HTTP 요청 라이브러리, 백그라운드 작업 및 통합 서비스는 종종 요청을 자동으로 반복합니다. 연결 오류, 서버 응답 코드, 네트워크 단절 또는 너무 긴 응답이 원인이 될 수 있습니다.

재시도 자체는 유용합니다. 일시적 장애 시 손실되는 주문 수를 줄여줍니다. 이 접근 방식의 단점은 재처리 방어가 없으면 모든 네트워크 불안정이 중복으로 변한다는 것입니다.

• 재시도는 사이트나 봇 코드에서 실행될 수 있습니다.
• 큐가 작업을 재시작할 수 있습니다.
• 프록시나 통합 모듈이 요청을 반복할 수 있습니다.
• 운영자가 오류 후 주문을 수동으로 다시 보낼 수 있습니다.

재요청이 첫 번째 응답보다 먼저 도착하는 경우

때로는 두 개의 동일한 요청이 실제로 거의 동시에 API에 도달합니다. 예를 들어 사용자가 양식을 두 번 제출했거나, 프론트엔드가 버튼을 차단하지 않았거나, 백그라운드 작업이 첫 번째 완료 전에 다시 시작된 경우입니다.

처리기가 먼저 주문 존재 여부를 확인한 후 생성하면, 두 개의 병렬 작업이 동시에 검사를 통과할 수 있습니다. 각각은 주문이 아직 없다고 보고 새로운 레코드를 추가합니다.

이러한 상황을 데이터 경쟁이라고 합니다. 코드의 단순한 사전 확인만으로는 완전히 방어할 수 없습니다. 데이터베이스 수준의 제한 없는 검사의 단점은 병렬 부하에서 깨진다는 것입니다.

주문은 기록되었지만 API 응답이 손실된 경우

요청은 여러 단계를 거칩니다. 서버가 데이터를 받고, 레코드를 생성하고, 작업을 큐에 넣고, 응답을 보냅니다. 어느 단계 사이에서든 장애가 발생할 수 있습니다. 예를 들어 데이터베이스가 이미 주문 생성을 확인했지만 클라이언트에 응답을 전달하기 전에 연결이 끊어졌습니다.

클라이언트는 주문이 접수되었는지 알 수 없어 작업을 반복합니다. 별도의 확인 메커니즘이 없는 API는 요청을 새로운 것으로 인식합니다. 로그에서는 서비스가 '스스로' 두 개의 주문을 생성한 것처럼 보이지만, 실제로는 두 개의 수신 요청이 있었던 것입니다.

주문 생성을 위한 멱등성 키

생성 작업에는 고유한 멱등성 키가 필요합니다. 클라이언트는 첫 전송 전에 이를 생성하고 주문 매개변수와 함께 전달합니다. 타임아웃이나 오류로 인한 재시도 시 동일한 키를 사용합니다.

API는 처리 결과와 함께 키를 저장합니다. 이미 알려진 키로 요청이 오면 서버는 새 주문을 생성하지 않고 첫 번째 요청의 결과(주문 ID, 상태 또는 이전에 생성된 오류)를 반환합니다.

하나의 키는 하나의 HTTP 연결이 아닌 하나의 비즈니스 작업에 대응해야 합니다.

이 방법의 단점은 키를 저장하고, 규칙에 따라 정리하고, API 측에서 검증해야 한다는 것입니다. 재시도마다 새 키를 생성하면 방어가 작동하지 않습니다. 서로 다른 주문에 하나의 키를 사용하면 일부 새 작업이 잘못 거부됩니다.

고유성은 데이터베이스에서 제어해야 한다

멱등성은 데이터베이스의 고유 제약으로 보완하는 것이 좋습니다. 이를 위해 주문을 명확히 설명하는 조합을 선택합니다. 내부 클라이언트 ID, 멱등성 키, 서비스 유형 및 기타 필요한 필드입니다.

데이터베이스는 두 개의 처리기가 동시에 생성에 도달하더라도 두 번째 레코드를 거부해야 합니다. 충돌 후 API는 설명 없는 오류가 아닌 기존 주문을 반환합니다.

엄격한 고유 제약의 단점은 링크나 사용자 이름만으로 구축할 수 없다는 것입니다. 클라이언트는 동일한 채널에 동일한 서비스를 의도적으로 여러 번 주문할 수 있습니다. 너무 광범위한 제약은 정상적인 재구매를 차단합니다.

큐가 작업을 두 번 이상 전달할 수 있다

작업 큐는 종종 '최소 한 번 전달' 원칙으로 작동합니다. 워커가 작업을 처리했지만 완료를 확인하지 못하면, 큐는 동일한 작업을 다른 워커에게 다시 전달할 수 있습니다.

큐에게는 작업을 잃지 않는 정상적인 방법입니다. 멱등성 없는 주문 생성에게는 중복의 원천입니다. 작업 ID 또는 별도의 작업 키를 최종 처리기까지 전달해야 하며, 공급자에게 주문을 보내는 모듈도 포함됩니다.

재전달을 비활성화하는 것의 단점은 워커가 다운되면 일부 주문이 사라질 수 있다는 것입니다. 가능한 재전달을 수용하고 처리기를 이에 견고하게 만드는 것이 더 안전합니다.

중복은 패널과 공급자 사이에서 발생한다

내부 주문은 한 번 생성될 수 있지만 외부 API로의 요청이 두 번 전송될 수 있습니다. 원인은 동일합니다. 패널이 공급자로부터 응답을 받지 못해 전송을 반복하기로 결정한 것입니다. 공급자가 첫 번째 요청을 이미 접수했다면, 공급자 측에 동일한 신청이 두 개 나타납니다.

내부 주문을 외부와 연결하는 별도의 바인딩이 필요합니다. 전송 ID, 멱등성 키 또는 저장된 공급자 응답입니다. 자체 패널 입구의 방어가 나가는 호출을 자동으로 보호한다고 가정할 수 없습니다.

외부 API와의 대조의 단점은 모든 공급자가 외부 키로 검색을 지원하지 않는다는 것입니다. 그런 경우 전송 시도를 기록하고 불확실한 상태를 별도로 분석해야 합니다.

웹훅은 새 주문을 생성해서는 안 된다

웹훅은 변경 사항을 알립니다. 주문 접수, 시작, 완료, 취소 또는 확인 필요 등입니다. 오류는 웹훅 처리기가 알림을 주문을 새로 생성하라는 명령으로 인식할 때 발생합니다.

동일한 웹훅이 다시 올 수 있습니다. 발신자는 확인을 받지 못하면 전달을 반복하며, 알림은 때때로 순서 없이 도착합니다. 처리기는 외부 ID로 기존 주문을 찾아 상태를 업데이트해야 합니다.

수신 시간만으로 웹훅을 처리하는 것의 단점은 늦은 알림이 현재 상태를 오래된 것으로 덮어쓸 수 있다는 것입니다. 이벤트 ID, 상태 버전 또는 명확한 전환 규칙이 필요합니다.

어떤 기록이 중복의 원인을 찾는 데 도움이 되는가

조사에는 두 개의 주문 번호만 보는 것으로는 충분하지 않습니다. 각 처리 단계에 대한 데이터가 필요합니다. 요청 시간, 멱등성 키, 클라이언트 ID, 주문 매개변수, 백그라운드 작업 번호, 외부 API 응답 및 재전송 시도입니다.

• 중복을 링크가 아닌 작업 키로 대조하세요.
• 수신 API 로그에 동일한 요청이 있었는지 확인하세요.
• 큐에서 작업이 반복되었는지 확인하세요.
• 내부 주문 생성과 공급자 전송을 분리하세요.
• 응답을 받은 즉시 외부 신청 ID를 저장하세요.

너무 짧은 로그의 단점은 문제의 원인이 분석되기 전에 사라진다는 것입니다. 과도한 로깅의 단점은 기록에 토큰, 개인 데이터 및 기타 민감한 필드가 포함될 수 있으므로 마스킹해야 한다는 것입니다.

불확실한 요청 결과를 처리하는 방법

타임아웃 후에는 즉시 새 데이터로 주문을 다시 생성할 수 없습니다. 먼저 API가 멱등성 키 또는 클라이언트 ID로 작업을 확인해야 합니다. 주문이 발견되면 현재 상태를 반환합니다. 처리가 아직 진행 중이면 클라이언트는 대기 상태를 받습니다.

1. 첫 요청 전에 작업 키를 생성합니다.
2. 매 재시도마다 동일한 키를 전송합니다.
3. 키와 주문을 하나의 보호된 데이터베이스 작업으로 저장합니다.
4. 작업 ID를 큐와 외부 API에 전달합니다.
5. 재요청 시 이전에 생성된 주문을 반환합니다.

이 시나리오는 API와 클라이언트 통합의 수정이 필요합니다. 단점은 디버깅이 더 어렵고 주문 상태가 더 많다는 것이지만, 요청의 재전달이 더 이상 자동으로 재구매를 의미하지 않게 됩니다.