비동기 작업 API의 멱등성과 상태 제어
파일 변환, 대량 정산, 리포트 생성, 외부 시스템 동기화처럼 오래 걸리는 작업은 단순한 REST 요청으로 처리하기 어렵습니다. 요청 시간이 길어질수록 타임아웃, 중복 제출, 클라이언트 재시도, 중간 실패가 한꺼번에 문제로 나타납니다. 이때 필요한 것은 빠른 응답이 아니라 작업을 하나의 상태 기계로 다루는 설계입니다.
요청과 실행을 분리한다
비동기 작업 API는 보통 POST /jobs로 작업을 만들고, GET /jobs/{id}로 상태를 조회합니다. 중요한 점은 작업 생성 요청이 실제 실행 완료를 의미하지 않는다는 것입니다. 서버는 요청을 검증하고 작업 레코드를 만든 뒤, 실행은 워커나 큐로 넘깁니다.
이 분리 덕분에 클라이언트는 연결을 오래 유지하지 않아도 되고, 서버는 작업량을 큐에서 조절할 수 있습니다. 또한 작업 이력과 결과를 저장할 수 있어 장애 분석도 쉬워집니다.
멱등성 키는 선택이 아니다
클라이언트가 네트워크 오류로 응답을 받지 못하면 같은 작업을 다시 요청할 수 있습니다. 서버가 이 요청을 새 작업으로 처리하면 중복 결제, 중복 이메일, 중복 배치가 발생합니다. 그래서 작업 생성에는 멱등성 키가 필요합니다.
좋은 멱등성 설계는 다음을 보장합니다.
- 같은 키와 같은 요청 본문은 같은 작업 ID를 반환한다.
- 같은 키지만 다른 본문은 충돌로 거절한다.
- 키 보존 기간을 문서화한다.
- 완료, 실패, 취소 상태에서도 조회 가능한 결과를 남긴다.
멱등성 키는 클라이언트 편의 기능이 아니라 데이터 보호 장치입니다.
상태 전이는 명시적으로 제한한다
비동기 작업의 상태는 queued, running, succeeded, failed, canceling, canceled처럼 명확해야 합니다. 그리고 모든 상태에서 모든 상태로 이동할 수 있으면 안 됩니다. 예를 들어 이미 succeeded가 된 작업은 다시 running이 될 수 없어야 하고, canceling 상태에서는 워커가 중단 지점을 안전하게 확인해야 합니다.
상태 전이를 코드에 흩뿌리면 시간이 갈수록 예외가 늘어납니다. 상태 전이 테이블을 만들고, 저장소 업데이트는 조건부 갱신으로 처리하는 편이 안전합니다.
운영에서 확인할 지표
- 작업 생성량과 큐 대기 시간
- 상태별 체류 시간
- 멱등성 충돌 비율
- 취소 요청 후 실제 중단까지 걸린 시간
- 실패 원인별 재시도 성공률
비동기 작업 API의 목적은 오래 걸리는 일을 숨기는 것이 아닙니다. 오래 걸리는 일을 사용자와 운영자가 이해할 수 있는 단위로 바꾸는 것입니다.
Continue Reading
다음으로 읽기 좋은 글
API Idempotency Key 생명주기 설계
프로덕션 API에서 idempotency key의 생성, 저장, 만료, 재사용 동작을 어떻게 설계할지 정리합니다.
⚙️ Backend대용량 API 작업의 Job Status 패턴
오래 걸리는 백엔드 작업을 동기 API로만 다루면 사용자 경험과 운영 안정성이 함께 흔들립니다. Job status 패턴을 실전적으로 정리합니다.
💬 Language런타임 스키마 경계 실전 설계
TypeScript, Python, Java 같은 언어에서 정적 타입만으로 막기 어려운 외부 입력을 런타임 스키마로 보호하는 방법을 정리합니다.
🧪 Test플레이키 테스트 신호 예산 관리
불안정한 테스트를 단순 재시도로 덮지 않고 신뢰도, 소유권, 격리 기준으로 관리하는 방법을 정리합니다.
다음 탐색