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

FastAPI는 현대적인 웹 애플리케이션 및 API 개발에 적합한 Python 프레임워크입니다. 그 주요 장점은 높은 성능과 직관적인 사용성입니다. 이번 글에서는 FastAPI를 이용한 기본적인 백엔드 서버 개발 방법과 Docker를 이용한 환경 구성 및 동작 확인 절차에 대해 자세히 설명하겠습니다.

1. FastAPI 개요

FastAPI는 ASGI(Asynchronous Server Gateway Interface)를 기반으로 하며, 비동기 프로그래밍을 지원합니다. 또한 FastAPI는 Python의 타입 힌트를 적극적으로 활용하여, 개발자가 코드를 작성하는 동시에 API 문서를 자동 생성할 수 있습니다. FastAPI의 주요 특징은 다음과 같습니다.

• 고속 성능: FastAPI는 Starlette와 Pydantic을 기반으로 하여, 비동기 지원으로 매우 높은 성능을 제공합니다.
• 자동 API 문서화: Swagger UI 및 ReDoc을 통해 API 문서를 자동으로 생성할 수 있습니다.
• 데이터 검증: Pydantic을 사용하여 요청 데이터에 대한 검증을 손쉽게 수행할 수 있습니다.

2. FastAPI 서버 구축하기

2.1 FastAPI 설치

FastAPI와 Uvicorn(Web 서버)을 설치해보겠습니다. 아래 명령어를 통해 설치할 수 있습니다.

        
        pip install fastapi uvicorn
        
    

2.2 기본 FastAPI 애플리케이션

FastAPI 애플리케이션을 시작해보겠습니다. 아래 코드를 “main.py” 파일에 작성합니다.

        
        from fastapi import FastAPI

        app = FastAPI()

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

        if __name__ == "__main__":
            import uvicorn
            uvicorn.run(app, host="0.0.0.0", port=8000)
        
    

위 코드는 FastAPI 애플리케이션을 정의하는 기본 구조입니다. 우리는 “/” 경로로 GET 요청을 보내면 “Hello”: “World”라는 JSON 응답을 받게 됩니다.

2.3 FastAPI 실행하기

FastAPI 서버를 실행하려면 아래 명령어를 터미널에서 실행합니다.

        
        python main.py
        
    

서버가 정상적으로 실행되면 http://127.0.0.1:8000/docs에 접속하여 Swagger UI를 통해 API 문서를 확인할 수 있습니다.

3. Docker를 이용한 FastAPI 배포

3.1 Docker 설치 확인

Docker가 설치되어 있지 않다면, Docker의 공식 웹사이트에서 다운로드하여 설치합니다. 설치가 완료되면 아래 명령어를 통해 Docker가 정상적으로 설치되었는지 확인할 수 있습니다.

        
        docker --version
        
    

3.2 Dockerfile 작성하기

Dockerfile은 Docker 이미지를 생성하기 위한 스크립트입니다. 아래 내용을 기반으로 “Dockerfile”을 작성합니다.

        
        # 베이스 이미지 설정
        FROM python:3.9

        # 작업 디렉토리 설정
        WORKDIR /app

        # requirements.txt를 컨테이너로 복사
        COPY requirements.txt .

        # 종속성 설치
        RUN pip install --no-cache-dir -r requirements.txt

        # 애플리케이션 코드 복사
        COPY ./main.py .

        # FastAPI 서버 실행
        CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
        
    

위 Dockerfile에서는 Python 3.9를 베이스 이미지로 사용하고, 작업 디렉토리를 “/app”으로 설정했습니다. 이후 requirements.txt를 통해 패키지를 설치하고, 애플리케이션 코드를 복사합니다.

3.3 requirements.txt 작성하기

FastAPI와 Uvicorn 패키지를 관리하기 위한 “requirements.txt” 파일을 생성합니다. 아래 내용을 입력합니다.

        
        fastapi
        uvicorn
        
    

3.4 Docker 이미지 빌드하기

Dockerfile과 requirements.txt가 준비되었으면, Docker 이미지를 빌드할 수 있습니다. 아래 명령어를 터미널에서 실행합니다.

        
        docker build -t fastapi-app .
        
    

3.5 Docker 컨테이너 실행하기

