파일 업로드 API가 생각하는 대로 작동하지 않을 때

파일 업로드 기능은 클라이언트와 서버 양쪽을 모두 봐야 한다. 사용자가 보는 화면의 상태와 백엔드가 받는 요청이 다를 수 있기 때문이다.

사용자 입장에서 먼저 보기

먼저 사용자가 보는 화면에서 뭐가 문제인지 명확히 한다. 버튼이 비활성화되는가, 에러 메시지가 나타나는가, 아니면 아무 반응이 없는가. 화면의 상태를 먼저 파악해야 백엔드 문제와 프론트엔드 문제를 구분할 수 있다.

개발자 도구에서 네트워크 요청 확인하기

브라우저의 개발자 도구 → 네트워크 탭을 열어서 파일 업로드 요청을 본다:

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

이 명령처럼 실제 요청의 헤더와 응답을 확인할 수 있다. 파일 업로드는 multipart/form-data 형식으로 전송되는데, 이것이 제대로 되는지 봐야 한다.

인증 상태 확인

파일 업로드 API는 대부분 인증이 필요하다. 사용자가 로그인됐는가, 토큰이 유효한가를 먼저 확인한다. 인증이 없으면 401이나 403 에러가 나타난다.

• 요청 헤더에 토큰이 제대로 들어가는가
• 토큰의 형식은 맞는가 (Bearer token 등)
• 토큰이 만료되지 않았는가

요청 파라미터 확인

파일 업로드 요청에 필수 파라미터가 모두 포함됐는가 확인한다. 때로는 파일만 보내는 게 아니라 제목, 설명 같은 추가 정보도 함께 보내야 한다.

응답 분석

업로드 후 서버의 응답을 확인한다:

• 상태 코드가 201(생성됨) 또는 200(성공)인가
• 응답에 파일 URL이나 ID가 포함되는가
• 에러 메시지가 있다면 정확히 뭐라고 하는가

서버 로그 확인

ローカル開発중には백엔드 서버의 로그도 함께 본다. 요청이 정말 도착했는가, 어느 부분에서 실패했는가를 로그에서 확인할 수 있다.

체크리스트

파일 업로드 문제를 진단할 때:

1. 사용자가 보는 화면의 상태를 정확히 설명한다.
2. 네트워크 요청과 응답을 기록한다.
3. 인증 상태를 확인한다.
4. 요청 파라미터 하나씩을 검증한다.

작은 확인들이 모이면 문제의 정확한 위치를 찾을 수 있다.