📁 Request Files – 파일 업로드

웹 애플리케이션에서 파일 업로드는 선택 기능이 아니다.

프로필 이미지, 첨부 파일, 문서 업로드, 이미지 분석, 머신러닝 데이터 수집까지 현대 웹 서비스의 거의 모든 영역에서 사용된다.

이번 글에서는 FastAPI에서 파일 업로드가 어떻게 동작하는지, 왜 UploadFile을 써야 하는지, 그리고 실무에서 반드시 알아야 할 핵심 개념만 정리한다.

---

📌 1. 파일 업로드의 본질

파일 업로드는 단순히 “데이터 하나 보내기”가 아니다.

파일은 다음과 같은 특징을 가진다.

• 텍스트가 아니라 바이너리 데이터다
• 용량이 클 수 있다
• 파일명, 타입 같은 메타데이터가 중요하다

그래서 파일 업로드는 JSON이나 Query Parameter로 처리할 수 없다.

---

⚙️ 2. 패키지 설치

FastAPI에서 파일 업로드를 처리하려면 python-multipart 패키지가 필수다.

pip install python-multipart

이 패키지는 요청을 다음처럼 처리한다.

• multipart/form-data 요청 파싱
• 파일과 텍스트 필드 분리
• FastAPI 파라미터로 주입

---

📂 3. FastAPI에서 파일 받는 두 가지 방법

FastAPI는 파일을 받는 방식을 의도적으로 두 가지 제공한다.

① bytes 방식

from typing import Annotated
from fastapi import FastAPI, File

app = FastAPI()

@app.post("/files/")
async def create_file(
    file: Annotated[bytes, File()]
):
    return {"file_size": len(file)}

이 방식의 특징은 명확하다.

• 파일 전체가 메모리에 로드됨
• 구현은 단순
• 작은 파일에만 적합

---

② UploadFile 방식 (권장)

from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

이 방식이 실무 표준!

• 파일을 바로 메모리에 올리지 않음
• 자동으로 임시 파일 관리
• 파일 메타데이터 제공

---

📊 bytes vs UploadFile 비교

구분	bytes	UploadFile
메모리 사용	파일 전체	필요한 만큼만
대용량 파일	❌ 위험	✅ 안전
메타데이터	없음	파일명, 타입 제공
실무 적합성	낮음	매우 높음

---

🧠 4. multipart/form-data의 동작 원리

파일 업로드 요청은 내부적으로 이렇게 흘러간다.

[브라우저 파일 선택]
        ↓
POST 요청: Content-Type: multipart/form-data
        ↓
python-multipart 파싱
        ↓
파일 / 텍스트 분리
        ↓
FastAPI 파라미터 주입

이때 중요한 규칙이 하나 있다.

이건 FastAPI 제약이 아니라 HTTP 프로토콜 규칙

---

📦 5. UploadFile 객체 완전 해부

🔹 UploadFile 속성 (Attributes)

@app.post("/upload/")
async def upload(file: UploadFile):
    print(file.filename)
    print(file.content_type)
    print(file.file)

속성	설명
filename	원본 파일명
content_type	MIME 타입 (image/png, application/pdf 등)
file	SpooledTemporaryFile 객체

🔹 UploadFile 메서드 (Methods)

모든 메서드는 async다.

@app.post("/upload/")
async def upload(file: UploadFile):
    contents = await file.read()
    await file.seek(0)
    contents_again = await file.read()
    await file.close()

메서드	역할
read()	파일 읽기
seek(0)	읽기 위치 초기화
close()	파일 닫기

---

📌 6. 실무에서 꼭 알아야 할 패턴

✔ 선택적 파일 업로드

@app.post("/upload/")
async def upload(file: UploadFile | None = None):
    if not file:
        return {"message": "파일이 없습니다"}
    return {"filename": file.filename}

핵심은 두 가지다.

• | None → 타입 힌트
• = None → 기본값

---

✔ 다중 파일 업로드

@app.post("/uploadfiles/")
async def upload_files(files: list[UploadFile]):
    return {
        "filenames": [file.filename for file in files]
    }

HTML에서는 multiple 속성이 필요하다.

<input type="file" name="files" multiple>

---

📌 Form Data의 핵심 역할

Form Data는 다음 문제를 해결하기 위해 존재한다.

• 파일은 바이너리 데이터다
• JSON은 바이너리에 적합하지 않다
• 텍스트 + 파일을 같이 보내야 하는 경우가 많다

그래서 HTTP는 파일 전송을 위해 multipart/form-data라는 인코딩 방식을 제공한다.

🔁 multipart/form-data 요청 흐름

파일 업로드가 포함된 요청은 내부적으로 다음 순서로 처리된다.

[클라이언트 (브라우저)]
    │
    │  파일 선택
    ▼
POST 요청
Content-Type: multipart/form-data
    │
    ▼
python-multipart
(요청 파싱)
    │
    ├─ 텍스트 필드
    └─ 파일 데이터
    │
    ▼
FastAPI
(File / UploadFile)

---

✅ 핵심 정리

• 파일 업로드는 multipart/form-data로 처리된다
• JSON Body와 File/Form은 동시에 사용할 수 없다
• 실무에서는 UploadFile이 표준이다
• 메모리, 성능, 안정성을 모두 고려해야 한다