FastAPI에서 파일 업로드 처리하기
FastAPI는 Python으로 개발된 현대적인 웹 프레임워크로, 빠르고 쉽게 API를 구축할 수 있는 특징을 가지고 있습니다.
특히, FastAPI는 타입 힌트를 사용하여 코드의 가독성을 높이고, 자동으로 문서화를 지원하는 기능 등으로 매우 유용합니다.
이번 글에서는 FastAPI를 사용하여 파일 업로드 기능을 구현하는 방법에 대해 자세히 알아보겠습니다.
1. FastAPI 소개
FastAPI는 Python 3.6 이상에서 실행되는 ASGI 표준 기반의 웹 프레임워크입니다. 기본적으로 Starlette 위에서 빌드되었으며,
Pydantic을 통해 데이터 유효성 검사를 제공합니다. High-performance API를 만들 수 있도록 최적화되어 있습니다.
FastAPI는 RESTful API를 구축할 때 간편하게 사용할 수 있으며, OpenAPI 스펙을 자동으로 문서화해주는 기능도 제공합니다.
2. FastAPI 환경 설정
FastAPI를 설치하기 위해 다음 명령어를 실행하여 패키지를 설치합니다.
pip install fastapi uvicorn여기서 `uvicorn`은 ASGI 서버로 FastAPI 애플리케이션을 실행하는 데 사용됩니다.
3. 파일 업로드 기능 이해하기
웹 애플리케이션에서 파일 업로드는 사용자가 이미지, 문서 및 기타 여러 가지 형식을 서버에 전송할 수 있게 해줍니다.
FastAPI는 파일 업로드를 간편하게 처리할 수 있는 다양한 도구를 제공합니다.
FastAPI에서 파일 업로드는 `File`과 `UploadFile` 클래스의 도움을 받아 구현할 수 있습니다.
3.1. File과 UploadFile의 차이점
– File: 일반적인 필드처럼 파일을 처리합니다. 파일의 내용을 메모리에 로드하므로,
작은 파일을 받는 경우에 적합합니다.
– UploadFile: 파일을 비동기적으로 처리할 수 있으며, 파일 내용을 메모리에 로드하지 않고,
파일의 내용을 파일 시스템에 저장하거나 버퍼링할 수 있습니다. 따라서 큰 파일 처리에 적합합니다.
4. 예제 코드: FastAPI 파일 업로드 서버
이번 섹션에서는 FastAPI로 간단한 파일 업로드 서버를 구현해 보겠습니다. 사용자는 파일을 선택하여 서버에 업로드할 수 있습니다.
4.1. 기본 구조 설정
python
from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse
import shutil
import os
app = FastAPI()
UPLOAD_DIRECTORY = "uploads"
# 업로드 디렉토리 생성
if not os.path.exists(UPLOAD_DIRECTORY):
os.makedirs(UPLOAD_DIRECTORY)
@app.get("/", response_class=HTMLResponse)
async def main():
content = """
파일 업로드
"""
return content
@app.post("/uploadfile/")
async def upload_file(file: UploadFile = File(...)):
file_location = f"{UPLOAD_DIRECTORY}/{file.filename}"
with open(file_location, "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
return {"info": f"file '{file.filename}' saved at '{file_location}'"}
4.2. 코드 설명
– FastAPI 인스턴스를 생성하고, 파일 업로드를 처리할 root 경로를 정의합니다.
– 사용자가 파일을 업로드할 수 있는 HTML 폼을 반환합니다.
– POST 요청을 처리하는 /uploadfile/ 엔드포인트를 정의하고,
UploadFile 타입의 인자를 받습니다.
– 파일을 일정한 위치에 저장하는 로직을 구현합니다.
5. FastAPI 서버 실행
위의 코드를 작성한 후, FastAPI 서버를 실행하면 됩니다. 아래 명령어를 터미널에 입력하여 서버를 실행합니다.
uvicorn your_file_name:app --reload
your_file_name은 FastAPI 어플리케이션이 정의된 파일의 이름으로, 확장자 없이 입력합니다.
–reload 플래그는 코드 변경 시 서버가 자동으로 재시작되도록 합니다.
6. 파일 업로드 테스트
서버가 실행되고 나면, 웹 브라우저에서 http://127.0.0.1:8000로 접근합니다.
파일 업로드를 위한 폼이 나타나면 원하는 파일을 선택하고 “Upload File” 버튼을 클릭하여 파일을 업로드합니다.
업로드가 완료되면, 서버는 파일이 저장된 경로와 파일 이름을 응답으로 반환합니다.
7. 추가 고려 사항
업로드된 파일을 처리할 때 몇 가지 고려해야 할 사항이 있습니다.
– **파일 크기 제한**: 대용량 파일 업로드를 방지하기 위해 FastAPI의 File 클래스에 max_length 매개변수를 사용할 수 있습니다.
– **파일 형식 검증**: 업로드할 수 있는 파일 형식을 제한할 수 있습니다. MIME 타입을 확인하여 허용된 형식만 처리하도록 설정할 수 있습니다.
– **보안**: 파일 업로드는 보안에 대한 취약점을 가질 수 있으므로, 파일 이름을 검증하고 특정 디렉토리 이외의 위치에 저장하지 않도록 주의해야 합니다.
8. 결론
FastAPI는 파일 업로드를 간편하게 처리할 수 있는 방법을 제공합니다. 이 강좌를 통해 파일 업로드 기본 개념과 좋은 코드의 예제를 이해하셨기를 바랍니다.
실제 프로젝트에서 적용할 때 다양한 추가 기능과 보안 측면에 신경 쓰시기 바랍니다.