외부 데이터 vs 내부 데이터 — Pat Helland의 앱 설계 교훈

"외부"는 당신이 제어하지 못하는 모든 것입니다: 브라우저, 모바일 네트워크, 큐, 서드파티 웹후크, 재시도, 타임아웃. 메시지는 지연되거나, 중복되거나, 손실되거나, 순서가 뒤바뀔 수 있다고 가정하세요.

"내부"는 당신이 제어하는 것들입니다: 저장된 상태, 규칙, 그리고 나중에 증명할 수 있는 사실들(보통 데이터베이스에 있음).

네트워크가 항상 진실을 말해주지 않기 때문입니다.

클라이언트가 타임아웃을 경험했다고 해서 서버가 요청을 처리하지 않았다는 의미는 아닙니다. 웹후크가 두 번 도착했다고 해서 제공자가 그 동작을 두 번 했다는 뜻도 아닙니다. 각 메시지를 "새로운 진실"로 취급하면 중복 주문, 이중 청구, 또는 멈춘 워크플로가 발생합니다.

명확한 경계는 신뢰할 수 없는 메시지가 내구성 있는 사실이 되는 지점입니다.

일반적인 경계 예:

• 데이터베이스에 커밋하는 API 엔드포인트
• 이벤트를 상태 변경으로 기록하는 큐 소비자
• 제공자가 발생했다고 주장한 것을 기록하는 웹후크 핸들러

데이터가 경계를 넘어오면 내부에서 불변 조건(예: "주문은 한 번만 결제될 수 있다")을 강제합니다.

멱등성을 사용하세요. 기본 원칙은: 같은 의도는 여러 번 전송되어도 같은 결과를 내야 한다는 것입니다.

실무 패턴:

• 클라이언트가 작업마다 고유한 멱등성 키를 전송함
• 서버는 키와 최종 응답을 내구성 있게 저장함
• 중복이 오면 첫 번째 요청과 같은 리소스 ID/상태를 반환함

메모리에만 두지 마세요. 보호 기록은 재시작 후에도 남아 있어야 하므로 경계 내부의 영구 저장소(예: PostgreSQL)에 보관하세요.

보존 기간에 대한 규칙:

• 낮은 위험의 작업: 몇 분~몇 시간
• 비용이 큰 작업(결제, 환불, 배송, 이메일): 며칠 이상

현실적인 재시도와 지연된 콜백을 커버할 만큼 오래 보관하세요.

불확실성을 인정하는 상태를 사용하세요.

단순하고 실용적인 집합 예:

• pending_* (의도를 수락했지만 결과를 모름)
• succeeded / failed (최종 결과를 기록함)
• needs_review (불일치가 감지되어 사람이나 특별한 작업이 필요함)

이렇게 하면 타임아웃 시 추측하지 않도록 하고 조정 작업이 착지할 명확한 장소를 제공합니다.

네트워크를 통해 여러 시스템에 원자적으로 커밋하는 것은 거의 불가능하기 때문에 함정이 됩니다.

예: "주문 저장 → 카드 결제 → 재고 예약"을 동기적으로 수행하면 어떤 단계가 타임아웃될 때 성공 여부를 알 수 없습니다. 재시도하면 중복이 발생할 수 있고, 재시도하지 않으면 작업이 미완성으로 남습니다.

부분적 성공을 설계하세요: 먼저 의도를 영구 저장하고, 외부 작업을 수행한 뒤 결과를 기록합니다.

아웃박스/인박스 패턴은 네트워크가 완벽하지 않더라도 시스템 간 메시지를 신뢰성 있게 만듭니다.

• Outbox: 상태 변경과 동일한 데이터베이스 트랜잭션으로 보낼 메시지 행을 작성합니다.
• 워커가 아웃박스를 읽어 메시지를 전송합니다.
• Inbox(수신 측): 처리된 메시지 ID를 저장해서 재전달이 중복 부작용을 만들지 않도록 합니다.

조정(리컨실리에이션)은 당신의 기록과 외부 시스템이 불일치할 때 복구하는 방법입니다.

좋은 기본값:

• 보류 상태가 오래된 항목을 다시 확인하는 예약 작업
• 비교 단계(우리 상태 vs 제공자 상태)
• 수리 작업: 재시도, 취소, 환불, 또는 needs_review로 표시

결제, 이행, 구독 등 웹후크가 관련된 항목에는 필수적입니다.

중요합니다. 빠르게 만들더라도 네트워크 실패는 사라지지 않습니다.

Koder.ai로 서비스를 생성하는 경우에도 다음 기본을 초기에 포함하세요:

• 명확한 경계(언제 의도가 내구화되는지)
• "생성/캡처/환불" 스타일 작업에 대한 멱등성 핸들러
• 외부 참조와 함께 저장된 상관 ID
• 보류 레코드를 다시 확인하는 조정 작업

그러면 재시도와 중복 콜백이 비용이 큰 문제가 아니라 지루한 일상이 됩니다.