다음으로 Docker 컨테이너를 실행하여 FastAPI 애플리케이션을 확인합니다. 아래 명령어를 사용합니다.

        
        docker run -d --name fastapi-container -p 8000:8000 fastapi-app
        
    

이제 http://127.0.0.1:8000/docs에 접속하여 Docker 내에서 실행 중인 FastAPI 서버의 Swagger UI를 확인할 수 있습니다.

4. 결론

이번 글에서는 FastAPI를 사용하여 기본적인 웹 애플리케이션을 구축하고 Docker를 통해 이를 배포하는 방법을 소개했습니다. FastAPI는 비동기 성공을 지원하며, 효율적인 API 개발을 가능하게 합니다. Docker를 이용한 배포는 애플리케이션 환경의 일관성을 보장하며, 손쉽게 배포할 수 있게 해줍니다. FastAPI와 Docker를 이용하여 신속하게 API 서버를 개발하시길 바랍니다.

5. 참고자료

• FastAPI 공식 문서
• Docker 공식 사이트

FastAPI는 Python으로 작성된 현대적이고 빠른 웹 프레임워크로, API 서버 개발에 매우 유용합니다. 이 글에서는 FastAPI를 사용하여 경로 동작 함수를 만드는 방법에 대해 상세히 알아보겠습니다. 이 강좌는 FastAPI를 처음 접하는 개발자뿐만 아니라 경로와 동작 함수 작성을 개선하고자 하는 개발자에게도 유익할 것입니다.

1. FastAPI 소개

FastAPI는 Starlette(비동기 웹 프레임워크)와 Pydantic(데이터 유효성 검사 및 설정 관리)을 기반으로 구축되었습니다. 주로 RESTful API를 구축하는 데 사용되며, 다음과 같은 장점이 있습니다:

• 성능: FastAPI는 매우 빠르며, Python의 비동기 기능을 통해 높은 성능을 제공합니다.
• 유효성 검사: Pydantic을 통해 요청 및 응답에 대한 엄격한 데이터 유효성 검사를 수행할 수 있습니다.
• 즉각적인 문서화: Swagger UI와 ReDoc을 사용하여 자동으로 API 문서 생성이 가능합니다.
• 비동기 프로그래밍 지원: 비동기/동기 프로그래밍을 모두 지원해 빠른 데이터를 처리할 수 있습니다.

2. FastAPI 설치하기

FastAPI 프레임워크를 설치하려면 pip를 통해 간단히 설치할 수 있습니다. 아래 명령어를 사용하여 FastAPI와 uvicorn(ASGI 서버)을 설치하세요:

pip install fastapi uvicorn

3. 간단한 FastAPI 서버 만들기

FastAPI 애플리케이션을 만들기 위해 가장 먼저 해야 할 일은 FastAPI 클래스를 인스턴스화하는 것입니다. 아래의 코드는 “Hello, World!”를 반환하는 기본적인 FastAPI 서버 예제입니다.

from fastapi import FastAPI

app = FastAPI()

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

3.1. 서버 실행하기

위 코드를 my_app.py라는 파일로 저장한 후, 다음과 같은 명령어로 서버를 실행합니다:

uvicorn my_app:app --reload

이제 브라우저에서 http://127.0.0.1:8000를 열면 “Hello, World!” 메시지를 확인할 수 있습니다.

4. 경로와 HTTP 메서드

FastAPI에서는 다양한 HTTP 메서드를 사용하여 경로를 정의할 수 있습니다. 주로 사용되는 메서드는 다음과 같습니다:

• GET: 데이터 조회
• POST: 데이터 생성
• PUT: 데이터 업데이트
• DELETE: 데이터 삭제

4.1. GET 메서드 사용하기

GET 메서드를 사용하여 특정 경로에 대한 요청을 처리하는 예제를 살펴보겠습니다. 아래 코드는 /items/{item_id} 경로에 대한 GET 요청을 처리합니다.

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

이 코드는 /items/1?q=example와 같은 요청을 처리하며, 응답은 다음과 같습니다:

{"item_id": 1, "query": "example"}

4.2. POST 메서드 사용하기

POST 메서드는 서버에 새로운 데이터를 생성하는 데 사용됩니다. 다음 예제에서는 새 아이템을 추가하는 POST 요청을 처리합니다.

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": item}

