FastAPI 프로젝트 구조

Padong/
├── app/
│   ├── main.py
│   ├── core/
│   │   ├── config.py
│   │   └── exceptions.py
│   ├── api/
│   │   ├── deps.py
│   │   └── v1/
│   │       ├── api.py
│   │       └── endpoints/
│   │           ├── health.py
│   │           └── users.py
│   ├── schemas/
│   │   └── user.py
│   ├── services/
│   │   └── user_service.py
│   ├── models/
│   │   └── user.py
│   ├── db/
│   │   ├── session.py
│   │   └── base.py
│   └── utils/
│       └── common.py
├── tests/
│   └── test_health.py
├── .env
├── .gitignore
├── requirements.txt
└── README.md

최상위 구조 설명

Padong/
├── app/
├── tests/
├── .env
├── .gitignore
├── requirements.txt
└── README.md

app/

실제 FastAPI 애플리케이션 코드가 들어가는 핵심 폴더다.
백엔드 로직은 거의 다 여기 들어간다고 보면 된다.

tests/

테스트 코드 전용 폴더다.
실제 코드와 테스트를 분리해서 관리한다.

.env

환경변수 파일이다.
비밀키, DB 주소, API 키 같은 값을 넣는다.

예:

DATABASE_URL=sqlite:///./test.db
SECRET_KEY=abc123
DEBUG=true

.gitignore

Git에 올리면 안 되는 파일 목록이다.

예:

venv/
.env
__pycache__/

requirements.txt

이 프로젝트에 필요한 라이브러리 목록이다.

예:

fastapi
uvicorn
sqlalchemy
pytest

다른 사람이 이 파일만 있으면 같은 환경을 설치할 수 있다.

README.md

프로젝트 설명서다.
이 프로젝트가 무엇인지, 어떻게 실행하는지, 어떤 API가 있는지 적는 파일이다.

app/ 폴더 상세 설명

app/
├── main.py
├── core/
├── api/
├── schemas/
├── services/
├── models/
├── db/
└── utils/

1. main.py

이 파일은 FastAPI 앱의 시작점이다.

쉽게 말하면:

FastAPI 앱을 생성하고
라우터를 등록하고
서버가 시작될 때 가장 먼저 읽는 파일

예:

from fastapi import FastAPI
from app.api.v1.api import api_router

app = FastAPI()
app.include_router(api_router, prefix="/api/v1")

main.py는 “이 프로젝트의 입구”라고 보면 된다.

2. core/

core/
├── config.py
└── exceptions.py

이 폴더는 프로젝트 전반에서 공통으로 쓰는 핵심 설정을 둔다.

config.py

환경설정 파일이다.

예:

앱 이름
디버그 모드
DB URL
JWT secret key
외부 API 키

즉, 여기서 “프로젝트 설정값”을 관리한다.

왜 필요하냐면 설정값이 코드 곳곳에 흩어지면 유지보수가 너무 어려워지기 때문이다.

exceptions.py

공통 예외처리를 정의하는 파일이다.

예:

사용자 없음
권한 없음
잘못된 요청
커스텀 에러 메시지

프로젝트가 커질수록 raise Exception(...) 식으로 아무렇게나 처리하면 정리가 안 되기 때문에,
예외를 통일해서 관리하려고 둔다.

3. api/

api/
├── deps.py
└── v1/
    ├── api.py
    └── endpoints/
        ├── health.py
        └── users.py

이 폴더는 실제로 API가 정의되는 곳이다.

-> URL 경로와 HTTP 메서드(GET, POST 등)를 다루는 영역이다.

deps.py

dependency 주입용 파일이다.

FastAPI는 Depends()를 많이 쓰는데, 이런 공통 의존성을 여기에 둔다.

예:

DB 세션 주입
현재 로그인 사용자 가져오기
토큰 검증
공통 권한 검사

즉, 반복적으로 쓰는 준비 작업을 모아놓는 곳이다.

v1/

API 버전 관리를 위한 폴더다.

예를 들어:

/api/v1/users
/api/v2/users

이렇게 버전이 바뀔 수 있으니까, 미리 v1로 나눠두면 나중에 확장하기 쉽다.

v1/api.py

버전 1의 전체 라우터를 모으는 파일이다.

예:

from fastapi import APIRouter
from app.api.v1.endpoints import health, users

api_router = APIRouter()
api_router.include_router(health.router)
api_router.include_router(users.router, prefix="/users", tags=["users"])

