[카테고리:] FastAPI서버개발

현대의 웹 애플리케이션 개발에서는 API와 그 문서화가 매우 중요합니다. FastAPI는
파이썬으로 제작된 웹 프레임워크로, 높은 성능과 사용의 용이성 덕분에 많은 개발자들 사이에서 각광받고 있습니다.
본 글에서는 FastAPI의 자동 문서화 기능에 대해 다룰 것입니다. 특히, Swagger UI와 ReDoc을 사용하여
FastAPI 애플리케이션의 API 문서화를 어떻게 수행하는지에 대해 자세히 알아보겠습니다.

1. FastAPI 소개

FastAPI는 Starlette와 Pydantic을 기반으로 구축된 현대적인 웹 프레임워크로,
RESTful API를 빠르고 쉽게 개발할 수 있도록 설계되었습니다. FastAPI의 주요 특징으로는
매우 빠른 성능, 자동적인 데이터 검증 및 직렬화, 그리고 멀티스레드를 지원하는 비동기 기능 등이 있습니다.

1.1 FastAPI의 특징

• 성능: Starlette를 기반으로 하여 비동기 처리를 통해 높은 성능을 자랑합니다.
• 자동 문서화: Swagger UI와 ReDoc을 통해 API 문서화를 자동으로 수행합니다.
• 유효성 검사: Pydantic을 사용하여 데이터 검증을 쉽게 처리할 수 있습니다.
• 간편한 라우팅 및 경로 매핑: 직관적인 경로 매핑 기능을 제공합니다.

2. FastAPI의 설치

FastAPI를 설치하기 위해서는 먼저 Python이 설치되어 있어야 합니다. 이후 다음의 명령어로 FastAPI와
Uvicorn(ASGI 서버)을 설치할 수 있습니다.

pip install fastapi uvicorn

3. FastAPI 애플리케이션 기본 설정

FastAPI로 애플리케이션을 생성하고 기본적인 API를 설정하는 방법을 알아보겠습니다.
아래는 기본적인 FastAPI 애플리케이션의 예제 코드입니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

위 코드는 기본적인 FastAPI 애플리케이션을 생성하며, 루트 경로(‘/’)와
파라미터가 있는 경로(‘/items/{item_id}’)를 정의하고 있습니다.
이를 실행하기 위해서는 다음과 같은 명령어를 사용할 수 있습니다.

uvicorn main:app --reload

위의 명령어에서 ‘main’은 파일 이름이며, ‘app’은 FastAPI 인스턴스입니다.
–reload 옵션을 통해 코드 변경 시 서버를 자동으로 재시작하도록 설정할 수 있습니다.

4. FastAPI의 자동 문서화 기능

FastAPI는 Swagger UI와 ReDoc을 사용하여 API 문서화를 자동으로 수행합니다.
이러한 기능은 개발자가 API Endpoint를 정의할 때, FastAPI가 자동으로
해당 API에 대한 문서를 생성하도록 합니다.

4.1 Swagger UI

FastAPI에서 Swagger UI를 사용하는 것은 매우 간단합니다.
애플리케이션을 실행하면 기본적으로 ‘/docs’ 경로에서 Swagger UI에 접근할 수 있습니다.
Swagger UI는 API의 요청 방식(HTTP 메서드, URL 등), 요청/응답의 데이터 구조,
예제 등을 포함하여 직관적으로 API를 테스트할 수 있는 인터페이스를 제공합니다.

Swagger UI 예제

FastAPI 애플리케이션을 실행한 후, 웹 브라우저에서 ‘http://localhost:8000/docs’를
열어보세요. 귀하의 API Endpoint에 대한 문서가 자동으로 생성된 것을 확인할 수 있습니다.
예를 들어 위에서 설정한 루트 경로(‘/’)와 ‘/items/{item_id}’ 경로가
Swagger UI에서 나열되고, 각 경로에 대한 요청을 보낼 수 있는 버튼이 제공됩니다.

4.2 ReDoc

