FastAPI 서버개발, FastAPI 애플리케이션 구조화

FastAPI는 현대적이고, 빠르며, 비동기적이며, 쉬운 RESTful API를 만드는 데 사용할 수 있는 훌륭한 프레임워크입니다. FastAPI를 사용하여 서버를 개발할 때, 애플리케이션 구조화는 확장성, 유지 보수성 및 팀 작업을 고려할 때 매우 중요한 요소입니다. 이 글에서는 FastAPI 애플리케이션을 구조화하는 방법에 대해 자세히 탐구해 보겠습니다.

1. FastAPI 소개

FastAPI는 Python 3.7 이상에서 사용할 수 있는 웹 프레임워크입니다. Starlette과 Pydantic을 기반으로 하여 빠른 속도와 높은 성능을 자랑합니다. FastAPI는 데이터 검증, 순서 매기기, 문서화 등의 기능을 내장하고 있어 개발자가 API를 더 쉽게 만들 수 있도록 도와줍니다. 또한, OpenAPI 스펙을 자동으로 생성하여 API 문서화를 빠르고 쉽게 할 수 있습니다.

FastAPI의 주요 특징

  • 비동기 지원: FastAPI는 비동기 프로그래밍을 지원하여 높은 성능을 제공합니다.
  • 자동화된 데이터 검증: Pydantic을 사용하여 입력 데이터를 자동으로 검증합니다.
  • 자동 생성된 API 문서: Swagger UI 및 ReDoc을 사용하여 API 문서를 자동으로 생성합니다.
  • 사용의 용이성: 개발자가 최소한의 코드로 API를 개발할 수 있도록 설계되었습니다.

2. FastAPI 애플리케이션 구조화의 필요성

대규모 애플리케이션에서 코드의 유지 보수성 및 확장성을 높이기 위해서는 명확한 구조화가 필수적입니다. FastAPI 애플리케이션을 구조화하는 방법은 다음과 같습니다:

  • 모듈화: 관련 성격을 가진 구성 요소들을 모아서 모듈 단위로 관리합니다.
  • 디렉토리 구조: 명확한 디렉토리 구조를 설계하여 코드의 가독성을 높입니다.
  • 프레임워크 활용: FastAPI의 내장 기능을 최대한 활용하여 반복된 코드를 줄입니다.

2.1 모듈화

모듈화를 통해 애플리케이션의 특정 기능이나 역할을 별도의 파일이나 디렉토리로 나누어 관리할 수 있습니다. 예를 들어, 사용자 인증, 데이터베이스 접근, API 라우팅 등을 각각의 모듈로 나누어 관리합니다.

2.2 디렉토리 구조

애플리케이션의 디렉토리 구조는 다음과 같은 형태로 구성할 수 있습니다:


my_fastapi_app/
├── app/
│   ├── main.py
│   ├── models/
│   │   └── user.py
│   ├── schemas/
│   │   └── user.py
│   ├── routes/
│   │   └── user.py
│   ├── database/
│   │   └── db.py
│   └── services/
│       └── user.py
└── requirements.txt

위의 디렉토리 구조는 FastAPI 애플리케이션의 기본적인 구조를 보여줍니다. 각 디렉토리의 역할은 다음과 같습니다:

  • main.py: FastAPI 애플리케이션의 진입점입니다. 모든 라우터를 포함하고, 데이터베이스 연결 등의 초기 설정을 수행합니다.
  • models: 데이터베이스 모델을 정의하는 곳입니다.
  • schemas: 데이터 검증 및 직렬화를 위한 Pydantic 모델을 정의합니다.
  • routes: API 엔드포인트를 설정합니다.
  • database: 데이터베이스 연결 및 세션 관리 관련 코드를 포함합니다.
  • services: 비즈니스 로직을 구현한 것입니다.

3. FastAPI 애플리케이션 구축 예제

이제 FastAPI 애플리케이션을 실제로 구축하는 과정을 단계별로 살펴보겠습니다.

3.1 환경 설정

먼저 FastAPI와 데이터베이스 클라이언트인 SQLAlchemy를 설치합니다. requirements.txt 파일에 다음과 같은 내용을 작성합니다:


fastapi
uvicorn
pydantic
sqlalchemy
databases

이제 다음 명령어를 통해 패키지를 설치합니다:

pip install -r requirements.txt

3.2 데이터베이스 설정

PostgreSQL 데이터베이스를 사용할 경우, 먼저 .env 파일을 만들어 환경 변수를 설정해야 합니다. .env 파일의 내용은 다음과 같습니다:


DATABASE_URL=postgresql://username:password@localhost/dbname

database/db.py 파일을 작성하여 데이터베이스 연결을 설정합니다:


from sqlalchemy import create_engine, MetaData
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
import databases
import os

DATABASE_URL = os.getenv('DATABASE_URL')

database = databases.Database(DATABASE_URL)
metadata = MetaData()
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

3.3 모델 만들기

models/user.py 파일에서 User 모델을 정의합니다:


from sqlalchemy import Column, Integer, String
from ..database.db import Base

class User(Base):
    __tablename__ = 'users'

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    email = Column(String, unique=True, index=True)

3.4 스키마 만들기

schemas/user.py 파일에서 Pydantic 모델을 정의합니다:


from pydantic import BaseModel

class UserBase(BaseModel):
    username: str
    email: str

class UserCreate(UserBase):
    password: str

class User(UserBase):
    id: int

    class Config:
        orm_mode = True

3.5 라우터 만들기

routes/user.py 파일에서 라우터를 정의합니다:


from fastapi import APIRouter, Depends
from ..models.user import User
from ..schemas.user import UserCreate, User
from ..database.db import SessionLocal

router = APIRouter()

@router.post("/users/", response_model=User)
async def create_user(user: UserCreate):
    async with SessionLocal() as db:
        db_user = User(username=user.username, email=user.email)
        db.add(db_user)
        await db.commit()
        await db.refresh(db_user)
        return db_user

3.6 메인 애플리케이션 설정

app/main.py 파일에서 FastAPI 애플리케이션을 구성합니다:


from fastapi import FastAPI
from .database.db import database
from .routes import user

app = FastAPI()

app.include_router(user.router)

@app.on_event("startup")
async def startup():
    await database.connect()

@app.on_event("shutdown")
async def shutdown():
    await database.disconnect()

3.7 서버 실행

이제 Uvicorn를 사용하여 서버를 실행할 준비가 되었습니다. 다음 명령어로 서버를 실행합니다:

uvicorn app.main:app --reload

3.8 Swagger UI로 테스트하기

서버가 실행되면 http://localhost:8000/docs에서 Swagger UI를 통해 API를 테스트할 수 있습니다. 이곳에서 생성한 API 엔드포인트를 자동으로 확인하고, 요청을 수행할 수 있습니다.

4. 결론

FastAPI는 현대적인 API를 개발하는 데 매우 유용한 프레임워크입니다. 애플리케이션을 구조화하는 것은 코드의 가독성, 유지 보수성 및 확장성을 높이는 데 중요한 역할을 합니다. 위에서 설명한 방법으로 FastAPI 애플리케이션의 구조를 설계하고 구현하면, 더욱 체계적이고 효율적인 백엔드 서버를 개발할 수 있습니다.

FastAPI의 다양한 기능을 최대한 활용하고, 모듈화 및 디렉토리 구조를 잘 설계하여 안정적이고 확장 가능한 애플리케이션을 구축해 보세요. 추가적인 조언과 도움을 원하신다면 FastAPI 문서 및 커뮤니티를 참고하시기 바랍니다.