FastAPI 파일 업로드 마스터하기: 멀티파트 폼 처리 심층 분석

현대 웹 애플리케이션에서 파일 업로드 처리 기능은 필수적인 요구사항입니다. 사용자가 프로필 사진을 제출하든, 처리를 위해 문서를 업로드하든, 공유를 위해 미디어를 올리든, 견고하고 효율적인 파일 업로드 메커니즘은 매우 중요합니다. 고성능 파이썬 웹 프레임워크인 FastAPI는 이 분야에서 탁월하며, HTTP를 통해 파일을 전송하는 표준 방식인 멀티파트 폼 데이터를 관리하는 간소화된 방법을 제공합니다. 이 종합 가이드는 기본적인 구현부터 고급 고려사항까지 FastAPI 파일 업로드의 복잡한 부분을 안내하여, 여러분이 글로벌 사용자를 위한 강력하고 확장 가능한 API를 자신 있게 구축할 수 있도록 보장합니다.

멀티파트 폼 데이터 이해하기

FastAPI의 구현에 대해 알아보기 전에, 멀티파트 폼 데이터가 무엇인지 이해하는 것이 중요합니다. 웹 브라우저가 파일을 포함한 폼을 제출할 때, 일반적으로 enctype="multipart/form-data" 속성을 사용합니다. 이 인코딩 유형은 폼 제출을 여러 부분(part)으로 나누며, 각 부분은 고유한 콘텐츠 유형과 처리 정보를 가집니다. 이를 통해 텍스트 필드, 비텍스트 필드, 바이너리 파일을 포함한 다양한 유형의 데이터를 단일 HTTP 요청 내에서 전송할 수 있습니다.

멀티파트 요청의 각 부분은 다음으로 구성됩니다:

• Content-Disposition 헤더: 폼 필드의 이름(name)과 파일의 경우 원본 파일 이름(filename)을 지정합니다.
• Content-Type 헤더: 해당 부분의 MIME 유형을 나타냅니다 (예: text/plain, image/jpeg).
• Body: 해당 부분의 실제 데이터입니다.

FastAPI의 파일 업로드 접근 방식

FastAPI는 파이썬의 표준 라이브러리를 활용하며 데이터 유효성 검사를 위해 Pydantic과 원활하게 통합됩니다. 파일 업로드를 위해 fastapi 모듈의 UploadFile 타입을 사용합니다. 이 클래스는 업로드된 파일 데이터에 접근하기 위한 편리하고 안전한 인터페이스를 제공합니다.

기본 파일 업로드 구현

단일 파일 업로드를 수락하는 FastAPI 엔드포인트를 만드는 간단한 예제부터 시작하겠습니다. fastapi의 File 함수를 사용하여 파일 매개변수를 선언할 것입니다.

            from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/files/")
async def create_file(file: UploadFile):
    return {"filename": file.filename, "content_type": file.content_type}

            

              
                Copy
              
            
          

이 예제에서:

• FastAPI, File, UploadFile을 임포트합니다.
• /files/ 엔드포인트는 POST 요청으로 정의됩니다.
• file 매개변수는 UploadFile로 타입 힌트가 지정되어, 파일 업로드를 예상한다는 것을 의미합니다.
• 엔드포인트 함수 내에서, 업로드된 파일의 filename이나 content_type과 같은 속성에 접근할 수 있습니다.

클라이언트가 /files/로 파일을 첨부하여 POST 요청을 보내면(일반적으로 enctype="multipart/form-data"를 사용한 폼을 통해), FastAPI는 자동으로 파싱을 처리하고 UploadFile 객체를 제공합니다. 그러면 이 객체와 상호작용할 수 있습니다.

업로드된 파일 저장하기

종종 업로드된 파일을 디스크에 저장하거나 그 내용을 처리해야 할 필요가 있습니다. UploadFile 객체는 이를 위한 메서드를 제공합니다:

• read(): 파일의 전체 내용을 메모리에 바이트로 읽어들입니다. 작은 파일에 사용하세요.
• write(content: bytes): 파일에 바이트를 씁니다.
• seek(offset: int): 현재 파일 위치를 변경합니다.
• close(): 파일을 닫습니다.

특히 대용량 파일을 다루거나 I/O 바운드 작업을 처리할 때 파일 작업을 비동기적으로 처리하는 것이 중요합니다. FastAPI의 UploadFile은 비동기 작업을 지원합니다.

            from fastapi import FastAPI, File, UploadFile