클라이언트에서 application/json 포맷으로 데이터를 전송하면 FastAPI는 자동으로 데이터를 검증하고 파싱하여 item으로 전달합니다.

4.3. PUT 메서드 사용하기

PUT 메서드는 기존 데이터를 업데이트하는 데 사용됩니다. 아래 코드는 특정 아이템을 업데이트하는 예제입니다.

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "updated_item": item}

4.4. DELETE 메서드 사용하기

DELETE 메서드는 특정 아이템을 삭제하는 데 사용됩니다. 다음 코드는 특정 아이템을 삭제하는 경로를 정의합니다.

@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"message": f"Item with id {item_id} deleted"} 

5. 경로 동작 함수 파라미터

FastAPI의 경로 동작 함수에서는 입력 파라미터를 다양하게 정의할 수 있습니다. FastAPI는 자동으로 요청 본문, 쿼리 매개변수, 경로 매개변수를 검증합니다.

• 경로 매개변수: 경로의 경로 변수에 대응하는 파라미터입니다.
• 쿼리 매개변수: URL의 쿼리 문자열에 따라 전달되는 파라미터입니다.
• 본문 데이터: POST, PUT 요청과 함께 전송되는 데이터

5.1. 쿼리 파라미터 예제

@app.get("/items/")
async def read_items(q: str = None):
    return {"query": q}

5.2. 본문 파라미터 예제

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

6. 데이터 검증 및 설정 관리

FastAPI는 편리한 데이터 검증을 위해 Pydantic 모델을 활용합니다. 모델 클래스는 데이터 유효성 검사 및 설정 관리를 가능하게 합니다.

6.1. Pydantic 모델 정의하기

from pydantic import BaseModel

class User(BaseModel):
    name: str
    email: str
    age: int = None

6.2. 모델 사용 예제

@app.post("/users/")
async def create_user(user: User):
    return {"name": user.name, "email": user.email}

7. API 문서 자동 생성

FastAPI는 Swagger UI와 ReDoc을 지원하여 API 문서를 자동으로 생성합니다. Swagger UI는 http://127.0.0.1:8000/docs에서 조회할 수 있으며, ReDoc은 http://127.0.0.1:8000/redoc에서 조회할 수 있습니다. FastAPI는 IO-bound 작업을 처리하기 위해 asyncio를 사용하여 비동기적인 코드를 작성하는 것이 가능합니다.

8. FastAPI 프로젝트 구조

일반적인 FastAPI 프로젝트 구조는 다음과 같습니다:

my_fastapi_app/
├── app/
│   ├── main.py
│   ├── models.py
│   ├── routers/
│   └── services/
└── requirements.txt

이 구조는 더 큰 규모의 FastAPI 애플리케이션에서 유용하며, 각 구성요소를 분리하여 유지보수를 용이하게 합니다.

9. 결론

FastAPI는 매우 강력하고 직관적인 웹 프레임워크로, 쉬운 API 개발과 데이터 검증을 가능하게 합니다. 본 강좌에서는 FastAPI의 기본적인 경로 동작 함수를 만드는 방법을 배웠습니다. FastAPI를 사용하면 빠르고 효율적인 백엔드 서버 개발이 가능하니, 실무에 적용해 보시기를 추천합니다.

재능있는 개발자가 되기를 응원하며, 더 많은 정보를 원하시면 FastAPI 공식 문서를 참조하시기 바랍니다.

작성자: 조광형

날짜: 2024년 11월 26일

1. FastAPI란?

FastAPI는 Python의 비동기 웹 프레임워크로, API 서버를 개발하는 데 최적화되어 있습니다. Python의 타입 힌트를 활용하여 강력한 데이터 검증 및 문서화 기능을 제공합니다. FastAPI는 스타트업에서 대규모 애플리케이션에 이르기까지 다양한 프로젝트에 적합하며, OpenAPI와 JSON Schema를 지원하여 자동으로 API 문서를 생성합니다. 이러한 특징 덕분에 FastAPI는 효율적이고 명확한 API 서버 개발을 가능하게 합니다.

2. FastAPI 설치

