IT 20년차의 복합 비즈니스 도전

이 시리즈의 궁극적 목적은 ‘Python 웹 개발의 필수 요소를 실무적으로 습득’하는 것입니다.

1. Poetry 및 FastAPI를 활용해 의존성 관리와 웹 프레임워크의 기초를 닦고,
2. 데이터베이스 연동, 인증, 배포와 같은 주요 기능을 단계별로 학습하며,
3. 실제 운영 환경에서 신뢰할 수 있는 백엔드 애플리케이션을 완성하는 것을 목표로 합니다.

안녕하세요! 이번 포스팅은 FastAPI 시리즈의 첫 번째 글로, Poetry와 FastAPI를 함께 사용하기 위한 기본 환경 설정을 다룹니다. 본 시리즈를 통해 Python 웹 개발의 핵심 요소(데이터베이스, 인증, 배포 등)를 단계별로 익혀, 실제 서비스를 구축할 수 있는 능력을 기르는 것을 지향합니다.

---

커리큘럼 개요

1. 1장: Poetry와 FastAPI 환경 설정
   • Poetry 소개 및 설치, FastAPI 기본 구조, VS Code 개발 환경 세팅, .env 활용 등
2. 2장: FastAPI 기본 구조 설계
   • 프로젝트 디렉토리 구성, APIRouter 활용, 라우팅 전략, OpenAPI 문서화 기초
3. 3장: 데이터베이스 연동
   • SQLAlchemy, Alembic으로 CRUD 구현, 마이그레이션 관리
4. 4장: API 설계 및 구현
   • RESTful 엔드포인트, Pydantic 스키마, 예외 처리, 자동 문서화
5. 5장: 인증 및 권한 관리
   • JWT 기반 사용자 로그인, OAuth2 Password Flow, 권한(Role) 설정
6. 6장: 테스트 및 디버깅
   • Pytest, TestClient를 통한 자동화 테스트, 디버깅 기법, 로깅 설정
7. 7장: 비동기 작업 및 배포
   • Celery + Redis를 활용한 비동기 처리, Docker Compose 기반 배포 전략
8. 8장: 종합 프로젝트 실습
   • 간단한 블로그 API 예제: DB 모델, 인증, 비동기 처리, Docker 배포까지
9. 9장: Google 로그인 연동
   • OAuth2 Social Login 전략, React 간단 예시 코드, FastAPI와의 통합 구현

---

1.1. Poetry 소개 및 설치

1.1.1. Poetry란 무엇인가?

Poetry는 Python 환경에서 패키지와 의존성을 깔끔하게 관리해주는 도구입니다. 기존 pip + venv 방식이나 pipenv 대비, 다음과 같은 장점이 있습니다:

• **pyproject.toml**을 통해 프로젝트 메타정보와 종속 패키지 목록을 일원화
• **가상 환경(virtual environment)**을 자동으로 생성 및 관리
• 의존성 충돌을 최소화하고, 버전 고정을 손쉽게 처리

Python 프로젝트를 팀 단위로 협업할 때, 혹은 멀티 환경(개발/테스트/프로덕션)에서 패키지 충돌을 방지하고 싶다면 Poetry를 사용하는 것이 권장됩니다.

1.1.2. 설치 방법

Windows/macOS/Linux에서 Poetry를 설치하는 일반적인 방법은 다음과 같습니다:

curl -sSL https://install.python-poetry.org | python3 -

설치 과정 후, poetry --version 명령어로 정상 설치 여부를 확인하세요.
만약 Poetry 경로가 인식되지 않는다면, export PATH="$HOME/.local/bin:$PATH" 등의 경로 설정을 해주어야 합니다.

---

1.2. FastAPI 프로젝트 초기화

1.2.1. 프로젝트 폴더 생성 및 Poetry 초기화

1. 작업할 디렉토리를 하나 만든 뒤 이동합니다:

   mkdir fastapi-poetry-app
   cd fastapi-poetry-app
   

2. Poetry를 이용해 프로젝트를 초기화합니다:

   poetry init
   

   • 프로젝트 이름, 버전, 설명 등을 입력하라고 나오며, 기본값으로 진행해도 괜찮습니다.
   • 이 과정을 마치면 pyproject.toml 파일이 생성됩니다.

1.2.2. FastAPI 및 Uvicorn 설치

이제 FastAPI와 ASGI 서버 Uvicorn을 Poetry로 설치합시다:

poetry add fastapi uvicorn

• fastapi: 핵심 웹 프레임워크
• uvicorn: ASGI 서버 구현체. 개발 시 --reload 옵션을 통해 코드 변경을 즉시 반영할 수 있음

설치가 완료되면 pyproject.toml과 poetry.lock에 의존성 정보가 기록됩니다.

