SAG / ARCHITECTURE NOTE

멱등성·작업 큐·사용량 원장: 반복 실행에도 결과를 지키는 운영 설계

네트워크 재시도와 중복 클릭이 있어도 작업과 과금이 한 번만 반영되도록 멱등성 키, 상태 전이, 사용량 원장을 설계하는 방법입니다.

Markdown 내려받기

어떤 상황에서 활용하나요?

진단 결과를 실제 수정 작업으로 옮기는 개발·콘텐츠 담당자에게 유용합니다. 고객 질문에 부족한 답을 대상 URL·제안 문장·공식 근거·승인자와 연결하고, 반영 후 무엇을 재검증할지 정하세요.

SAG(새그)는 더크림유니언이 운영하는 GEO·AEO·SEO 분석 및 최적화 플랫폼입니다. 검색엔진과 생성형 AI가 브랜드와 웹사이트 콘텐츠를 어떻게 발견하고 이해하는지 분석하고, 경쟁사 비교·개선 우선순위·실행 결과·재검증을 관리합니다. 플랫폼 구독과 전문 운영 지원을 제공하며, 콘텐츠 제작·사이트 코드 수정 등 대행 실행 범위는 별도 계약에서 정합니다.

운영 서비스는 같은 요청을 여러 번 받습니다

사용자가 버튼을 두 번 누르거나 네트워크가 끊겨 클라이언트가 요청을 다시 보낼 수 있습니다. 서버리스 함수도 처리 도중 종료된 뒤 재실행될 수 있습니다. 이런 환경에서 요청 한 번이 작업 두 건이나 사용량 이중 차감으로 이어지면 결과를 신뢰하기 어렵습니다.

멱등성은 같은 의도의 요청이 반복되어도 최종 효과가 한 번만 발생하게 만드는 성질입니다. SAG는 생성·실행 요청에 논리적인 멱등성 키를 연결하고, 이미 처리 중이거나 완료된 키라면 기존 결과를 반환하는 구조를 사용합니다.

콘텐츠·기술 개선 작업을 관리하는 SAG 운영 예시

이 화면은 방법 설명을 위한 SAG 공개 예시이며, 특정 고객사의 성과나 색인·검색·AI 추천을 보장하지 않습니다.

작업 상태를 명시적으로 관리하기

시간이 오래 걸리는 점검은 요청 안에서 끝내기보다 작업 큐로 넘겨 상태를 관리하는 편이 안전합니다.

  • queued: 실행을 기다리는 상태
  • running: 작업자가 처리 중인 상태
  • succeeded: 결과와 정산이 완료된 상태
  • failed: 재시도 가능한 실패 상태
  • dead-letter: 자동 재시도 한도를 넘겨 운영 확인이 필요한 상태

상태 전이는 데이터베이스에서 원자적으로 처리해야 두 작업자가 같은 건을 동시에 가져가지 않습니다. 재시도 횟수와 다음 실행 시각도 함께 기록하면 일시적인 외부 장애와 지속적인 오류를 구분할 수 있습니다.

사용량은 값이 아니라 원장으로 남깁니다

현재 사용량 숫자만 덮어쓰면 언제 어떤 작업으로 증가했는지 확인하기 어렵습니다. 사용량 원장은 예약, 확정, 취소를 각각의 기록으로 남깁니다. 작업을 시작할 때 한도를 예약하고 성공하면 확정하며, 실행 전에 실패하면 예약을 되돌립니다. 같은 작업 키의 정산은 한 번만 허용합니다.

실패를 포함한 운영 검증

정상 성공 외에도 중복 제출, 작업자 충돌, 제한 초과, 실패 후 재시도, 완료 뒤 동일 요청을 테스트해야 합니다. 멱등성과 원장은 사용자가 보는 기능은 아니지만 “버튼은 한 번 눌렀는데 왜 두 번 차감됐나요?” 같은 운영 사고를 막는 핵심 아키텍처입니다.

주제별 기술 참고

이 기술을 이어서 읽는 방법

테넌트 권한, 작업 재시도, 캐시와 승인 이력을 살펴봅니다.

PDF

idempotency-jobs-usage-ledger.pdf

목록