FastAPI는 pip를 사용하여 간편하게 설치할 수 있습니다. 프로젝트를 시작하기 위해 가상 환경을 설정하고 FastAPI와 Uvicorn(ASGI 서버)을 설치하는 방법은 다음과 같습니다.

bash
# 가상 환경 설정
python -m venv venv
source venv/bin/activate  # 리눅스/Mac
venv\Scripts\activate  # 윈도우

# FastAPI와 Uvicorn 설치
pip install fastapi uvicorn
            

이제 FastAPI를 사용할 준비가 되었습니다.

3. 이벤트 문서 클래스란?

이벤트 문서 클래스는 특정 이벤트에 대한 정보를 담고 있는 데이터 모델을 정의합니다. FastAPI는 Pydantic을 사용하여 데이터 모델을 정의하고 검증합니다. 예를 들어, 이벤트의 제목, 설명, 발생 일시 등을 포함하는 이벤트 모델을 만들어 보겠습니다.

python
from pydantic import BaseModel
from datetime import datetime

class Event(BaseModel):
    title: str
    description: str
    event_date: datetime
    location: str
            

이벤트 모델은 FastAPI의 요청 및 응답 본문에서 사용할 수 있습니다. 이 모델을 활용하면 API에서 수신되는 데이터의 유효성을 검사하고, 자동으로 문서화할 수 있습니다.

4. FastAPI 라우트 설정

라우트는 HTTP 요청에 대한 핸들러 역할을 합니다. FastAPI에서 라우트를 설정하려면 인스턴스를 생성한 후 데코레이터를 사용하여 경로를 정의합니다. 다음은 기본적인 FastAPI 애플리케이션 및 이벤트 모델을 활용한 API 라우트 설정 예제입니다.

python
from fastapi import FastAPI
from typing import List

app = FastAPI()

# 이벤트 리스트
events: List[Event] = []

# 이벤트 생성
@app.post("/events/", response_model=Event)
async def create_event(event: Event):
    events.append(event)
    return event

# 모든 이벤트 조회
@app.get("/events/", response_model=List[Event])
async def get_events():
    return events
            

위 코드는 이벤트를 생성하는 POST 요청과 모든 이벤트를 조회하는 GET 요청을 처리합니다.

5. 라우트 변경 및 추가 기능 구현

이제 기본적인 CRUD(Create, Read, Update, Delete) 기능을 갖춘 이벤트 API를 확장해 보겠습니다. 여기서는 이벤트 업데이트 및 삭제 기능을 추가하는 방법을 설명하겠습니다.

python
from fastapi import HTTPException

# 이벤트 업데이트
@app.put("/events/{event_id}", response_model=Event)
async def update_event(event_id: int, updated_event: Event):
    if event_id < 0 or event_id >= len(events):
        raise HTTPException(status_code=404, detail="Event not found")
    events[event_id] = updated_event
    return updated_event

# 이벤트 삭제
@app.delete("/events/{event_id}", response_model=Event)
async def delete_event(event_id: int):
    if event_id < 0 or event_id >= len(events):
        raise HTTPException(status_code=404, detail="Event not found")
    deleted_event = events.pop(event_id)
    return deleted_event
            

이 코드는 이벤트를 업데이트하는 PUT 요청과 삭제하는 DELETE 요청을 처리합니다. 각각의 요청은 이벤트의 ID를 경로 매개변수로 사용하여 특정 이벤트를 관리할 수 있도록 합니다.

6. 데이터베이스와의 통합

FastAPI 애플리케이션은 데이터베이스와 쉽게 통합할 수 있습니다. SQLAlchemy를 사용하여 데이터베이스와의 상호작용을 구현하는 방법을 살펴보겠습니다. 다음은 SQLite 데이터베이스에 연결하고 이벤트 모델을 저장하고 가져오는 방법의 예시입니다.

python
from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from sqlalchemy import create_engine

Base = declarative_base()

class EventORM(Base):
    __tablename__ = "events"
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String)
    description = Column(String)
    event_date = Column(DateTime)
    location = Column(String)

# SQLite 데이터베이스 연결
engine = create_engine("sqlite:///./events.db")
Base.metadata.create_all(bind=engine)

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# FastAPI 라우트에서 사용
@app.post("/events/", response_model=Event)
async def create_event(event: Event):
    db = SessionLocal()
    db_event = EventORM(**event.dict())
    db.add(db_event)
    db.commit()
    db.refresh(db_event)
    db.close()
    return db_event
            

