---
title: "멱등성·작업 큐·사용량 원장: 반복 실행에도 결과를 지키는 운영 설계"
slug: "idempotency-jobs-usage-ledger"
language: "ko"
tags: ["멱등성","작업 큐","사용량 원장","운영"]
created: "2026-09-28T00:00:00.000Z"
published: "2026-09-28T00:00:00.000Z"
updated: "2026-09-28T00:00:00.000Z"
sample: false
---

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

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

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

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

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

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

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

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

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

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

## 실패를 포함한 운영 검증

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