import shutil

app = FastAPI()

@app.post("/files/save/")
async def save_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
    return {"info": f"file '{file.filename}' saved at '{file_location}'"}

            

              
                Copy
              
            
          

이 향상된 예제에서:

• File(...)을 사용하여 이 매개변수가 필수임을 나타냅니다.
• 파일이 저장될 로컬 경로를 지정합니다. uploads 디렉토리가 존재하는지 확인하세요.
• 대상 파일을 바이너리 쓰기 모드("wb+")로 엽니다.
• await file.read()를 사용하여 업로드된 파일의 내용을 비동기적으로 읽고 로컬 파일에 씁니다.

참고: await file.read()로 전체 파일을 메모리에 읽는 것은 매우 큰 파일의 경우 문제가 될 수 있습니다. 그런 시나리오에서는 파일 콘텐츠를 스트리밍하는 것을 고려하세요.

파일 콘텐츠 스트리밍하기

대용량 파일의 경우, 전체 내용을 메모리로 읽으면 과도한 메모리 소비와 잠재적인 메모리 부족 오류로 이어질 수 있습니다. 더 메모리 효율적인 접근 방식은 파일을 청크 단위로 스트리밍하는 것입니다. shutil.copyfileobj 함수는 이를 위해 훌륭하지만, 비동기 작업을 위해 조정할 필요가 있습니다.

            from fastapi import FastAPI, File, UploadFile
import aiofiles # Install using: pip install aiofiles

app = FastAPI()