위의 코드는 SQLite 데이터베이스에 이벤트 데이터를 저장하는 방법을 보여줍니다. SQLAlchemy를 사용하여 데이터베이스 연결과 ORM(Object-Relational Mapping) 설정을 하였습니다.

7. 비동기 작업 및 성능 최적화

FastAPI는 비동기 작업을 쉽게 처리할 수 있도록 설계되었습니다. 데이터베이스 작업을 비동기로 처리하면, 성능을 더욱 향상시킬 수 있습니다. SQLAlchemy의 비동기 기능을 사용하는 방법은 다음과 같습니다.

python
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

Base = declarative_base()
DATABASE_URL = "sqlite+aiosqlite:///./events.db"

# 비동기 데이터베이스 엔진
async_engine = create_async_engine(DATABASE_URL, echo=True)
AsyncSessionLocal = sessionmaker(async_engine, expire_on_commit=False, class_=AsyncSession)

@app.post("/events/", response_model=Event)
async def create_event(event: Event):
    async with AsyncSessionLocal() as session:
        db_event = EventORM(**event.dict())
        session.add(db_event)
        await session.commit()
        await session.refresh(db_event)
        return db_event
            

위의 코드는 비동기 세션을 사용하여 데이터베이스에 이벤트를 저장하는 방법을 보여줍니다. 성능 향상을 위해 비동기 작업을 활용할 수 있습니다.

8. API 문서화

FastAPI의 강력한 기능 중 하나는 자동으로 API 문서를 생성하는 것입니다. Swagger UI와 ReDoc을 기본적으로 지원하여, 작성한 API를 쉽게 문서화하고 테스트할 수 있습니다. FastAPI 애플리케이션을 실행한 후 http://localhost:8000/docs 또는 http://localhost:8000/redoc에 접속하여 문서를 확인할 수 있습니다.

9. 애플리케이션 실행하기

FastAPI 애플리케이션을 실행하려면, Uvicorn을 사용하여 서버를 실행할 수 있습니다. 아래 명령어를 통해 FastAPI 서버를 실행하세요.

bash
uvicorn main:app --reload
            

여기서 main은 Python 파일의 이름이며, app는 FastAPI 인스턴스의 이름입니다. --reload 옵션을 사용하면 코드 변경 시 자동으로 서버가 재시작됩니다.

10. 결론

이번 글에서는 FastAPI를 사용하여 이벤트 문서 클래스를 정의하고, 다양한 라우트를 설정하는 방법을 살펴보았습니다. 데이터베이스와의 통합 및 비동기 작업을 통해 더 나아가 성능 최적화 방법까지 알아보았습니다. FastAPI의 유용한 기능들을 활용하여 강력하고 유연한 API 서버를 구축할 수 있습니다.

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에 대한 깊이 있는 이해를 바탕으로 복잡한 어플리케이션을 개발해보시길 바랍니다.

감사합니다!

최근 들어 웹 애플리케이션 개발에 있어 FastAPI는 그 빠른 성능과 사용의 용이성 덕분에 많은 인기를 끌고 있습니다. 특히 비동기 처리를 지원하여 높은 처리량을 요구하는 애플리케이션에 적합합니다. 이번 글에서는 FastAPI를 사용한 서버 개발 과정과 함께 Poetry를 활용한 파이썬 환경 관리 방법에 대해 자세히 알아보겠습니다.

1. FastAPI란?

FastAPI는 Starlette 위에 구축된 현대적인 웹 프레임워크로, 빠르고 효율적인 API 개발을 위한 도구입니다. Python 3.6 이상에서 사용할 수 있으며, 주요 특징으로는 다음과 같은 점들이 있습니다:

• 빠른 성능: FastAPI는 비동기 및 동기 기능 모두를 지원하며, Uvicorn 서버 위에서 매우 빠르게 작동합니다.
• 자동 문서화: API를 정의할 때 사용한 타입 힌트에 기반하여 Swagger UI와 Redoc을 자동 생성합니다.
• 간편한 입력 검증: Pydantic을 통해 요청 데이터의 검증과 직렬화/역직렬화를 손쉽게 처리할 수 있습니다.

