FastAPI 보일러 플레이트

시리즈, 입문

2024. 6. 3. PM 2:53:30

#fastapi, #boilerplate, #보일러플레이트, #router

Poetry 초기화

이 프로젝트에서는 Poetry로 패키지 관리를 할 거예요. 그래서 먼저 Poetry로 프로젝트를 초기화합니다. 먼저 Poetry를 설치합니다.

pip install poetry

이번엔 Poetry 프로젝트를 초기화해요.

poetry init

몇 가지 물어보는데, 현 단계에서 중요한 정보는 아니니 편하게 입력하셔도 돼요.

초기화를 마치면 pyproject.toml 파일이 생기는데, 앞으로 이 파일이 있는 경로를 최상위 경로라고 칭할게요.

FastAPI 설치

FastAPI 설치는 FastAPI만 설치하거나 FastAPI가 의존하는 다른 패키지도 함께 설치하는 방법이 있어요. 신경쓸 것 없이 다함게 설치할게요. 최상위 경로에서 FastAPI 패키지를 설치합니다.

poetry add "fastapi[all]"

가장 최신 버전은 0.111인데, 0.111 버전에 처음으로 FastAPI CLI 도구가 추가됐어요. 이 도구도 써볼 겸 0.111 버전을 사용할게요.

프로젝트 파일과 디렉터리 구조 구성

이 프로젝트의 파일과 디렉터리는 최상위 경로에 크게 두 개 디렉터리를 만드는 걸로 시작해요. pudding_todo는 구현 파일이 위치하고, tests는 테스팅을 담은 파일이 위치하죠.

최상위 경로에 pudding_todo 디렉터리를 만들고, 이 디렉터리에 빈 파일로 __init__.py 를 만들어요.

pudding_todo 디렉터리는 Python 에서 패키지 역할을 할 거예요. from pudding_todo import ... 와 같은 이름경로가 되는 거죠.

FastAPI 애플리케이션 생성

pudding_todo 디렉터리에 app.py 파일을 만들고, 그 안에 FastAPI 애플리케이션의 인스턴스 객체를 만듭니다.

# pudding_todo/app.py

from fastapi import FastAPI

app = FastAPI()

잘 동작하는지 확인해볼까요? 최상위 경로에서 FastAPI CLI 도구를 이용해 웹 서버를 생성해 실행합니다.

fastapi dev pudding_todo/app.py

실행하면 8000번 포트로 웹 애플리케이션 서버가 실행돼요.

FastAPI의 웹 구현체 근간인 Starlette을 이용해 웹 애플리케이션 서버가 실행됐어요. 웹 브라우저로 접속해볼까요?

웹 브라우저에서 http://localhost:8000으로 접속하면 Not Found라는 문구가 출력돼요. 아직 최상위 URL 경로에 대응하는 구현을 하지 않아서 그래요. 오류 화면 보는 것 같으니 뭔가 동작하는 화면을 볼게요. FastAPI는 문서화 기능을 제공하는데, OpenAPI 3 Specification과 Redoc 형식을 제공해요.

http://localhost:8000/docs에 접근하면 OpenAPI 3 Spec 페이지가, http://localhost:8000/redoc에 접근하면 Redoc 페이지가 나와요.

Hello World

이번엔 Not Found 대신 Hello World를 출력해볼게요. 구현하기 쉽고 간단해요.

pudding_todo 디렉터리 안에 apps 디렉터리를 만들고, 그 안에 __init__.py 파일을 만듭니다. 그리고 apps 디렉터리 안에 common 디렉터리를 만들고, 마찬가지로 __init__.py 파일을 만들고요. common 디렉터리에 endpoints.py 파일을 하나 더 만들어서 이 파일에 종단점(Endpoint)을 만들게요. 최상위 URL 경로에 접근하면 바로 이 종단점이 동작하게 할 거예요.

# pudding_todo/apps/common/endpoints.py

from fastapi import APIRouter

router = APIRouter()


@router.get('/')
async def toppage() -> dict:
    return {
        'message': 'Hello, world!',
    }

APIRouter 클래스가 처음 등장했는데, 이어서 나오는 구현까지 마저 한 후에 살펴볼게요.

이번엔 common 디렉터리에 router.py 파일을 만들고 endpoints.py 모듈에 있는 router를 Router에 등록합니다.

# pudding_todo/apps/common/router.py

from fastapi import APIRouter
from .endpoints import router as common_router

router = APIRouter()
router.include_router(common_router)

common이라 이름이 붙은 애플리케이션(컴포넌트)에서 사용하는 Router를 FastAPI 애플리케이션에 등록할게요. 그래야 비로소 FastAPI가 우리가 만든 종단점을 URL 경로에 연결지어요.

# pudding_todo/app.py

from fastapi import FastAPI
from pudding_todo.apps.common.router import router as common_router

app = FastAPI()
app.include_router(common_router)

APIRouter로 만든 Router 인스턴스 객체는 FastAPI 애플리케이션 객체의 include_router() 메서드로 FastAPI 애플리케이션 서버에 등록해요.

변경한 파일을 저장하면 웹 애플리케이션 서버가 자동으로 변경사항을 반영해요. 웹 브라우저를 열고 https://localhost:8000 에 다시 접근해보면 이번엔 Hello, World! 문구가 출력돼요.

지금까지 작성한 코드는 2bf9392 커밋에서 확인하실 수 있어요.

Router에 단계가 있어 복잡하게 보이죠?

FastAPI Application
└─ apps.common.router
   └─ apps.common.router.endpoints.router

이렇게 단계를 거쳐가는 것은 종단점 Router를 관리하기 편하게 하는 게 목적이예요. 예를 들어, 종단점 함수가 20개이고, 비슷한 맥락끼리 Python 모듈(파일) 단위로 묶었다고 칠게요. endpoints/hello.py와 endpoints/landing.py, 이렇게 두 개 파일이 있으면, 각 파일에 APIRouter 클래스로 라우터를 만들게 되죠.

FastAPI Application
├─ apps.common.router
│  └─ apps.common.router.endpoints.hello.router
│  └─ apps.common.router.endpoints.landing.router
└─ apps.account.router
   ├─ apps.common.router.endpoints.auth.router
   └─ apps.common.router.endpoints.profile.router

이런 식으로 구조화를 하고, FastAPI 애플리케이션은 apps 패키지에 있는 각 애플리케이션의 router만 포함시키면(include) 되도록 구성한 거예요.

학습이 이뤄지고 있는지 확신이 안 서나요?
사수가 없나요?
효과적이고 효율적으로 학습하며 성장하는
자기만의 학습과 성장 체계를 만들 수 있습니다.
연사자들의 각양각색 학습과 성장 스토리로
여러분의 학습과 성장을 키워보세요.

푸딩캠프 뉴스레터를 구독하면 학습과 성장, 기술에 관해 요약된 컨텐츠를 매주 편하게 받아보실 수 있습니다.

뉴스레터 구독하기

이전 컨텐츠

다음 컨텐츠