혼자 API 개발할 때 원인을 좁히는 법

혼자 개발할 때 API 문제는 화면만 봐서는 해결되지 않는다. 백엔드는 돌아가는데 화면에만 응답이 안 나타나거나, 요청은 성공했는데 데이터가 이상한 경우가 자주 생긴다.

핵심은 한 가지만 의심하지 말고 요청·응답·로그를 함께 보면서 원인을 좁혀나가는 것이다. 나는 보통 이 순서로 확인한다: 재현 조건 → 응답 body → 로그 → 설정.

먼저 응답 body를 확인한다

문제가 생기면 나는 즉시 curl로 실제 응답을 본다. 화면의 에러 메시지는 이미 가공된 것이고, API 응답이 정말 뭔지 모르니까다.

curl -i 'https://example.com/api/items?page=1'

이 커맨드로 status code와 response body를 함께 본다. 200이 나오는데 data 필드가 null일 수도 있고, 예상과 다른 구조일 수도 있다. 이 순간 화면의 "로딩 실패"와 실제 API의 동작이 일치하는지 판단할 수 있다.

정상 상태와 비교해본다

응답을 본 후엔 반드시 "정상일 때는 뭐였지?" 하고 이전 요청과 비교한다. 보통 같은 엔드포인트에 다른 파라미터를 넘겨본다.

• 같은 page로 두 번 요청하면 같은 응답이 나오는가
• status code는 200인데 body의 특정 필드가 없는가
• 401이 나왔다면 인증 상태부터 확인해야 한다

정상 상황을 명확히 정의하지 않으면 "이게 맞는 건가?" 하고 헤맨다.

로그에서 바뀐 부분을 찾는다

응답이 의도와 다르면 백엔드 로그를 본다. 보통 다음을 확인한다:

1. 요청이 서버에 도착했는가 (진짜 요청을 받았나)
2. 데이터베이스 쿼리는 실행됐는가 (rows returned: 0 같은 메시지)
3. 에러가 발생했다면 어디서인가 (exception stack trace)

이 세 가지만 봐도 화면의 "로딩 실패"가 실은 쿼리가 아무것도 반환하지 않았기 때문인지, 아니면 응답 변환 과정에서 실패한 건지 알 수 있다.

환경 차이를 의심한다

"로컬에서는 되는데..." 하는 상황이 자주 생긴다. 이때 체크할 것:

• DATABASE_URL이 정말 로컬 DB를 가리키는가
• 타임존 설정이 다르지 않은가 (날짜 필터링할 때)
• 로컬과 서버의 데이터 상태가 다르지 않은가

환경마다 기록을 남겨두면 나중에 "어? 이전엔 이렇게 했는데?" 할 때 도움이 된다.

마지막에 기록을 남긴다

문제를 해결한 후 중요한 건 "뭘 바꿨는가"를 기억하는 것이다. 나는 다음을 짧게라도 남긴다:

• 실제 증상: 응답이 빈 배열
• 원인: where 절 조건이 모든 행을 제외함
• 해결: filter 로직을 수정해서 active=true인 항목도 포함

이렇게 기록해두면 다음에 비슷한 문제가 나올 때 빠르게 판단할 수 있다.