버그를 좁혀서 고치는 습관: API·DB·재시도 오류를 줄인 법
API 400·422, DB 마이그레이션, 백그라운드 재시도와 폴링, 청구 정산에서 반복해서 겪은 실패를 좁혀 고친 디버깅 습관을 정리했다.

혼자 서비스를 운영하다 같은 종류의 버그를 또 만나면, 지난번에 고쳤는데 왜 다시 막히는지 답답하다. 이번에도 처음부터 찾아야 할 것 같아 막막하다면 실패를 재현할 범위부터 좁혀 볼 수 있다. 이 글은 내가 이 블로그와 별개로 운영하는 서비스 한 곳의 수정 기록을 다룬다. API 요청 형식, DB 변경 순서, 완료 단계의 재실행 여부를 나눠 보면 각각 무엇을 확인해야 하는지 드러난다.
실패를 재현할 범위부터 좁힌다
이 서비스의 기록에는 API 오류, DB 마이그레이션, 백그라운드 재시도, 폴링과 청구 정산 문제가 남아 있다. API에서는 보낼 항목을 제한했고, DB에서는 변경 파일과 새 DB 구성 경로를 함께 맞췄다. 백그라운드 작업에서는 완료된 단계를 다시 실행하지 않도록 고쳤다. 이 조치들을 독자용 점검 순서로 정리하면, 오류가 난 경계에서 입력과 상태를 확인하는 방식이 된다.
오류를 숨기기 전에, 실패가 다시 드러나는 가장 작은 요청과 상태를 정한다.
성능 문제도 대상을 나눠 다뤘다. 상태를 주기적으로 확인하는 폴링은 초반에 촘촘히 확인하고 이후 간격을 늘리는 방식으로 바꿨다. 청구 정산은 외부 조회와 DB 쓰기를 분리해, 조회는 병렬로 처리하고 쓰기는 제공자별 순차 처리를 유지했다.
한 서비스에서 만난 실패 유형
이 서비스의 API 400·422 원인
이 서비스에서 다룬 400·422 사례는 외부로 보낸 요청이 상대 API의 계약과 어긋난 경우였다. 다른 모델용 필드나 화면 전용 설정이 요청에 섞였고, 주소 형식과 정해진 값 목록(enum)을 맞춰야 하는 문제도 있었다. 상태 코드만으로 원인을 확정하기보다 실제로 보낸 항목과 허용된 항목을 대조할 필요가 있었다.
요청 조립기는 모델별 허용 목록(allowlist)에 있는 항목만 담도록 바꿨다. 다른 제공자용 키와 화면 전용 키는 외부 호출 전에 걷어냈다. 화면이 들고 있는 설정 전체를 그대로 보내지 않도록 요청을 만드는 경계를 좁힌 것이다.
422 사례에서는 외부로 보내는 주소와 열거값을 확인했다. 앱 내부 상대 경로는 외부 호출에 쓸 수 있도록 완전한 주소로 정규화했다. 주소를 조립할 때 남은 공백이나 끝의 슬래시 때문에 유효한 URI가 되지 않는 사례도 기록에 있다. 워크플로가 만드는 값과 카탈로그 스키마의 URI·enum 필드를 맞추는 수정도 이 범위에 속한다.
DB 마이그레이션은 순서 문제로 본다
DB에서는 번호를 붙인 마이그레이션 파일만 추가했을 때 새로 만든 DB에 조회용 색인이 빠지는 문제가 있었다. 변경 파일, 실행 시점의 스키마 정의, 변경 이력, 재현 목록을 함께 맞춰야 했다. 기존 DB에 변경을 적용하는 경로와 새 DB를 구성하는 경로를 따로 살펴야 하는 이유다.
관련 테스트는 새 DB에서 변경 이력을 재현하는 경우와 기존 데이터가 있는 DB에 변경을 추가하는 경우를 다룬다. 재현 목록 자체에서도 위치를 기준으로 항목을 고르던 방식이 수정됐다. 목록 앞에 파일이 추가되면 필요한 변경이 빠질 수 있어, 파일 이름을 기준으로 선택하도록 바꾼 기록이다.
읽기 전용 경로에서는 구조 복구가 섞이지 않도록 하는 수정도 있었다. 조회 과정의 스키마 복구를 끄고, 일부 조회가 실패해도 기존 집계가 보이도록 대체 조회를 뒀다. DB 오류를 볼 때는 변경 순서뿐 아니라 읽기 경로가 구조 변경까지 맡고 있는지도 확인할 수 있다.
백그라운드 재시도는 중복 실행을 부른다
여러 단계로 나뉜 작업에서는 재시작할 때 이미 끝낸 단계를 다시 실행하는 문제가 있었다. 중간에 실패하기 전까지 성공한 단위를 저장하지 않으면, 재시도에서 같은 외부 호출과 과금이 반복됐다. 고친 방식은 완료된 단계를 건너뛰고, 단위별 성공 결과를 즉시 저장해 미완료 부분만 다시 실행하도록 하는 것이었다.
진행 기록(checkpoint)은 어디까지 끝났는지를 남기는 기준이다. 재시작 테스트는 이미 완료된 단계에서 제공자 호출 0회와 쓰기 0회를 확인하도록 작성돼 있다. 이는 테스트에 적힌 확인 조건이며, 이 글에서 새로 실행해 얻은 결과는 아니다.
결과를 재사용할 수 있는지는 입력값의 스냅샷과 지문값을 함께 보고 판단했다. 문자열 하나만 비교하면 달라진 입력을 같은 것으로 취급할 수 있기 때문이다. 같은 질문을 다른 백그라운드 작업에 적용한다면, 완료된 일을 다시 하고 있는지와 재사용 판단에 필요한 입력이 보존됐는지부터 확인할 수 있다.
주기적 확인 간격과 정산 병목은 다른 문제다
기존 폴링은 2초 간격으로 최대 900회 상태를 확인했다. 변경된 방식은 500ms에서 시작해 대기 간격을 지수적으로 늘리고, 상한은 30초로 두었다. 여기에 ±10%의 무작위 변동인 지터를 더했다. 수정 기록에는 30분 작업 기준으로 폴링 횟수가 약 93% 줄었다고 남아 있다.
이 수치가 말하는 것은 해당 조건에서의 상태 확인 횟수다. 초반에는 짧은 간격으로 확인하고 작업이 길어질수록 확인 빈도를 낮추는 방식이다. 작업 자체의 처리 시간이나 사용자가 느낀 대기 시간까지 줄었다는 뜻으로 넓혀 읽어서는 안 된다.
청구 정산에서는 제공자별 청구 조회를 순차 처리에서 병렬 처리로 바꿨다. 반면 DB에 값이 있으면 갱신하고 없으면 추가하는 작업과 사용량 맞춤은 제공자별 순차 처리를 유지했다. 저장소의 쓰기 충돌을 피하기 위한 구분이었다. 같은 정산 안에서도 외부 응답을 기다리는 부분과 저장소를 바꾸는 부분을 다르게 다뤘다.
테스트는 실패 지점에 맞춰 좁힌다
여기서 실패 지점에 가깝다는 말은 테스트가 확인할 동작의 범위를 뜻한다. 요청 오류라면 요청 조립 결과를, 마이그레이션이라면 변경 이력 재현을 확인하는 식이다. 폴링과 청구 정산 변경에는 대기 간격이 늘어나는 경로와 병렬 조회를 다루는 회귀 테스트가 추가됐다. 이 글은 수정 기록과 테스트에 적힌 조건을 설명하며, 해당 테스트를 실행한 결과를 제시하는 글은 아니다.
테스트 실행 명령도 확인 대상이다. 기록에는 패키지 관리 도구를 거치지 않고 테스트 실행 파일을 직접 호출한 명령이 남아 있다. 잠금 파일이나 작업 영역 설정이 의도치 않게 달라진 별도 기록도 있어, 검증 명령이 주변 파일까지 바꾸는지 살펴볼 필요가 있다.
배포 결과나 화면 하나가 뜬다는 사실만으로 전체 흐름을 검증했다고 판단할 수는 없다. 이는 이 기록에서 도출한 점검 기준이다. 실행하지 못한 검사는 남은 확인으로 구분하고, 실패한 조건을 약하게 바꾸기 전에 준비 데이터와 초기 설정부터 대조한다.
다음 버그에 바로 쓰는 체크리스트
아래 표는 이 서비스의 수정 기록에서 정리한 독자용 점검 순서다. 혼자 서비스를 운영하며 비슷한 증상을 만났을 때, 먼저 확인할 경계를 고르는 데 쓸 수 있다. 각 대응은 자신의 요청과 데이터 상태로 재현해 확인할 항목이다.
| 증상 | 먼저 확인할 것 | 대응과 검증 범위 |
|---|---|---|
| API 400 | 화면 전용 값, 다른 모델·제공자용 항목 | 허용 목록으로 요청을 조립하고 실제 전송 항목 확인 |
| API 422 | 주소 형식과 정해진 값 목록 | 주소 정규화와 스키마의 URI·enum 필드 대조 |
| 새 DB 구성 실패 | 변경 순서, 기존 데이터, 색인 생성 경로 | 새 DB 재현과 기존 데이터 변경을 각각 검사 |
| 백그라운드 재시작 | 완료 상태, 진행 기록, 입력 스냅샷 | 완료 단계 건너뛰기와 성공 단위의 즉시 저장 확인 |
| 긴 작업의 상태 확인 부하 | 고정 간격과 호출 횟수 | 짧은 초기 간격, 점진적 증가, 상한과 지터 설정 |
| 청구 정산 지연 | 외부 조회와 DB 쓰기의 처리 순서 | 조회는 병렬 처리하고 DB 쓰기·맞춤은 제공자별 순차 유지 |
다음 버그에서는 이 표에서 해당하는 경계를 골라 실제 요청이나 완료 상태부터 대조할 수 있다. 재현 조건을 정한 뒤에는 그 조건을 확인하는 테스트와 수정 범위를 연결한다. 관련 개발 글은 프로그래밍 카테고리에서 볼 수 있다.
자주 묻는 질문
API 400이나 422가 나면 다른 서비스로 우회하는 것이 먼저인가요?
먼저 오류 응답과 실제 요청을 대조한다. 이 서비스에서는 허용 목록으로 보낼 항목을 제한하고, 화면 전용 설정·다른 제공자용 값·주소 형식·열거값을 확인했다. 대체 경로를 늘리기 전에 해당 요청을 재현하는 테스트 조건을 정리할 수 있다.
DB 마이그레이션은 새 데이터베이스에서만 재현하면 충분한가요?
아니다. 새 DB 재현뿐 아니라 기존 데이터가 있는 DB에서도 추가 변경이 안전해야 한다. 원본 파일·실행 시점·변경 이력·색인 생성 순서를 함께 보고, 읽기 전용 경로에서는 구조 복구가 섞이지 않게 해야 한다.
폴링과 정산 지연은 같은 동시 처리 전략으로 줄일 수 있나요?
이 사례에서는 두 문제를 다르게 다뤘다. 폴링은 초기에 짧게 시작해 점차 간격을 늘리고 지터를 더했다. 청구 정산에서는 외부 조회를 병렬로 처리하고, DB 갱신과 사용량 맞춤은 쓰기 충돌을 피하도록 제공자별 순차 처리를 유지했다.
아직 댓글이 없습니다.