2. Poetry란?

Poetry는 Python 프로젝트 관리를 위한 도구로, 패키지 의존성 관리와 프로젝트 환경을 통합적으로 제공합니다. 다른 패키지 관리 툴들과의 차별점은 다음과 같습니다:

• 간편한 의존성 관리: Poetry는 pyproject.toml 파일에 의존성을 명세하며, 이를 통해 의존성 충돌을 방지합니다.
• 가상 환경 자동 생성: 각 프로젝트별로 독립적인 가상 환경을 자동으로 생성하고 활성화합니다.
• 버전 잠금: poetry.lock 파일에 버전을 잠궈 재현 가능한 환경을 제공합니다.

3. FastAPI 서버 개발 환경 구축하기

3.1. Poetry 설치

Poetry를 설치하기 위해 다음 명령어를 사용합니다:

curl -sSL https://install.python-poetry.org | python3 -

설치 후, 아래 명령어로 PATH를 설정합니다:

export PATH="$HOME/.local/bin:$PATH"

3.2. 새 프로젝트 생성

이제 새로운 FastAPI 프로젝트를 생성해 보겠습니다. 프로젝트 폴더를 만들어주고 해당 폴더로 이동한 후, Poetry로 새 프로젝트를 초기화합니다:

mkdir my_fastapi_project
cd my_fastapi_project
poetry init

변수에 대한 질문이며, 기본값을 사용하거나 필요한 정보를 입력합니다. 이후, Poetry가 생성한 pyproject.toml 파일이 프로젝트 루트 디렉토리에 생성됩니다.

3.3. FastAPI 및 Uvicorn 설치

FastAPI와 Uvicorn을 설치합니다. Uvicorn은 ASGI 서버로, FastAPI 애플리케이션을 실행할 수 있게 해줍니다:

poetry add fastapi uvicorn

4. FastAPI 애플리케이션 구현하기

4.1. 기본 FastAPI 애플리케이션

프로젝트 디렉토리에 main.py 파일을 생성하고 아래와 같이 내용을 작성합니다:

from fastapi import FastAPI

app = FastAPI()

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

4.2. 서버 실행

이제 서버를 실행해볼 차례입니다. 아래 명령어를 입력하면 Uvicorn 서버가 실행됩니다:

poetry run uvicorn main:app --reload

브라우저에서 http://127.0.0.1:8000로 접근하면 “Hello, World!” 메시지를 확인할 수 있습니다. 또한, Swagger UI는 http://127.0.0.1:8000/docs에서 확인 가능합니다.

5. 데이터 모델 정의 및 CRUD API 만들기

5.1. Pydantic 모델 생성

Pydantic을 사용하여 데이터 모델을 정의합니다. models.py 파일을 생성하고 다음 코드를 추가합니다:

from pydantic import BaseModel

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

5.2. CRUD 기능 구현

이제 main.py 파일에 CRUD 기능을 구현해 보겠습니다. 간단한 메모리 데이터베이스를 사용하여 데이터를 저장하고 조회하는 기능을 추가합니다:

from fastapi import FastAPI
from typing import List
from models import Item

app = FastAPI()

items = {}

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

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

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    return items[item_id]

@app.put("/items/{item_id}", response_model=Item)
async def update_item(item_id: int, item: Item):
    items[item_id] = item
    return item

@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    del items[item_id]
    return {"message": "Item deleted"}

5.3. 테스트

서버를 실행한 후, Swagger UI를 통해 API를 테스트할 수 있습니다. 각 메서드를 클릭하여 요청을 보내고 응답을 확인합니다.

6. 마무리 및 추가 리소스

FastAPI와 Poetry를 통한 개발 환경 구축 과정을 살펴보았습니다. 이러한 도구들은 특히 비동기 기능과 작업의 단순성을 제공하므로, 빠르게 RESTful API를 개발할 수 있게 도와줍니다.

FastAPI에 대해 더 알고 싶다면 공식 문서와 다양한 튜토리얼을 참고해 보세요:

• FastAPI 공식 문서
• Poetry 공식 문서

이 튜토리얼을 통해 FastAPI와 Poetry의 기초를 익히고, 실무에서의 활용에 대한 감각을 익히셨기를 바랍니다. Happy Coding!