멱등성 있는 인덱서 핸들러 설계 - 재처리 안전성 확보

시리즈 목차

1. 블록체인 인덱서란?
2. 인덱서 아키텍처 Deep Dive
3. 이력 테이블 vs 스냅샷 테이블
4. Rust로 인덱서 SDK 만들기
5. Diesel ORM 실전 활용
6. 멱등성 있는 인덱서 핸들러 설계 (현재 글)

멱등성이 왜 필수인가

인덱서는 재시작, 네트워크 장애, 수동 복구 과정에서 동일 트랜잭션을 반복 처리합니다. 멱등성이 없으면 중복 데이터, 잔액 왜곡, 상태 오염이 발생합니다.

실전 패턴

1. 이력 테이블: 복합 PK + ON CONFLICT DO NOTHING
2. 스냅샷 테이블: UPSERT + version guard
3. 값 갱신은 상대 연산(+1)보다 절대 상태 반영 우선

복구 API 설계

범위 재처리 API(start_version, end_version)를 별도로 두고, 정상 파이프라인과 같은 멱등 핸들러를 재사용해야 합니다.

버전 트래킹

• 프로세서별 마지막 처리 버전 저장
• 배치 단위 커밋 시점 명확화
• 재시작 시 last_version + 1부터 재개

체크리스트

1. 같은 이벤트 2번 처리해도 결과가 같은가
2. out-of-order 배치가 와도 최신 상태가 유지되는가
3. 부분 실패 후 재시도 시 중복 부작용이 없는가

결론

인덱서의 신뢰성은 처리 속도가 아니라 멱등성에서 시작합니다. 빠른 시스템보다 다시 돌려도 같은 결과가 나오는 시스템이 운영에서 이깁니다.