FastAPI는 또한 ReDoc을 통해 API 문서화를 지원합니다.
ReDoc은 깔끔하고 현대적인 디자인으로 복잡한 API를 쉽게 탐색할 수 있도록 도와줍니다.
ReDoc 문서는 ‘/redoc’ 경로에서 확인할 수 있습니다.

ReDoc 예제

FastAPI 애플리케이션을 실행한 후, 웹 브라우저에서 ‘http://localhost:8000/redoc’를
열어보세요. ReDoc으로 생성된 API 문서를 확인할 수 있습니다.
각 API Endpoint에 대한 설명과 요청/응답 모델을 간결하게 보여줍니다.

5. FastAPI의 문서화에 대한 추가적인 기능

FastAPI는 문서화 기능을 강화하기 위한 여러 가지 옵션을 제공합니다.
예를 들어, API 문서화 시에 사용할 제목, 설명 및 버전 정보를 설정할 수 있습니다.

예제 코드

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="API 설명을 여기에 적습니다.",
    version="1.0.0",
)

@app.get("/")
def read_root():
    return {"Hello": "World"}

위와 같이 FastAPI 인스턴스를 생성할 때, title, description, version 등의
매개변수를 지정할 수 있습니다. 이렇게 하면 Swagger UI와 ReDoc에 설정한 값이
자동으로 반영됩니다.

6. 의존성과 보안 기능을 활용한 문서화

FastAPI는 API 문서화를 단순화하는 것만이 아니라, 의존성 주입(Dependency Injection)와 보안
기능을 통해 API의 복잡한 구조를 관리하는 데도 유용합니다. 예를 들어,
인증이 필요한 API Endpoint의 경우 FastAPI는 이러한 기능을 문서화하는 데 있어서
유용한 정보를 제공합니다.

예제 코드

from fastapi import FastAPI, Depends

app = FastAPI()

def fake_authenticate(username: str, password: str):
    if username == "admin" and password == "secret":
        return True
    return False

@app.get("/secure-data/")
def get_secure_data(authenticated: bool = Depends(fake_authenticate)):
    return {"data": "This is secured data"}

위 예제를 실행할 경우 ‘/secure-data/’ Endpoint는 ‘fake_authenticate’ 함수를 통해
인증을 요구합니다. Swagger UI에서는 이 Endpoint에 대해 인증 요구 사항이
명시적으로 표시될 것입니다.

7. 결론

FastAPI는 훌륭한 자동 문서화 기능을 제공하여 API 개발을 보다 쉽게 만들어 줍니다.
Swagger UI와 ReDoc을 통해 API 문서를 자동으로 생성할 수 있는 기능은 개발자에게 큰
시간을 절약하게 하며, 적시에 문서화된 API를 제공할 수 있습니다.
또한 FastAPI의 다양한 기능을 통해 애플리케이션의 안정성과 보안성을 높일 수 있습니다.

FastAPI를 사용한 API 개발의 모든 과정을 이해하는 데 도움이 되었기를 바랍니다.
앞으로도 FastAPI를 활용하여 더 나은 웹 애플리케이션을 개발해 보세요!

FastAPI는 Python으로 작성된 현대적인 웹 프레임워크로, 빠른 개발과 성능을 목표로 하고 있습니다. 이 블로그 포스트에서는 FastAPI에서 스키마를 정의하고 이를 통해 응답을 설정하는 방법에 대해 자세히 설명하도록 하겠습니다. 우리는 여기에 여러 예제와 함께 설명할 것이며, 명확한 이해를 돕기 위해 단계적으로 진행하겠습니다.

FastAPI란?

FastAPI는 다음과 같은 주요 특징을 가지고 있습니다:

• 자동 생성된 OpenAPI 문서
• 유효성 검사를 통한 데이터 검증
• 비동기 지원으로 높은 성능
• 모든 매개변수의 자동 문서화

FastAPI 설치

FastAPI를 시작하기 위해서는 먼저 FastAPI와 Uvicorn을 설치해야 합니다. Uvicorn은 ASGI 서버로 FastAPI 애플리케이션을 실행하는 데 사용됩니다. 아래와 같이 설치할 수 있습니다:

pip install fastapi uvicorn

응답 스키마 정의