endpoints에 흩어진 여러 API를 하나로 묶는 역할이다.

v1/endpoints/

실제 엔드포인트 파일들이 들어간다.

도메인별로 나눈다고 보면 된다.

예:

users.py → 사용자 관련 API
posts.py → 게시글 관련 API
recommend.py → 추천 관련 API

health.py의 필요성

이건 되게 중요하다.

health.py는 보통 /health 같은 헬스 체크 API를 둔다.

예:

@router.get("/health")
def health_check():
    return {"status": "ok"}

이 API는 “서비스가 살아 있는지” 확인하는 용도다.

쓰이는 상황
서버가 정상 실행 중인지 확인
Docker / Kubernetes에서 컨테이너 상태 체크
배포 후 서버 점검
로드밸런서가 이 서버로 트래픽을 보내도 되는지 판단
모니터링 시스템에서 주기적으로 확인
쉽게 말하면

health.py는
“이 서버 안 죽었어요”를 알려주는 최소한의 점검 API다.

실무에서는 거의 항상 있다고 보면 된다 !

users.py

사용자 관련 API를 모아두는 파일이다.

예:

사용자 목록 조회
사용자 생성
사용자 상세 조회
사용자 수정 / 삭제

즉, 요청을 직접 받는 컨트롤러 역할이라고 보면 된다.

4. schemas/

schemas/
└── user.py

여기는 요청/응답 데이터 형식 즉 DTO를 정의하는 곳이다.
FastAPI에서는 보통 Pydantic 모델을 둔다.

예:

class UserCreate(BaseModel):
name: str
email: str

왜 필요하냐면:

요청값 검증 자동화
응답 형식 통일
Swagger 문서 자동 생성
타입 안정성 확보

즉,
“API가 어떤 데이터를 받고 어떤 데이터를 내보내는지”를 정의하는 곳이다.

user.py는 사용자 관련 schema를 모아둔 파일이다.

예:

UserCreate
UserUpdate
UserResponse

5. services/

services/
└── user_service.py

여기는 비즈니스 로직을 처리하는 곳이다.

중요한 포인트는,
엔드포인트 파일(users.py)에 로직을 다 넣지 않고 여기로 분리한다는 점이다.

예:

사용자 생성 규칙
이메일 중복 체크
비밀번호 처리
추천 알고리즘 호출
외부 API 연동

즉,
api는 요청을 받고
service는 실제 일을 한다.

user_service.py는 사용자 관련 핵심 로직을 넣는 파일이다.

6. models/

models/
└── user.py

여기는 DB 테이블 구조를 정의하는 곳이다.

예를 들어 SQLAlchemy를 쓰면:

class User(Base):
    \__tablename__ = "users"

이 파일은 데이터베이스와 직접 연결되는 구조를 정의한다.

user.py는 사용자 테이블 모델이라고 보면 된다.

schemas는 API 데이터 구조
models는 DB 데이터 구조 !!

7. db/

db/
├── session.py
└── base.py

DB 연결 관련 파일을 둔다.

session.py

데이터베이스 세션을 만드는 파일이다.

쉽게 말하면:

DB 연결 열기
세션 생성
세션 반환

이 세션이 있어야 DB 조회/저장 가능하다.

base.py

모델들이 공통으로 상속받는 Base를 정의하거나, 모델 import를 모아두는 파일이다.

Alembic 같은 마이그레이션 도구를 붙일 때도 자주 사용한다.

즉, DB 관련 공통 기반 파일이라고 보면 된다.

8. utils/

utils/
└── common.py

여기는 공통 유틸 함수들을 넣는다.

예:

날짜 포맷 변환
문자열 처리
공통 응답 함수
해시 계산
파일명 생성

즉, 여러 곳에서 반복적으로 쓰는 “작은 도구 함수”를 모아두는 곳이다.

common.py는 그런 공통 함수들을 넣기 위한 기본 파일명이다.

비즈니스 로직까지 여기 넣으면 안 된다.
정말 범용적인 보조 함수만 두는 게 좋다.

9. tests/

tests/
└── test_health.py

테스트 코드를 두는 폴더다.

test_health.py

헬스 체크 API 테스트 파일이다.

예:

/health 호출 시 200이 나오는지
응답이 {"status":"ok"} 인지

왜 필요하냐면,
가장 단순한 API부터 테스트가 돌아가는지 확인하기 좋기 때문이다.

보통 health API는 가장 먼저 만들고 가장 먼저 테스트하는 편이다.