1.2.3. 간단한 엔트리포인트 작성

프로젝트 내 app/main.py 파일을 생성해 간단한 Hello World 수준의 FastAPI 코드를 작성합니다:

# app/main.py
from fastapi import FastAPI

app = FastAPI()

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

---

1.3. VS Code 개발 환경 설정

1.3.1. Poetry 가상 환경 인식

Poetry가 생성한 가상 환경을 VS Code에서 인식시키려면 다음 과정을 거칠 수 있습니다:

1. VS Code 좌측 하단의 Python 버전/인터프리터 선택 영역을 클릭
2. "Select Interpreter" → "Enter interpreter path" → Poetry 가상 환경 경로 선택
   • poetry env info --path 명령어로 가상 환경 디렉토리를 확인할 수 있습니다.

1.3.2. 유용한 확장 기능

1. Python 확장: 기본적인 코드 자동 완성, 린트, 디버깅
2. Pylance: 타입 체크와 인텔리센스 성능 향상
3. Black / isort / Flake8: 코드 포매팅 및 스타일 검사
4. Docker (선택): Docker를 활용한 배포, 컨테이너 관리 시 유용

1.3.3. 린팅 & 포매터 도구 추가 (선택)

개발 환경을 더 깔끔하게 유지하려면 다음과 같이 Poetry에 린팅 및 포매팅 패키지를 추가할 수 있습니다:

poetry add --group dev black isort flake8

• --group dev 옵션을 통해 프로덕션 빌드 시 제외되는 개발용 의존성으로 분리
• VS Code 설정에서 Format On Save를 활성화해두면, 저장 시 자동으로 Black과 isort가 적용됩니다.

---

1.4. .env 파일을 통한 환경 변수 관리

배포 환경마다 DB 접속 정보, API 키, Secret Key 등이 달라질 수 있습니다. 이를 코드에 직접 하드코딩하기보다는, 별도 .env 파일에 보관하고 **python-dotenv**를 통해 로드하면 편리합니다:

poetry add python-dotenv

1.4.1. 예시

# .env
DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=mypass

# app/core/config.py
import os
from dotenv import load_dotenv

load_dotenv()  # .env 파일 로드
DB_HOST = os.getenv("DB_HOST", "localhost")
DB_USER = os.getenv("DB_USER", "myuser")
...

• 주의: 실제 운영 환경에서는 .env 파일을 깃에 커밋하지 않거나, 클라우드 시크릿 매니저를 사용할 수 있습니다.

---

1.5. 프로젝트 디렉토리 구조 설계

초기 설정이 끝나면, 빠른 시범 운영이 가능해집니다. 이 시점에 폴더 구조를 대략적으로 잡아두는 것이 좋습니다:

fastapi-poetry-app/
├── app/
│   ├── main.py         # FastAPI 엔트리포인트
│   ├── core/           # 설정 및 유틸리티 (config.py, security.py 등)
│   ├── api/            # 라우터/엔드포인트 모음
│   ├── models/         # DB 모델(SQLAlchemy 등)
│   ├── schemas/        # Pydantic 스키마
│   ├── crud/           # DB CRUD 로직
│   └── tests/          # 테스트 코드
├── pyproject.toml
├── poetry.lock
├── .env                # 환경 변수 파일
└── README.md

• **app/main.py**에 app = FastAPI()를 정의하고, 추후 라우터와 DB 설정 등을 연결
• 필요할 때마다 models/, schemas/, crud/, api/ 디렉토리를 만들어 세분화
• 2장 이후로 프로젝트 구조와 라우팅 전략을 더 자세히 다룰 예정

---

1.6. 마무리

이번 1장에서는 Poetry와 FastAPI를 빠르게 시작하기 위한 환경 설정 전반을 알아보았습니다.

1. 시리즈의 목적: Python 웹 개발의 필수 요소를 학습하여 실무 수준의 백엔드 구축
2. Poetry 설치 및 pyproject.toml 초기화로 Python 의존성 관리를 정돈
3. FastAPI와 Uvicorn을 설치해 간단한 Hello World 서버를 띄워보기
4. VS Code 개발 환경에서 Poetry 가상 환경을 인식, 포매팅/린팅 도구를 추가
5. .env 파일 활용으로 환경 변수를 안전하게 관리
6. 대략적인 프로젝트 구조 안내

이렇게 기본적인 설정을 마쳤다면, 다음 2장부터는 FastAPI 프로젝트 구조와 라우팅 설계, 그리고 DB 연동을 통한 CRUD 구현으로 조금씩 스펙을 확장해 나가겠습니다. 앞으로 함께 진행하며, 효율적인 Python 백엔드 개발의 노하우를 차근차근 익혀 보시길 바랍니다.