FastAPI는 Pydantic을 통해 데이터 유효성 검사와 직렬화를 처리합니다. Pydantic 모델을 사용하면 API의 데이터 모델을 정의할 수 있습니다. 이를 통해 클라이언트가 요청한 데이터를 검증하고, 서버가 보낼 응답 형태를 정의할 수 있습니다.

Pydantic 모델 생성

Pydantic 모델을 생성하는 방법에 대해 살펴보겠습니다. 아래는 간단한 Pydantic 모델을 정의하는 예제입니다:

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

위의 Item 클래스는 name, description, price, 그리고 tax 필드를 포함하고 있습니다. description와 tax는 기본값으로 None을 설정하였으므로 선택적 필드입니다. 이제 이 모델을 사용하여 FastAPI 라우트를 정의해 보겠습니다.

FastAPI에서 응답 정의

FastAPI에서 정의한 Pydantic 모델을 응답 스키마로 활용하는 방법을 설명하겠습니다. 아래는 FastAPI와 Pydantic을 사용한 간단한 API 예제입니다:

from fastapi import FastAPI

app = FastAPI()

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    return item

위의 예제에서는 /items/ 엔드포인트를 통해 아이템을 생성하는 API를 정의하였습니다. 사용자가 요청한 아이템 데이터는 Pydantic 모델인 Item을 기준으로 검증됩니다. 요청이 성공적으로 처리되면, 동일한 아이템 데이터가 응답으로 반환됩니다.

응답 타입 정의

FastAPI에서는 응답의 타입을 정의하여 클라이언트에게 어떤 형식의 데이터를 보낼 것인지 명확히 알릴 수 있습니다. 이는 API의 가독성을 높이고, 클라이언트가 올바르게 요청을 할 수 있도록 돕습니다.

응답 모델 사용하기

응답 모델은 위에서 정의한 Pydantic 모델을 쉽게 활용할 수 있습니다. 여기서는 약간 더 복잡한 예제를 통해 응답 타입을 정의하는 방법을 알아보겠습니다:

from typing import List

class ItemResponse(BaseModel):
    items: List[Item]
    total: int

@app.get("/items/", response_model=ItemResponse)
async def read_items(skip: int = 0, limit: int = 10):
    # 여기서 실제 데이터베이스 쿼리를 수행하겠지만, 예제로 일부 더미 데이터를 반환합니다.
    fake_items = [Item(name="Item 1", price=100.0), Item(name="Item 2", price=200.0)]
    return ItemResponse(items=fake_items, total=len(fake_items))

위의 예제는 /items/ 엔드포인트를 통해 아이템 리스트와 총 개수를 반환합니다. ItemResponse 모델은 items 필드와 total 필드를 포함하고 있으며, 데이터를 리스트와 정수 형태로 묶어서 보냅니다.

응답 JSON 예제

위의 예제를 통해 API를 호출하면 다음과 같은 JSON 응답을 얻을 수 있습니다:

{
    "items": [
        {"name": "Item 1", "description": null, "price": 100.0, "tax": null},
        {"name": "Item 2", "description": null, "price": 200.0, "tax": null}
    ],
    "total": 2
}

여기서 클라이언트는 요청한 API에서 어떤 형태의 데이터가 반환될지를 예측할 수 있으며, 이는 개발자와 사용자가 더 나은 대화를 할 수 있도록 돕습니다.

오류 응답 처리

FastAPI에서는 정의된 스키마에 맞지 않는 요청에 대해 자동으로 오류를 처리합니다. 사용자가 잘못된 데이터를 보낼 경우, FastAPI는 422 Unprocessable Entity 오류를 반환하며, 어떤 필드가 잘못되었는지에 대한 정보를 제공합니다.

POST /items/
{
    "name": "Item 1",
    "price": "Not a number"  # 이 필드는 숫자가 필요합니다.
}

이와 같은 경우 FastAPI는 다음과 같은 오류 응답을 생성합니다:

{
    "detail": [
        {
            "loc": ["body", "price"],
            "msg": "value is not a valid float",
            "type": "value_error.float"
        }
    ]
}

결론

