파일 업로드 API를 검증하는 체크리스트

파일 업로드를 다룰 때 검색으로 찾은 코드를 바로 복사하면 안 된다. 요청과 응답의 흐름이 복잡하기 때문에 단계적으로 검증해야 한다.

요청 파라미터부터 확인하기

API 파일 업로드 문제는 화면만 보고 판단하면 놓치는 값이 많다. 실제 요청이 어떻게 이루어지는지 확인해야 한다.

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

POST 요청의 헤더, body, 응답 status code를 함께 확인하면 문제가 어디에 있는지 빠르게 좁혀진다.

인증 상태 먼저 확인하기

파일 업로드 문제가 자주 반복된다면 확인 순서를 고정해두는 게 낫다. 대부분의 경우 인증 상태가 애매하거나 요청 파라미터가 빠져 있다.

• 먼저 볼 것: 요청의 인증 헤더와 파라미터
• 같이 비교할 것: 정상일 때의 요청/응답 형식
• 기록해둘 것: 요청 헤더, content-type, 파일 크기

브라우저 개발자 도구로 직접 보기

서버에서 파일을 받았는지 확인하려면 실제 요청과 응답을 봐야 한다. 브라우저의 Network 탭에서 파일 업로드 요청을 확인할 수 있다.

단계별로 검증하기

파일 업로드 문제는 한 가지 원인만 있는 경우가 드물다.

1. 같은 환경에서 증상을 재현해본다
2. 로그나 응답에서 바뀐 부분을 한 줄로 정리한다
3. 실제 서버에서 파일이 올바르게 저장되었는지 최종 확인한다

다음 작업을 위해 기록하기

결과가 바뀐 이유를 로그와 응답으로 설명할 수 있으면 충분히 정리된 것이다. 어떤 요청이 실패했는지, 어떤 응답을 받았는지 기록해두면 다음 수정이 훨씬 빨라진다.