API에서 대량 파일 업로드를 처리할 때 배포 전 확인

사용자가 여러 파일을 한 번에 업로드할 때, API 응답이 느리거나 에러가 나는 경우가 많다.

실제 API 응답을 확인한다

curl -i 'https://example.com/api/upload' \
  -F 'file=@/path/to/large-file.zip'

HTTP 상태 코드, 응답 시간, 에러 메시지를 본다. 특히 timeout이 나는지, 413 (Payload Too Large) 에러가 나는지 확인한다.

서버의 파일 업로드 크기 제한을 확인한다

Nginx, Apache 등 웹 서버에서 업로드 크기 제한을 둔다:

client_max_body_size 100M;  # nginx
LimitRequestBody 104857600  # apache

애플리케이션 레벨에서도 제한이 있을 수 있다. 예를 들어 Node.js express는:

app.use(express.json({ limit: '100mb' }));
app.use(express.urlencoded({ limit: '100mb' }));

타임아웃을 확인한다

대용량 파일 업로드는 시간이 걸린다. 기본 타임아웃 (보통 30초)을 초과하면 업로드가 중단된다.

server.timeout = 300000; // 5분

API 엔드포인트마다 다른 타임아웃을 설정할 수도 있다.

디스크 공간과 메모리를 점검한다

df -h
free -h

파일이 메모리에 전부 로드된 후 저장되는 방식이면, 메모리 부족으로 실패할 수 있다. 파일을 청크(chunk) 단위로 받아서 바로 디스크에 저장하는 방식이 더 효율적이다.

상태 코드와 응답을 기록한다

SELECT status_code, COUNT(*) FROM api_logs
WHERE endpoint = '/api/upload' AND timestamp > NOW() - INTERVAL '1 hour'
GROUP BY status_code;

업로드 실패가 계속되는지, 특정 파일 크기에서만 실패하는지 추적한다.

클라이언트에서의 분할 업로드를 고려한다

매우 큰 파일은 여러 부분으로 나눠서 업로드하는 게 안정적이다. 이렇게 하면 각 부분이 실패해도 다시 보낼 수 있고, 전체 업로드를 다시 시작할 필요가 없다.