이 블로그 포스트에서는 FastAPI에서 스키마를 정의하고, 이를 통해 API의 응답 타입을 설정하는 방법에 대해 자세히 살펴보았습니다. Pydantic 모델을 사용하여 데이터 구조를 정의하고, 이를 FastAPI에 통합하여 강력한 API를 만들 수 있음을 확인하였습니다. 이러한 접근은 데이터의 무결성과 API의 명료성을 보장하는 데 큰 도움이 됩니다.

FastAPI를 통해 더 나은 웹 서비스를 개발할 수 있기를 바랍니다. 추가적인 질문이 있다면 언제든지 댓글 달아 주시기 바랍니다!

FastAPI는 현대적인 웹 API를 구축하기 위한 높은 성능과 비동기 기능을 제공하는 Python 웹 프레임워크입니다. 본 글에서는 FastAPI 서버 개발부터 배포, 그리고 환경 변수 설정까지의 전 과정을 자세히 살펴보도록 하겠습니다.

1. FastAPI 소개

FastAPI는 Python 3.6 이상에서 사용 가능하며, Starlette과 Pydantic을 기반으로 설계되었습니다. 주된 특징으로는 자동 API 문서 생성, 유효성 검사, 비동기 지원, 높은 성능 등이 있습니다. 이러한 특징 덕분에 FastAPI는 RESTful API, Microservices, 데이터 처리 애플리케이션 등을 만드는 데 적합합니다.

2. FastAPI 설치

FastAPI는 PyPI에서 쉽게 설치할 수 있습니다. 아래 명령어를 사용하여 FastAPI와 ASGI 서버인 uvicorn을 설치합니다:

pip install fastapi uvicorn

3. FastAPI 기본 구조

FastAPI 애플리케이션은 기본적으로 다음과 같은 구조를 가집니다.

my_fastapi_app/
├── main.py
└── requirements.txt

디렉토리 구조를 만들었다면, 빠른 시작을 위한 예제 코드를 작성해보겠습니다.

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, World!"}

이제 아래 명령어로 FastAPI 서버를 실행합니다:

uvicorn main:app --reload

서버가 실행되면, http://127.0.0.1:8000/docs를 통해 자동으로 생성된 API 문서를 확인할 수 있습니다.

4. RESTful API 개발

4.1. CRUD API 구현

이제 간단한 CRUD(Create, Read, Update, Delete) API를 만들어보겠습니다.

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str
    description: str

items = []

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    items.append(item)
    return item

@app.get("/items/", response_model=List[Item])
async def read_items():
    return items

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    for item in items:
        if item.id == item_id:
            return item
    raise HTTPException(status_code=404, detail="Item not found")

@app.put("/items/{item_id}", response_model=Item)
async def update_item(item_id: int, item: Item):
    for index, existing_item in enumerate(items):
        if existing_item.id == item_id:
            items[index] = item
            return item
    raise HTTPException(status_code=404, detail="Item not found")

@app.delete("/items/{item_id}", response_model=Item)
async def delete_item(item_id: int):
    for index, item in enumerate(items):
        if item.id == item_id:
            return items.pop(index)
    raise HTTPException(status_code=404, detail="Item not found")

4.2. API 테스트

이제 개발한 API를 Postman 또는 cURL을 사용하여 테스트할 수 있습니다. 예를 들어, curl을 이용하여 아이템을 생성하는 방법은 다음과 같습니다.

curl -X POST "http://127.0.0.1:8000/items/" -H "Content-Type: application/json" -d '{"id": 1, "name": "Item 1", "description": "This is item 1."}'

5. 환경 변수 설정

개발 환경에서 중요한 요소 중 하나는 환경 변수를 설정하는 것입니다. FastAPI를 사용할 때도 환경 변수를 설정하여 설정 파일을 분리하고 보안을 강화할 수 있습니다.

5.1. Python-dotenv 라이브러리 설치

환경 변수를 관리하기 위해 python-dotenv 라이브러리를 설치합니다:

pip install python-dotenv

5.2. .env 파일 생성

프로젝트 루트 디렉토리에 .env 파일을 생성하고 여기에 환경 변수를 추가합니다:

