[FastAPI] FastAPI 구조화 예제 튜토리얼, 폴더 구성과 라우터 분리

🎯 이전 포스팅에서 이어지는 내용입니다.

[FastAPI] FastAPI 시작하기: 설치부터 로컬 서버 실행까지 따라하기

 

FastAPI로 간단한 API를 만들었다면, 이제는 프로젝트를 구조화해보는 단계입니다. 규모가 커질수록 유지보수가 어려워지기 때문에, 체계적인 폴더 구성으로 코드를 분리해 보겠습니다.

이번 글에서는 라우터, 스키마, 유틸 함수까지 분리된 FastAPI 폴더 구조 예제를 소개하고, 실제 실행 및 테스트 방법까지 안내해드리겠습니다.

라우터, 스키마 관련 설명은 이전 글에 작성해 두었습니다. 

[FastAPI] FastAPI router, schemas

 

1️⃣. 폴더 구조 설명 

아래와 같은 폴더 구조를 만들겠습니다.

fastapi-v1/
└── app_v1/
    ├── main.py
    ├── router/
    │   ├── __init__.py   ✅ 라우터 등록용
    │   └── hello.py
    ├── schemas/
    │   └── hello.py
    ├── utilities/
    │   └── helpers.py
    └── config.py

📌 관련 코드 깃허브에서 한번에 확인하기

FastAPI-v1/app_v1 at main · hgk0404-v2/FastAPI-v1

2️⃣. 코드 

🔹 1. app_v1/main.py 

from fastapi import FastAPI
from routers import hello
import uvicorn

app = FastAPI()

# 라우터 등록
app.include_router(hello.router)

if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8081, reload=True)

 

🔹 2. app_v1/ config.py 

# 설정 예시
APP_NAME = "FastAPI Example"
VERSION = "0.1.0"

 

🔹 3. routers/hello.py 

from fastapi import APIRouter
from schemas.hello import HelloRequest, HelloResponse
from utilities.helpers import greet_user

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

@router.post("/", response_model=HelloResponse)
def say_hello(req: HelloRequest):
    message = greet_user(req.name)
    return HelloResponse(message=message)

🔹 3-1. routers/__init__.py 

모듈화를 위한 파일으로 그냥 빈 파일로 놔두시면 됩니다.

 

🔹 4. schemas/hello.py 

from pydantic import BaseModel

class HelloRequest(BaseModel):
    name: str

class HelloResponse(BaseModel):
    message: str

 

🔹 5. utilities/helpers.py 

def greet_user(name: str) -> str:
    return f"Hello, {name}! 👋"

 

3️⃣. 실행

저번 포스팅 때 생성했던 가상환경을 그대로 사용하겠습니다. 

# 실행 (포트는 8081번)
python main.py

OpenAPI로 접속해 보겠습니다. 

http://127.0.0.1:8081/docs

127.0.0.1:8081/docs

OpenAPI로 Post /hello에 접속하였습니다. 

 

4️⃣. 테스트 방법 

Try it out을 입력하여 "name"에 원하는 내용을 입력한 뒤 execute를 실행합니다.

저는 name의 value에 "멜론"을 넣었고

결과:

• Response body에 "멜론"이 출력되는 것을 확인할 수 있습니다.
• routers/hello.py에서 from utilities.helpers import greet_uesr를 해주었고, helpers.py에서 greet_user가 인자로 "멜론"을 받았기 때문에 위와 같이 출력 되었습니다.

이렇게 Swagger UI를 통해 바로 테스트 가능하며, request/response 모델도 자동으로 확인할 수 있습니다.

☑️ 폴더 분리: 

• 진입점(main), 라우터, 스키마, 유틸 분리
• Uvicorn으로 실행하고 Swagger로 테스트

다음 시간엔 이 구조 위에 데이터베이스 연동, 인증 기능, 미들웨어 설정들을 추가하는 프로젝트 구조를 만들어 보겠습니다.