FastAPI 기본 구조 설명과 예제 코드

FastAPI 기본 구조 설명과 예제 코드

FastAPI 기본 구조 설명과 예제 코드

🔥 FastAPI 기본 구조 설명과 예제 코드

Python으로 빠르고 직관적인 웹 API를 만들 수 있는 FastAPI는 최근 많은 개발자들 사이에서 인기를 얻고 있는 프레임워크입니다. 이 글에서는 FastAPI의 기본적인 프로젝트 구조를 살펴보고, 간단한 코드를 통해 그 구조가 어떻게 작동하는지 설명합니다.

📁 기본 프로젝트 구조

FastAPI 애플리케이션을 체계적으로 구성하려면 다음과 같은 폴더 구조를 추천합니다:

fastapi_app/
├── main.py
├── routers/
│   └── items.py
├── models/
│   └── item.py
├── schemas/
│   └── item_schema.py
└── requirements.txt

이 구조는 작은 프로젝트뿐 아니라 중·대형 프로젝트로 확장할 때도 유용합니다.

🧩 구성 요소 설명

1. main.py – 앱의 진입점

from fastapi import FastAPI
from routers import items

app = FastAPI()

app.include_router(items.router)

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

• FastAPI()로 앱 인스턴스를 생성합니다.

• include_router()를 통해 외부 모듈에 정의된 라우터를 앱에 등록합니다.

• / 루트 경로에 간단한 GET 요청 핸들러를 설정합니다.

2. routers/items.py – 라우터 분리

from fastapi import APIRouter
from schemas.item_schema import Item

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/")
def get_items():
    return [{"id": 1, "name": "Pen"}, {"id": 2, "name": "Notebook"}]

@router.post("/")
def create_item(item: Item):
    return {"message": "Item created", "item": item}

• APIRouter를 사용해 API 엔드포인트들을 모듈로 분리합니다.

• prefix="/items"는 이 라우터의 모든 경로 앞에 /items를 붙입니다.

• tags=["items"]는 자동 문서화(Swagger UI)에서 API 그룹을 정리하는 데 사용됩니다.

3. schemas/item_schema.py – 데이터 스키마 정의

from pydantic import BaseModel

class Item(BaseModel):
    id: int
    name: str
    description: str | None = None

• pydantic을 기반으로 데이터를 검증하고, 문서화에 필요한 정보도 자동으로 생성됩니다.

• Item 클래스는 POST 요청 시 요청 본문(request body)의 구조를 정의합니다.

4. requirements.txt – 의존성 관리

fastapi
uvicorn

• uvicorn은 ASGI 서버로, FastAPI 앱을 실행할 때 사용됩니다.

• 다음 명령어로 앱을 실행할 수 있습니다:

uvicorn main:app --reload

🚀 실행 예시

1. 프로젝트 폴더에서 위 구조대로 파일을 작성합니다.

2. uvicorn main:app --reload 명령어로 서버를 실행합니다.

3. 브라우저에서 http://127.0.0.1:8000/docs에 접속하면 자동 생성된 Swagger 문서를 확인할 수 있습니다.

카테고리 다른 글