DATABASE_URL=mysql://user:password@localhost/dbname
API_KEY=your_api_key

5.3. 환경 변수 로드하기

이제 코드에서 load_dotenv() 함수를 사용하여 환경 변수를 로드할 수 있습니다.

# main.py
import os
from dotenv import load_dotenv

load_dotenv()

DATABASE_URL = os.getenv("DATABASE_URL")
API_KEY = os.getenv("API_KEY")

6. FastAPI 배포

FastAPI 애플리케이션을 배포하는 방법에는 여러 가지가 있습니다. 여기서는 Heroku와 Docker를 이용한 배포 방법을 설명하겠습니다.

6.1. Heroku 배포

Heroku는 클라우드 애플리케이션 플랫폼으로, FastAPI 애플리케이션을 쉽게 배포할 수 있습니다.

heroku create my-fastapi-app
heroku addons:create heroku-postgresql:hobby-dev
git push heroku master

이후, 브라우저에서 https://my-fastapi-app.herokuapp.com와 같은 URL로 FastAPI 애플리케이션에 접근할 수 있습니다.

6.2. Docker 배포

Docker를 사용하면 애플리케이션을 컨테이너로 패키징하여 배포할 수 있습니다. 다음은 Dockerfile 작성 예시입니다.

# Dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.8

COPY ./app /app

WORKDIR /app

RUN pip install --no-cache-dir -r requirements.txt

이후, 이미지를 빌드하고 실행합니다:

docker build -t my-fastapi-app .
docker run -d -p 80:80 my-fastapi-app

7. 결론

FastAPI는 API 서버를 쉽게 개발하고 배포할 수 있는 강력한 도구입니다. 이 글에서 설명한 내용을 바탕으로 FastAPI를 활용하여 자신의 프로젝트를 구현해보세요. 환경 변수 설정과 같은 유용한 기능을 통해 보안을 강화하고, 다양한 배포 방법을 통해 애플리케이션을 실제 서비스에 적용할 수 있습니다.

FastAPI는 현대적인 웹 프레임워크 중 하나로, Python을 기반으로 하여 빠르고 효율적으로 API 서버를 개발할 수 있도록 돕습니다. 특히 비동기 처리를 지원하기 때문에 높은 성능을 자랑합니다. 본 강좌에서는 FastAPI 서버 개발에 있어서 CORS(Cross-Origin Resource Sharing)의 필요성과 관련된 보안 고려사항에 대해 자세히 설명하겠습니다.

1. CORS란 무엇인가?

CORS는 Cross-Origin Resource Sharing의 약자로, 다른 출처(Origin)의 서버와 자원을 공유하기 위한 메커니즘입니다. 기본적으로 웹 브라우저는 보안상의 이유로 다른 출처의 자원 요청을 제한하고 있습니다. 예를 들어, A.com에서 실행되는 스크립트는 B.com의 API에 접근할 수 없습니다. 하지만, 적절한 CORS 헤더를 서버에서 설정함으로써 이러한 제한을 해제할 수 있습니다.

1.1 CORS의 필요성

CORS는 여러 서비스가 서로 연동될 필요가 있는 현대 웹 환경에서 필수적입니다. 프론트엔드와 백엔드가 다른 출처에 있을 경우, 프론트엔드에서 API를 호출할 때 CORS 설정이 필요합니다. 만약 CORS가 설정되지 않은 경우, 웹 브라우저는 요청을 차단하게 되어 사용자에게 원활한 서비스 제공이 어려워집니다.

2. FastAPI에서 CORS 설정하기

FastAPI에서는 CORS에 대한 설정이 매우 간단합니다. fastapi.middleware.cors 모듈을 통해 쉽게 CORS 미들웨어를 추가할 수 있습니다. 아래 예제를 통해 FastAPI에서 CORS 설정을 어떻게 하는지 살펴보겠습니다.

2.1 FastAPI 애플리케이션 생성 및 CORS 추가

