Uvicorn은 HTTP 요청을 받아 앱을 실행하는 ASGI 서버, Starlette는 웹 처리 기반, FastAPI는 그 위에 검증·문서화 등 API 기능을 제공하는 프레임워크입니다. 셋은 같은 역할의 대체재가 아닙니다.
클라이언트 → Uvicorn (ASGI 서버)
→ FastAPI (Starlette 기반 웹 처리 + API 기능)
→ 작성한 경로 함수 / 데이터베이스 / 외부 API
역할 구분은 Starlette 공식 소개를 참고하세요. 프레임워크 선택 기준은 Django vs FastAPI 비교에서 설명합니다.
1. FastAPI란?
FastAPI는 Python의 비동기 기능을 활용하여 빠르고 효율적인 API 서버를 구축할 수 있는 프레임워크입니다.
🎯 주요 특징
- 빠른 성능: Starlette과 Pydantic을 활용하여 뛰어난 속도를 자랑합니다.
- 비동기 지원:
async및await을 기본적으로 활용 가능 - 자동 문서화: Swagger UI 및 ReDoc을 통해 API 문서를 자동 생성
- 타입 검사 지원: Python 타입 힌트를 활용하여 자동 검증 수행
✨ FastAPI 예제 코드
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"message": "Hello, FastAPI!"}
위 코드를 main.py로 저장한 뒤 아래의 Uvicorn 실행 명령을 사용하면 http://127.0.0.1:8000에서 확인할 수 있습니다.
2. Starlette이란?
FastAPI는 내부적으로 Starlette이라는 ASGI 프레임워크를 기반으로 동작합니다.
🛠 Starlette의 역할
- 비동기 요청 처리
- 미들웨어 지원
- WebSocket, 응답 후 백그라운드 작업 처리
즉, FastAPI는 Starlette을 활용하여 API 요청을 관리하고 있습니다.
3. Uvicorn이란?
FastAPI 애플리케이션을 실행하려면 ASGI 서버가 필요하며, 대표적으로 Uvicorn을 사용합니다.
🚀 Uvicorn의 특징
- 고성능 ASGI 서버: 비동기 이벤트 루프 기반으로 빠른 요청 처리 가능
- 멀티 프로세스 지원:
--workers옵션으로 여러 프로세스를 활용 가능
🏃♂️ FastAPI 실행하기 (Uvicorn 사용)
python -m pip install fastapi "uvicorn[standard]"
python -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload
main:app은 main.py 파일의 app 객체를 뜻합니다. 위 명령은 로컬 개발용입니다. --reload는 코드 변경 감지를 위한 옵션이며, --workers와 함께 사용할 수 없습니다. Uvicorn 설정 문서
4. async def와 일반 def의 차이
FastAPI가 호출하는 일반 def 경로 함수는 외부 스레드 풀에서 실행됩니다. 반면 async def에서는 기다리는 작업에 적절한 비동기 API와 await를 사용해야 합니다. async def 내부에서 직접 실행한 일반 함수가 자동으로 스레드 풀로 옮겨지는 것은 아닙니다. FastAPI 공식 설명
import asyncio
from fastapi import FastAPI
app = FastAPI()
@app.get("/wait")
async def wait_example():
await asyncio.sleep(1) # I/O 대기를 설명하기 위한 예시
return {"message": "finished"}
이 예제는 DB나 외부 API 호출을 대신하는 데모입니다. 실제 작업에서는 사용하는 라이브러리의 비동기 API를 확인하세요. CPU 연산을 async def로 선언하는 것만으로 빨라지는 것은 아닙니다.
요청마다 직접 새 스레드를 만드는 코드는 작업 수 제한·오류 처리·종료 관리를 어렵게 만듭니다. 오래 걸리는 작업은 응답 이후 처리할지, 별도의 작업 시스템으로 분리할지 운영 요구에 맞춰 설계하세요.
5. FastAPI, Starlette, Uvicorn, Thread 비교 정리
| 항목 | 역할 |
|---|---|
| FastAPI | API 개발을 위한 프레임워크 |
| Starlette | ASGI 애플리케이션 관리, 미들웨어 제공 |
| Uvicorn | FastAPI 실행을 위한 ASGI 서버 |
| Thread | 비동기 작업과 별개로 동기 작업을 병렬 처리 |
✨ 결론
FastAPI는 Starlette과 Uvicorn을 활용하여 빠르고 강력한 API 서버를 구축할 수 있습니다. 또한, 특정 상황에서는 Thread를 활용하여 백그라운드 작업을 효율적으로 실행할 수도 있습니다.
FastAPI를 활용하여 비동기 프로그래밍을 마스터해 보세요! 🚀
실행이 안 될 때 확인할 것
Could not import module "main": 현재 디렉터리에main.py가 있는지, 모듈 경로가 맞는지 확인하세요./docs에서 문서가 안 보일 때: 문서 경로를 변경했는지 확인하고 Swagger UI·ReDoc 설정 가이드를 참고하세요.