B컷전문 | 개발과 인생의 이야기

FastAPI 입문자를 위한 개발 환경 구축 가이드. Python 가상환경 설정부터 Uvicorn 실행, 첫 FastAPI API 서버까지 단계별 실습을 안내합니다.

---

1. FastAPI 프로젝트 구조는 어떻게 잡을까?

FastAPI는 마이크로프레임워크이기 때문에,
간단한 파일 하나로도 실행이 가능하지만,
처음부터 구조화된 프로젝트 폴더를 설계하는 것이 중요합니다.

기본 구조 예시:

fastapi-tutorial/
├── app/
│   ├── main.py
│   └── __init__.py
├── venv/
├── requirements.txt
└── README.md

• app/ : 실제 FastAPI 코드가 들어가는 디렉토리
• venv/ : 가상환경 (Git 저장소에는 제외)
• requirements.txt : 패키지 리스트
• main.py : FastAPI 서버 진입점

---

2. Python 가상환경 만들기 (venv)

윈도우/macOS/Linux 공통

# 프로젝트 폴더 생성
mkdir fastapi-tutorial
cd fastapi-tutorial

# 가상환경 생성
python -m venv venv

# 가상환경 활성화
# macOS/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

가상환경이 활성화되면 프롬프트 앞에 (venv)가 붙습니다.

---

3. FastAPI 및 Uvicorn 설치

FastAPI는 서버 프레임워크, Uvicorn은 ASGI 서버입니다.

pip install fastapi uvicorn

# requirements.txt로 저장
pip freeze > requirements.txt

설치된 패키지는 다음과 같습니다:

• fastapi: 코어 프레임워크
• pydantic: 데이터 검증 및 직렬화
• starlette: ASGI 툴킷
• uvicorn: 비동기 서버

---

4. 첫 FastAPI 서버 만들기

app/main.py 파일을 생성하고 다음 코드를 작성합니다:

# app/main.py
from fastapi import FastAPI

app = FastAPI()

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

설명:

• FastAPI() 인스턴스를 app 변수로 생성
• @app.get("/") 데코레이터로 루트 엔드포인트 정의
• GET / 요청에 {"message": "Hello, FastAPI!"} 응답

---

5. Uvicorn으로 서버 실행하기

터미널에서 다음 명령어를 실행합니다:

uvicorn app.main:app --reload

• app.main:app: main.py 파일에서 FastAPI 인스턴스(app)를 찾는다
• --reload: 코드 변경 시 자동 재시작 (개발용 옵션)

접속:
http://127.0.0.1:8000 → JSON 응답 확인
http://127.0.0.1:8000/docs → Swagger UI
http://127.0.0.1:8000/redoc → Redoc 문서

---

6. 실행 오류가 나는 경우 점검 사항

문제 확인 사항

ModuleNotFoundError	uvicorn app.main:app 경로가 정확한지 확인
venv 활성화 안 됨	source 혹은 Scripts\activate 명령 다시 입력
포트 충돌	--port 8001 등 다른 포트로 실행해보기

---

마무리 정리

이번 글에서는 FastAPI의 개발 환경을 구축하고,
실제 서버를 띄워 보는 경험까지 단계별로 진행했습니다.
초보자 입장에서도 FastAPI의 진입장벽이 낮다는 점을 직접 체감할 수 있었을 것입니다.

---

다음 글 예고

[FastAPI 시리즈 3화]
FastAPI 기본 라우팅 – GET, POST, PUT, DELETE 작성법
에서는 다양한 HTTP 메서드별 엔드포인트를 작성하며 FastAPI의 라우팅 구조를 본격적으로 학습합니다.