python
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# CORS 미들웨어 설정
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 모든 출처 허용
    allow_credentials=True,
    allow_methods=["*"],  # 모든 HTTP 메서드 허용
    allow_headers=["*"],  # 모든 HTTP 헤더 허용
)

@app.get("/")
async def read_root():
    return {"Hello": "World"}
    

위 코드에서 allow_origins=["*"]는 모든 출처의 요청을 허용하는 설정입니다. 실제 운영 환경에서는 특정 도메인만 허용하는 것이 좋습니다.

3. 보안 고려사항

CORS 설정은 보안과 관련하여 매우 중요한 요소입니다. 적절한 CORS 정책을 설정하지 않을 경우, 원치 않는 출처에서 API에 접근하거나 악의적인 요청이 발생할 수 있습니다. 따라서 아래와 같은 보안 고려사항을 반드시 점검해야 합니다.

3.1 신뢰할 수 있는 출처만 허용하기

CORS를 설정할 때는 신뢰할 수 있는 출처만을 허용해야 합니다. 예를 들어, allow_origins=["https://example.com"]와 같이 특정 도메인만 허용할 수 있습니다. 이는 보안의 기본입니다.

3.2 데이터 검증과 인증

모든 API 요청에 대해 적절한 인증과 데이터 검증을 수행해야 합니다. FastAPI에서는 OAuth2, JWT 같은 토큰 기반 인증 메커니즘을 통해 API 인증을 쉽게 구현할 수 있습니다.

3.3 HTTP 메서드 제한하기

API에서 허용하는 HTTP 메서드를 제한함으로써 불필요한 접근을 차단할 수 있습니다. 예를 들어, GET과 POST 메서드만을 허용하는 방식으로 설정할 수 있습니다. 아래는 메서드를 제한하는 예시입니다.

python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],  # 제한된 HTTP 메서드 허용
    allow_headers=["*"],
)

3.4 CSRF 보호

Cross-Site Request Forgery(CSRF) 공격에 대해 주의해야 합니다. FastAPI에서는 CSRF 보호를 위해 적절한 인증 토큰을 사용해야 하며, 중요한 상태 변화가 포함된 요청에 대해 추가적인 확인 절차를 두는 것이 좋습니다.

4. CORS와 보안 확인 예제

아래는 CORS와 보안 고려사항을 적용한 FastAPI의 전체 예제입니다. 이 예제에서는 기본적인 CORS 설정과 함께 데이터 검증을 포함하여 실제 API 사용을 보여줍니다.

python
from fastapi import FastAPI, HTTPException, Depends
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel, EmailStr
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

# CORS 미들웨어 설정
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

class User(BaseModel):
    email: EmailStr
    password: str

@app.post("/users/")
async def create_user(user: User, token: str = Depends(oauth2_scheme)):
    # 사용자 데이터 검증과 저장 로직
    if not user.email or not user.password:
        raise HTTPException(status_code=400, detail="Invalid user data")
    return {"email": user.email, "message": "User created successfully!"}

@app.get("/")
async def read_root():
    return {"Hello": "World"}

5. 결론

FastAPI에서 CORS 설정은 필수적이며, 올바른 CORS 정책을 설정하여 보안상의 문제를 예방하는 것이 중요합니다. 실제 운영 단계에서는 보다 세부적인 보안 고려사항을 반드시 점검하고, 필요에 따라 추가적인 보안 수단을 적용해야 합니다. FastAPI의 유연함을 활용하여 안전하면서도 강력한 API 서버를 구축해보세요.

이 글이 FastAPI에서 CORS를 설정하고 보안 고려사항을 이해하는 데 도움이 되었기를 바랍니다.

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는 파일 업로드를 간편하게 처리할 수 있는 방법을 제공합니다. 이 강좌를 통해 파일 업로드 기본 개념과 좋은 코드의 예제를 이해하셨기를 바랍니다.
실제 프로젝트에서 적용할 때 다양한 추가 기능과 보안 측면에 신경 쓰시기 바랍니다.

9. 참고 자료

• FastAPI 공식 문서
• HTTP POST 메서드에 대한 설명
• Real Python의 FastAPI 튜토리얼
• Towards Data Science의 FastAPI API 구축 강좌