서론
오늘은 FastAPI 로 간단하게 로컬 서버 띄우는 방법에 대해서 알아보도록 하자. 기본적으로 python(Python 3.13.2 기준으로 작성됨)이 설치된 것을 가정하고 진행하겠다.
FastAPI 간단 소개
Python 서버 개발 프레임워크에는 대표적으로 FastAPi, Django, Flask가 있다. 오늘은 이 중에서도 FastAPI에 대해서 알아보겠다. FastAPi란 Python 기반의 초고속 비동기 웹 프레임워크. Starlette와 Pydantic 기반으로 만들어졌으며, 비동기 API와 자동 문서화(Swagger)를 강력하게 지원한다. Python 싱글스레드 한계를 이벤트루프 + 비동기로 극복해서 동시성 높인 게 FastAPI와 같은 최신 프레임워크의 특징이다. 참고로 Python 서버는 기본적으로 싱글 스레드로 동작하지만, I/O 작업만 비동기로 병렬 처리한다.
장점
- 빠른 개발 속도 : 타입 힌트 기반 자동 문서 (Swagger, ReDoc) → 즉시 API 테스트 가능
- 비동기 I/O 지원 : async/await로 고성능 비동기 처리 (동시 요청 처리 탁월)
- Pydantic 기반 검증 : 데이터 검증, 직렬화 자동화 → 보안, 일관성 ↑
- Pythonic : 파이썬 타입 힌트 적극 활용 → 코드 가독성/안정성 ↑
- 높은 성능 : Starlette(비동기 ASGI, ASGI는 비동기 Python 웹 프레임워크를 위한 서버와 애플리케이션 사이의 통신 표준) 기반으로 Flask/Django보다 성능 훨씬 뛰어남 (Node.js 급)
- 자동 문서화 : Swagger, ReDoc 자동 생성 (개발/테스트 효율 폭증)
단점
- 싱글스레드 한계 (GIL) : CPU 집중 작업에 약함 (멀티프로세스 필요)
- 장기 대규모 서비스 경험 부족 : Flask, Django에 비해 대규모 실전 사례 적음 (점점 증가 중)
- 세션/관리성 부족 : 장기 서비스엔 세션, ORM 등 수동 구성 필요 (Django 같은 일체형 아님)
- 패키지 조합 직접 해야 함 : 인증, 관리, 어드민 직접 조합 (장점이자 단점)
가상 환경 만들기
자, 본격적으로 로컬 서버를 띄우기 위한 작업을 설명하겠다.
# 폴더 생성
mkdir sample-fastapi-server
cd sample-fastapi-server
# 가상환경 생성
python3 -m venv venv
# 가상환경 활성화 (Mac/Linux)
source venv/bin/activate
# (Windows)
# venv\Scripts\activate파이썬에서 가상환경은 가상환경은 프로젝트별로 독립적인 파이썬 실행 환경을 만들어서 다른 프로젝트랑 충돌 없이 격리된 상태로 패키지와 버전을 관리하는 시스템이다. 그리고 가상환경을 만들었다고 끝이 아니라, 그 환경 안으로 들어가야 사용 가능하다.
my_project/
├── venv/ # 가상환경 (여기서만 작동)
│ ├── bin/ # 파이썬 실행 파일 (python, pip 등)
│ ├── lib/ # 패키지들이 설치되는 공간
│ └── ...
├── main.py # 내 코드
└── requirements.txt # 패키지 목록가상환경을 활성화(activate) 하면 이 가상환경 전용 파이썬, pip가 기본으로 연결된다. 이후 설치/실행하는 모든 패키지는 전역이 아니라 이 프로젝트 안에만 존재한다.
의존성 설치 : FastAPI & Uvicorn 설치
여기서 uvicorn은 FastAPI 같은 Python 웹 프레임워크를 실제로 "웹 서버"로 띄워주는 ASGI 서버다. FastAPI는 웹 애플리케이션을 만드는 프레임워크이고 이 FastAPI 앱을 브라우저에서 요청받고 응답하는 실제 서버 역할을 해주는 게 바로 uvicorn이다. 마치 Spring Boot에서 톰캣이 하는 역할과 같다.
pip install fastapi uvicornmain.py 파일 생성 및 코드 작성
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "FastAPI 서버가 잘 동작합니다!"}서버 실행
uvicorn main:app --reload --port 8000- --reload: 코드 변경 시 자동 반영
- --port 8000: 8000번 포트에서 실행
확인
브라우저 열고 http://127.0.0.1:8000 접속 시, FastAPI 서버가 잘 동작합니다! 확인 가능
패키지 의존성 관리
FastAPI에선 의존성 관리를 하는 가장 기본적인 방법은 requirements.txt 파일로 하는 것이다.
fastapi==0.110.0
uvicorn==0.29.0
PyMuPDF==1.23.6
python-multipart==0.0.6- 버전 고정: 항상 동일한 환경 보장한다.
- pip install -r requirements.txt 로 한번에 설치 가능하다.
pip freeze > requirements.txtpyproject.toml를 활용하는 방식도 있다. 최근 Python 패키징 표준 (PEP 518, PEP 621)으로 poetry 같은 툴 쓸 때 자동 관리된다.
좀 더 구조적이고 명확하다는 장점이 있다. 마치 Node.js의 package.json 느낌
[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.110.0"
uvicorn = "^0.29.0"
pymupdf = "^1.23.6"단, 기본 pip만 쓸 때는 안 쓰고, poetry 같은 툴 쓸 때만 사용한다.
댓글