FastAPI 서버개발, 경로 동작 함수에 대하여

FastAPI는 Python의 현대적인 웹 프레임워크로, 빠르고 간편하게 RESTful API를 구축할 수 있도록 설계되었습니다.
이 글에서는 FastAPI의 경로 동작 함수에 대해 자세히 알아보며, 다양한 예제를 통해 이를 실습해보겠습니다.

1. FastAPI란?

FastAPI는 Starlette를 기반으로 하고 있으며, ASGI를 지원하는 비동기 웹 프레임워크입니다.
이는 고성능 웹 애플리케이션을 구축하는 데 최적화되어 있으며, 비동기 프로그래밍을 쉽게 구현할 수 있도록 도와줍니다.
FastAPI는 타입 힌트(type hints)를 사용하여 코드 작성 시 발생할 수 있는 오류를 줄이고,
더 나아가 API 문서화(auto-generation) 및 데이터 검증(data validation)을 자동으로 처리할 수 있습니다.

2. 경로 동작 함수란?

경로 동작 함수는 특정 HTTP 요청이 앱의 특정 경로로 들어올 때 실행되는 함수를 의미합니다.
예를 들어, 사용자가 “/items” 경로로 GET 요청을 보낼 때 특정 동작을 수행하는 함수가 이에 해당합니다.
FastAPI에서는 경로 동작 함수를 구현하기 위해 여러 데코레이터를 사용합니다.

2.1 주요 HTTP 메서드와 FastAPI 데코레이터

FastAPI에서 지원하는 주요 HTTP 메서드와 이들을 구현하기 위한 데코레이터는 다음과 같습니다:

  • @app.get(): GET 요청 처리
  • @app.post(): POST 요청 처리
  • @app.put(): PUT 요청 처리
  • @app.delete(): DELETE 요청 처리
  • @app.patch(): PATCH 요청 처리

3. FastAPI 기본 사용법

FastAPI 서버를 시작하기 위해서는 먼저 FastAPI 라이브러리를 설치해야 합니다. 이는 pip 명령어로 간단하게 설치할 수 있습니다. 

pip install fastapi uvicorn

설치가 완료되면, 아래와 같이 기본적인 FastAPI 서버를 구현할 수 있습니다. 

python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Welcome to FastAPI!"}

위 코드는 루트 경로(“/”)로의 GET 요청이 들어오면 JSON 형식으로 웰컴 메시지를 반환하는 간단한 FastAPI 서버입니다.
이 서버를 실행하기 위해서는 다음 명령어를 사용합니다. 

uvicorn main:app --reload

여기서 main은 파일 이름, app는 FastAPI 인스턴스를 가리킵니다.
--reload 옵션을 주면 코드 변경 시 서버가 자동으로 재시작됩니다.

4. 경로 동작 함수의 파라미터

경로 동작 함수는 URL 경로에서 정보를 읽어 파라미터로 받을 수 있습니다. FastAPI는 이러한 파라미터를 손쉽게 정의할 수 있습니다.

4.1 경로 파라미터

경로 파라미터는 URL 경로에 포함되어 전달되는 값으로, 대괄호({})를 사용하여 정의합니다. 다음은 경로 파라미터를 사용하는 예제입니다. 

python
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

위 예제에서 item_id는 URL 경로의 일부로서, 클라이언트가 /items/5와 같은 요청을 보냈을 때 5가 item_id로 전달됩니다.
FastAPI는 자동으로 이 값을 정수형으로 변환합니다.

4.2 쿼리 파라미터

쿼리 파라미터는 URL의 ‘?’ 뒤에 있는 파라미터로, URL 인코딩된 키-값 쌍 형식으로 전달됩니다.
아래는 쿼리 파라미터를 사용한 예제입니다. 

python
@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

이 예제에서 skip과 limit는 쿼리 파라미터로, 기본값을 각기 0과 10으로 설정하고 있습니다.
클라이언트가 /items/?skip=5&limit=15로 요청할 경우, 값이 정상적으로 변경됩니다.

4.3 본문 파라미터

POST 요청에서 JSON 데이터를 본문으로 받을 수 있습니다. FastAPI는 이 데이터를 Pydantic 모델을 통해 검증하고 사용합니다.
다음은 본문 파라미터를 사용하는 예제입니다. 

python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

@app.post("/items/")
async def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

이 예제에서 Item 클래스는 Pydantic을 사용하여 데이터 검증을 수행합니다.
클라이언트가 JSON 본문을 {"name": "Item1", "price": 35.5}와 같은 형식으로 보내면,
해당 데이터가 item 파라미터로 전달됩니다.

5. FastAPI의 응답 모델

FastAPI는 응답 모델을 정의하여 반환되는 데이터 형식을 명확히 정의할 수 있습니다.
이렇게 하면 자동으로 문서화되며, 클라이언트가 반환되는 데이터의 구조를 쉽게 이해할 수 있습니다. 

python
from fastapi import FastAPI
from pydantic import BaseModel

class ItemResponse(BaseModel):
    item_name: str
    item_price: float

@app.post("/items/", response_model=ItemResponse)
async def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

이 예제에서 response_model 매개변수를 사용하여 반환될 데이터의 형식을 정의하였습니다.
이렇게 하면 응답이 ItemResponse로 제한되며, 클라이언트는 해당 형식을 따르게 됩니다.

6. FastAPI에서 에러 처리

FastAPI는 요청 처리 중 발생하는 예외에 대해 에러 핸들링을 지원합니다.
다음은 사용자 정의 예외를 발생시키고 처리하는 예제입니다. 

python
from fastapi import HTTPException

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

위 코드에서 item_id가 1보다 작을 경우, 404 상태 코드와 함께 에러 메시지를 반환합니다.
이처럼 FastAPI는 HTTP 상태 코드와 메시지를 손쉽게 설정할 수 있습니다.

7. 배포 및 실행

최종적으로 완성된 FastAPI 애플리케이션은 다양한 플랫폼에 배포할 수 있습니다.
주요 배포 옵션으로는 Docker, Heroku, AWS 등이 있습니다.
Uvicorn 서버를 사용하여 로컬에서 애플리케이션을 실행할 수 있으며, 생산 환경에서는 Gunicorn과 같은 WSGI 서버를 사용할 수 있습니다.

7.1 Docker를 사용한 배포

Docker를 사용하면 환경 설정을 단순화하고, 애플리케이션을 쉽게 배포할 수 있습니다.

dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9
COPY ./app /app

위 Dockerfile을 사용하여 FastAPI 애플리케이션을 Docker 컨테이너에서 실행할 수 있습니다.
docker build -t myfastapiapp . 명령어로 이미지를 생성한 후,
docker run -d -p 80:80 myfastapiapp으로 컨테이너를 실행할 수 있습니다.

8. 결론

FastAPI는 경량의 RESTful API를 구축할 수 있는 강력한 도구입니다.
경로 동작 함수를 이해하고 활용함으로써 클라이언트의 다양한 요청을 처리할 수 있으며,
Pydantic을 통한 데이터 검증 및 모델링이 가능해 어느 정도 규모의 프로젝트에서도 안정적으로 사용할 수 있습니다.
앞으로도 FastAPI에 대한 깊이 있는 이해를 바탕으로 복잡한 어플리케이션을 개발해보시길 바랍니다.

감사합니다!