반응형
FastAPI 튜토리얼 영상 보면 늘 이런 생각 들더라.
“오케이…
Hello World는 알겠고… 그래서 프로젝트는 어떻게 ‘살아있는 형태’로 시작하지?”
그래서 오늘은 내가 파이썬 학습 겸 FastAPI를 제대로 감 잡기 위해 만들었던 Doubles 서버 코드를 기준으로, 연재를 시작해보려고 한다.
이 연재는 “작고 간단한 예제”가 아니라, 문서/설정/라우터/DB/테스트/도커까지 한 번에 만져보면서 학습한 것들을 잘게 쪼개서 기록하는 게 목표다.
이 연재에서 다룰 것(미리보기)
- 부트스트랩: app factory, lifespan,
app.state - 설정:
.env+pydantic-settings+ prefix 설계 - 라우팅: root vs
/api/v1, 도메인 라우터 분리 - DB: SQLModel + SQLite + JSON 컬럼
- 입력 검증:
Form/File/UploadFile+ 제한 + 422 - 외부 연동: httpx + WeatherAPI, 에러 매핑
- AI 연동: Gemini JSON schema 응답 강제 + 프롬프트 파일
- 테스트:
dependency_overrides+AsyncMock - (옵션) Docker/Compose
프로젝트 구조(모노레포라서 더 현실적임)
doubles-1은 모노레포 형태다.
doubles-1/
apps/
server/ # FastAPI 서버
mobile/ # React Native 앱
docs/ # 기획/스펙 문서 (꽤 중요)서버 코드만 보면 대충 이런 느낌.
apps/server/
app/
main.py # FastAPI 진입점(실제는 app/main.py)
api/ # 라우터/DI
core/ # Settings
db/ # SQLModel 세션/엔진
models/ # DB 모델
schemas/ # API 스키마
services/ # 외부 API, AI 등
tests/로컬 실행(uv + uvicorn)
서버 README에 적힌 실행 커맨드는 이거.
cd apps/server
uv run uvicorn app.main:app --reload여기서 uv랑 uvicorn을 짧게만 정리해보면:
- uv: 파이썬 패키지 설치/실행을 빠르게 해주는 도구다.
uv run ...은 “(이 프로젝트가 쓰는 가상환경/의존성 컨텍스트로) 다음 커맨드를 실행해줘”에 가깝다. - uvicorn: FastAPI(정확히는 ASGI 앱)를 실제로 띄워주는 웹 서버다.
app.main:app은 “app/main.py안의app객체”를 뜻한다. - --reload: 코드가 바뀌면 서버가 자동으로 재시작되는 개발용 옵션이다.
실행하고 나면 여기로 들어가면 된다.
- Swagger:
http://127.0.0.1:8000/docs
“한 방”으로 서버 살아있는지 확인
헬스체크는 /health.
curl -sS http://127.0.0.1:8000/health응답은 이런 형태.
{"status":"ok","app_name":"Doubles API"}이게 되면 일단 “서버가 뜨고, 설정이 로드되고, 라우터가 붙었다” 까지는 확인된 거다.
다음 편 예고
다음 편에서는 create_app() 패턴을 본다.
- 왜 굳이
app = FastAPI()를 전역에서 바로 만들지 않고 팩토리로 빼는지 lifespan에서 DB를 어떻게 초기화하는지- 그리고
app.state에 뭘 넣고 왜 넣는지
이게 익숙해지면 FastAPI가 “프레임워크”로 보이기 시작한다. (진짜로)
참고/더 읽기
반응형