@app.post("/files/stream/")
async def stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        content = await file.read()
        await out_file.write(content)
    return {"info": f"file '{file.filename}' streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

aiofiles를 사용하면 전체 파일을 한 번에 메모리에 로드하지 않고도 업로드된 파일의 내용을 대상 파일로 효율적으로 스트리밍할 수 있습니다. 이 문맥에서 await file.read()는 여전히 전체 파일을 읽지만, aiofiles가 쓰기를 더 효율적으로 처리합니다. UploadFile을 사용한 진정한 청크 단위 스트리밍을 위해서는 일반적으로 await file.read(chunk_size)를 반복하지만, aiofiles.open과 await out_file.write(content)는 저장을 위한 일반적이고 성능이 좋은 패턴입니다.

청킹을 사용한 더 명시적인 스트리밍 접근 방식은 다음과 같습니다:

            from fastapi import FastAPI, File, UploadFile
import aiofiles

app = FastAPI()

CHUNK_SIZE = 1024 * 1024 # 1MB chunk size

@app.post("/files/chunked_stream/")
async def chunked_stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        while content := await file.read(CHUNK_SIZE):
            await out_file.write(content)
    return {"info": f"file '{file.filename}' chunked streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

이 chunked_stream_file 엔드포인트는 파일을 1MB 청크 단위로 읽고 각 청크를 출력 파일에 씁니다. 이는 잠재적으로 매우 큰 파일을 처리하는 가장 메모리 효율적인 방법입니다.

다중 파일 업로드 처리하기

웹 애플리케이션은 종종 사용자가 여러 파일을 동시에 업로드하도록 요구합니다. FastAPI는 이를 간단하게 만듭니다.

파일 목록 업로드하기

매개변수에 UploadFile의 리스트로 타입 힌트를 지정하여 파일 목록을 받을 수 있습니다.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/multiple/")
async def create_multiple_files(
    files: List[UploadFile] = File(...)
):
    results = []
    for file in files:
        # Process each file, e.g., save it
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {"files_processed": results}

            

              
                Copy
              
            
          

이 시나리오에서 클라이언트는 동일한 폼 필드 이름(예: `files`)으로 여러 파트를 보내야 합니다. FastAPI는 이를 UploadFile 객체의 파이썬 리스트로 수집합니다.

파일과 다른 폼 데이터 혼합하기

폼이 파일 필드와 일반 텍스트 필드를 모두 포함하는 것은 흔한 일입니다. FastAPI는 다른 매개변수를 표준 타입 힌트와 함께, 파일이 아닌 폼 필드에 대해서는 Form을 사용하여 선언함으로써 이를 처리합니다.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/mixed/")
async def upload_mixed_data(
    description: str = Form(...),
    files: List[UploadFile] = File(...) # Accepts multiple files with the name 'files'
):
    results = []
    for file in files:
        # Process each file
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {
        "description": description,
        "files_processed": results
    }

            

              
                Copy
              
            
          

Swagger UI나 Postman과 같은 도구를 사용할 때, description을 일반 폼 필드로 지정한 다음 files 필드에 대해 여러 파트를 추가하고 각 파트의 콘텐츠 타입을 적절한 이미지/문서 유형으로 설정합니다.

고급 기능 및 모범 사례

기본적인 파일 처리 외에도, 견고한 파일 업로드 API를 구축하기 위해 몇 가지 고급 기능과 모범 사례가 중요합니다.

파일 크기 제한

무제한 파일 업로드를 허용하면 서비스 거부(DoS) 공격이나 과도한 리소스 소비로 이어질 수 있습니다. FastAPI 자체는 프레임워크 수준에서 기본적으로 엄격한 제한을 강제하지 않지만, 다음과 같은 검사를 구현해야 합니다:

• 애플리케이션 레벨에서: 파일을 받은 후 처리하거나 저장하기 전에 파일 크기를 확인합니다.
• 웹 서버/프록시 레벨에서: 웹 서버(예: Nginx, 워커를 사용하는 Uvicorn)를 구성하여 특정 페이로드 크기를 초과하는 요청을 거부하도록 합니다.

애플리케이션 레벨 크기 검사 예제:

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

MAX_FILE_SIZE_MB = 10
MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024

@app.post("/files/limited_size/")
async def upload_with_size_limit(file: UploadFile = File(...)):
    if len(await file.read()) > MAX_FILE_SIZE_BYTES:
        raise HTTPException(status_code=400, detail=f"File is too large. Maximum size is {MAX_FILE_SIZE_MB}MB.")
    
    # Reset file pointer to read content again
    await file.seek(0)
    
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully."}

            

              
                Copy
              
            
          

중요: 파일 크기를 확인하기 위해 파일을 읽은 후, 내용을 다시 읽으려면(예: 저장하기 위해) await file.seek(0)을 사용하여 파일 포인터를 처음으로 재설정해야 합니다.

허용되는 파일 유형 (MIME 타입)

특정 파일 유형으로 업로드를 제한하면 보안이 강화되고 데이터 무결성이 보장됩니다. UploadFile 객체의 content_type 속성을 확인할 수 있습니다.

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

ALLOWED_FILE_TYPES = {"image/jpeg", "image/png", "application/pdf"}

@app.post("/files/restricted_types/")
async def upload_restricted_types(file: UploadFile = File(...)):
    if file.content_type not in ALLOWED_FILE_TYPES:
        raise HTTPException(status_code=400, detail=f"Unsupported file type: {file.content_type}. Allowed types are: {', '.join(ALLOWED_FILE_TYPES)}")
        
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully and is of an allowed type."}

            

              
                Copy
              
            
          

MIME 타입은 때때로 위조될 수 있으므로, 특히 이미지의 경우 더 강력한 타입 검사를 위해 Pillow와 같은 라이브러리를 사용하여 파일의 실제 내용을 검사하는 것을 고려할 수 있습니다.

오류 처리 및 사용자 피드백

사용자에게 명확하고 실행 가능한 오류 메시지를 제공하세요. 표준 HTTP 오류 응답을 위해 FastAPI의 HTTPException을 사용합니다.

• 파일 없음/누락: 필수 파일 매개변수가 전송되지 않은 경우.
• 파일 크기 초과: 크기 제한 예제에서 보여준 경우.
• 잘못된 파일 유형: 유형 제한 예제에서 보여준 경우.
• 서버 오류: 파일 저장 또는 처리 중 문제 발생 시 (예: 디스크 공간 부족, 권한 오류).

보안 고려사항

파일 업로드는 보안 위험을 초래합니다:

• 악성 파일: 실행 파일(.exe, .sh)이나 다른 파일 유형으로 위장한 스크립트를 업로드하는 경우. 항상 파일 유형을 검증하고 업로드된 파일의 악성 코드 검사를 고려하세요.
• 경로 탐색(Path Traversal): 파일 이름을 삭제/정리(sanitize)하여 공격자가 의도하지 않은 디렉토리에 파일을 업로드하는 것을 방지하세요(예: ../../etc/passwd 같은 파일 이름 사용). FastAPI의 UploadFile은 기본적인 파일 이름 삭제/정리를 처리하지만, 추가적인 주의가 현명합니다.
• 서비스 거부(Denial of Service): 파일 크기 제한을 구현하고 업로드 엔드포인트에 속도 제한(rate limiting)을 적용할 수 있습니다.
• 크로스 사이트 스크립팅(XSS): 파일 이름이나 파일 내용을 웹 페이지에 직접 표시하는 경우, XSS 공격을 방지하기 위해 적절히 이스케이프 처리되었는지 확인하세요.

모범 사례: 업로드된 파일은 웹 서버의 문서 루트(document root) 외부에 저장하고, 적절한 접근 제어가 있는 전용 엔드포인트를 통해 제공하거나 콘텐츠 전송 네트워크(CDN)를 사용하세요.

Pydantic 모델과 파일 업로드 함께 사용하기

UploadFile이 파일을 위한 주요 타입이지만, 더 복잡한 데이터 구조를 위해 파일 업로드를 Pydantic 모델에 통합할 수 있습니다. 그러나 표준 Pydantic 모델 내의 직접적인 파일 업로드 필드는 멀티파트 폼에서 기본적으로 지원되지 않습니다. 대신, 일반적으로 파일을 별도의 매개변수로 받은 다음, Pydantic 모델에 의해 저장되거나 유효성 검사를 받을 수 있는 형식으로 처리합니다.

일반적인 패턴은 메타데이터를 위한 Pydantic 모델을 가지고 파일을 별도로 받는 것입니다:

            from fastapi import FastAPI, File, UploadFile, Form
from pydantic import BaseModel
from typing import Optional

class UploadMetadata(BaseModel):
    title: str
    description: Optional[str] = None

app = FastAPI()

@app.post("/files/model_metadata/")
async def upload_with_metadata(
    metadata: str = Form(...), # Receive metadata as a JSON string
    file: UploadFile = File(...)
):
    import json
    try:
        metadata_obj = UploadMetadata(**json.loads(metadata))
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON format for metadata")
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Error parsing metadata: {e}")

    # Now you have metadata_obj and file
    # Proceed with saving file and using metadata
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())

    return {
        "message": "File uploaded successfully with metadata",
        "metadata": metadata_obj,
        "filename": file.filename
    }

            

              
                Copy
              
            
          

이 패턴에서 클라이언트는 메타데이터를 폼 필드(예: metadata) 내의 JSON 문자열로 보내고, 파일은 별도의 멀티파트 파트로 보냅니다. 그러면 서버는 JSON 문자열을 Pydantic 객체로 파싱합니다.

대용량 파일 업로드와 청킹

매우 큰 파일(예: 기가바이트 단위)의 경우 스트리밍조차도 웹 서버나 클라이언트 측의 제한에 부딪힐 수 있습니다. 더 고급 기술은 청크 업로드(chunked uploads)로, 클라이언트가 파일을 작은 조각으로 나누어 순차적으로 또는 병렬로 업로드하는 방식입니다. 그러면 서버는 이 청크들을 재조립합니다. 이는 일반적으로 사용자 정의 클라이언트 측 로직과 청크 관리를 위해 설계된 서버 엔드포인트(예: 청크 식별, 임시 저장, 최종 조립)가 필요합니다.

FastAPI가 클라이언트 주도 청크 업로드에 대한 내장 지원을 제공하지는 않지만, FastAPI 엔드포인트 내에서 이 로직을 구현할 수 있습니다. 이는 다음과 같은 엔드포인트를 만드는 것을 포함합니다:

• 개별 파일 청크를 수신합니다.
• 이 청크들을 임시로 저장하며, 순서와 총 청크 수를 나타내는 메타데이터를 함께 저장할 수 있습니다.
• 모든 청크가 업로드되었을 때 신호를 보내 재조립 프로세스를 트리거하는 엔드포인트나 메커니즘을 제공합니다.

이는 더 복잡한 작업이며 종종 클라이언트 측에 JavaScript 라이브러리가 필요합니다.

국제화 및 세계화 고려사항

글로벌 사용자를 위한 API를 구축할 때 파일 업로드는 특별한 주의가 필요합니다:

• 파일 이름: 전 세계 사용자는 파일 이름에 비 ASCII 문자(예: 악센트, 표의 문자)를 사용할 수 있습니다. 시스템이 이러한 파일 이름을 올바르게 처리하고 저장하는지 확인하세요. UTF-8 인코딩이 일반적으로 표준이지만, 깊은 호환성을 위해서는 신중한 인코딩/디코딩 및 삭제/정리가 필요할 수 있습니다.
• 파일 크기 단위: MB와 GB가 일반적이지만, 사용자가 파일 크기를 어떻게 인식하는지 유의하세요. 사용자 친화적인 방식으로 제한을 표시하는 것이 중요합니다.
• 콘텐츠 유형: 사용자는 덜 일반적인 MIME 유형의 파일을 업로드할 수 있습니다. 허용된 유형 목록이 사용 사례에 충분히 포괄적이거나 유연한지 확인하세요.
• 지역 규정: 다른 국가의 데이터 상주 법률 및 규정에 유의하세요. 업로드된 파일을 저장하려면 이러한 규칙을 준수해야 할 수 있습니다.
• 사용자 인터페이스: 파일 업로드를 위한 클라이언트 측 인터페이스는 직관적이어야 하며 사용자의 언어와 로케일을 지원해야 합니다.

테스트를 위한 도구 및 라이브러리

파일 업로드 엔드포인트를 테스트하는 것은 매우 중요합니다. 다음은 몇 가지 일반적인 도구입니다:

• Swagger UI (대화형 API 문서): FastAPI는 Swagger UI 문서를 자동으로 생성합니다. 브라우저 인터페이스에서 직접 파일 업로드를 테스트할 수 있습니다. 파일 입력 필드를 찾아 "파일 선택" 버튼을 클릭하세요.
• Postman: 인기 있는 API 개발 및 테스트 도구입니다. 파일 업로드 요청을 보내려면:
• 요청 메서드를 POST로 설정합니다.
• API 엔드포인트 URL을 입력합니다.
• "Body" 탭으로 이동합니다.
• 유형으로 "form-data"를 선택합니다.
• 키-값 쌍에 파일 매개변수의 이름(예: file)을 입력합니다.
• 유형을 "Text"에서 "File"로 변경합니다.
• "Choose Files"를 클릭하여 로컬 시스템에서 파일을 선택합니다.
• 다른 폼 필드가 있는 경우, 유형을 "Text"로 유지하면서 비슷하게 추가합니다.
• 요청을 보냅니다.
• cURL: HTTP 요청을 만드는 명령줄 도구입니다.
• 단일 파일의 경우: curl -X POST -F "file=@/path/to/your/local/file.txt" http://localhost:8000/files/
• 다중 파일의 경우: curl -X POST -F "files=@/path/to/file1.txt" -F "files=@/path/to/file2.png" http://localhost:8000/files/multiple/
• 혼합 데이터의 경우: curl -X POST -F "description=My description" -F "files=@/path/to/file.txt" http://localhost:8000/files/mixed/
• 파이썬의 `requests` 라이브러리: 프로그래밍 방식 테스트용입니다.

            import requests

url = "http://localhost:8000/files/save/"
files = {'file': open('/path/to/your/local/file.txt', 'rb')}

response = requests.post(url, files=files)
print(response.json())

# For multiple files
url_multiple = "http://localhost:8000/files/multiple/"
files_multiple = {
    'files': [('file1.txt', open('/path/to/file1.txt', 'rb')),
              ('image.png', open('/path/to/image.png', 'rb'))]
}
response_multiple = requests.post(url_multiple, files=files_multiple)
print(response_multiple.json())

# For mixed data
url_mixed = "http://localhost:8000/files/mixed/"
data = {'description': 'Test description'}
files_mixed = {'files': open('/path/to/another_file.txt', 'rb')}
response_mixed = requests.post(url_mixed, data=data, files=files_mixed)
print(response_mixed.json())

            

              
                Copy
              
            
          

결론

FastAPI는 멀티파트 파일 업로드를 처리하는 강력하고 효율적이며 직관적인 방법을 제공합니다. UploadFile 타입과 비동기 프로그래밍을 활용하여 개발자는 파일 처리 기능을 원활하게 통합하는 견고한 API를 구축할 수 있습니다. 보안을 최우선으로 하고, 적절한 오류 처리를 구현하며, 파일 이름 인코딩 및 규제 준수와 같은 측면을 해결하여 글로벌 사용자 기반의 요구를 고려하는 것을 잊지 마세요.

간단한 이미지 공유 서비스를 구축하든 복잡한 문서 처리 플랫폼을 구축하든, FastAPI의 파일 업로드 기능을 마스터하는 것은 중요한 자산이 될 것입니다. 계속해서 그 기능을 탐색하고, 모범 사례를 구현하며, 국제적인 사용자에게 탁월한 사용자 경험을 제공하세요.