Skip to content

3.1장: FastAPI 설치 및 환경 설정

학습 시간: 45분

1. FastAPI란? API를 위한 하이퍼드라이브

Flask가 기동성 있는 정찰용 탐사선이고 Django가 거대한 항공모함이라면, FastAPI는 초광속 전투기입니다.

FastAPI는 Python 3.7+에서 API를 구축하기 위한 현대적이고 고성능 웹 프레임워크입니다. 주요 장점은 다음과 같습니다:

  • 속도: NodeJS 및 Go와 비견될 정도로 가장 빠른 Python 프레임워크 중 하나입니다.
  • 단순성: 미니멀하고 직관적인 구문입니다.
  • 자동 문서화: API에 대한 대화형 문서를 자동으로 생성합니다.
  • 타입 힌트: 유효성 검사, 자동 완성 및 문서화를 위해 표준 Python 타입 힌트를 사용합니다.

💡 우주 비유:

FastAPI는 API 함선을 위한 "하이퍼드라이브"와 같습니다. 이 프레임워크는 두 가지 기술을 기반으로 합니다:

  • Starlette (전투기 기체) — 비동기식 및 최고 성능을 제공합니다.
  • Pydantic (온보드 컴퓨터) — 데이터 유효성 검사 및 설정 관리를 담당합니다.

2. 발사대 준비: 가상 환경

전투기를 제작하기 전에 무균 조립 실험실을 만들어야 합니다. Python에서는 이를 위해 가상 환경을 사용합니다.

왜 필요할까요? 프로젝트의 종속성(엔진, 내비게이션 시스템)이 컴퓨터의 다른 프로젝트와 충돌하지 않도록 하기 위함입니다.

1단계: 가상 환경 생성 프로젝트 폴더(예: C:\Projects\FastAPI_Fleet)에서 터미널을 열고 다음을 실행합니다:

python -m venv venv
이 명령은 격리된 Python 버전이 포함된 venv 폴더를 생성합니다.

2단계: 실험실 "보호막" 활성화

  • Windows (PowerShell):

.\venv\Scripts\Activate.ps1
(오류가 발생하는 경우 스크립트 실행을 허용해야 할 수 있습니다: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process)

  • Windows (CMD):
.\venv\Scripts\activate.bat
  • macOS / Linux:

source venv/bin/activate
활성화 후 터미널 라인 시작 부분에 (venv)가 나타납니다. 이는 여러분이 실험실 안에 있다는 것을 의미합니다!

3. 엔진 설치: FastAPI 및 Uvicorn

이제 두 가지 핵심 구성 요소를 설치하겠습니다:

  • fastapi: 프레임워크 자체입니다.
  • uvicorn: 엔진을 "시동"할 번개처럼 빠른 ASGI 서버입니다.

활성화된 환경에서 다음을 실행합니다: 

pip install "fastapi[all]"

💡 왜 [all]일까요? 이는 fastapi, uvicorn 및 향후 미션에 유용할 다른 유용한 패키지(예: 웹 소켓 및 Jinja2 지원용)를 설치합니다.

설치 확인: 

pip freeze
목록에서 fastapi, pydantic, starlette, uvicorn 및 기타 패키지를 확인할 수 있습니다.

4. 첫 접촉: main.py 파일

프로젝트 루트에 main.py 파일을 생성하세요. 이것이 API의 중앙 제어판이 될 것입니다.

main.py에 다음 코드를 추가하세요: 

from fastapi import FastAPI

# 우리 "우주선" API의 인스턴스를 생성합니다.
app = FastAPI()

# 첫 번째 "도킹 노드"(엔드포인트)를 정의합니다.
# 이는 루트 URL입니다: /
@app.get("/")
def read_root():
    """
    이것은 주 게이트웨이에 연결하는 모든 사람이 볼 수 있는
    우주 관제 센터의 메시지입니다.
    """
    return {"message": "우주 함대 관제 센터에 오신 것을 환영합니다!"}
- @app.get("/"): 이는 FastAPI에게 read_root 함수가 루트 URL(/)에 대한 GET 요청을 처리해야 한다고 알려주는 데코레이터입니다.

5. 점화! 서버 실행

이제 하이퍼드라이브를 실행할 시간입니다! 터미널(활성화된 venv 상태)에서 다음을 실행합니다: 

uvicorn main:app --reload
명령어 해석:

  • uvicorn: Uvicorn 서버를 실행합니다.
  • main: main.py 파일(.py 제외).
  • app: main.py 내부에서 생성된 app = FastAPI() 객체.
  • --reload: "자동 조종". 코드가 변경될 때마다 서버가 자동으로 다시 시작됩니다.

터미널 예상 출력: 

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345]
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

6. 우주 관제 센터와의 통신 확인

이제 API가 온라인 상태이며 8000 포트를 수신 대기하고 있습니다!

1단계: 브라우저에서 확인

브라우저에서 http://127.0.0.1:8000 주소를 엽니다. 다음을 볼 수 있습니다: 

{
  "message": "우주 함대 관제 센터에 오신 것을 환영합니다!"
}

2단계: 미래 엿보기 (자동 문서화)

FastAPI는 이미 두 가지 선물을 만들었습니다. 다음 URL을 엽니다:

  • http://127.0.0.1:8000/docs: 대화형 Swagger UI 문서.
  • http://127.0.0.1:8000/redoc: 대체 ReDoc 문서.

브라우저에서 바로 테스트할 수 있는 첫 번째 엔드포인트를 보게 될 것입니다!

확인을 위한 퀴즈

1. FastAPI는 ...으로 알려져 있습니다.

2. 가상 환경(`venv`)이 왜 필요할까요?

3. 이 강의에서 FastAPI를 실행하는 데 사용되는 서버는 무엇입니까?

4. `uvicorn main:app --reload` 명령어는 다음을 의미합니다:

5. FastAPI에서 `@app.get("/")` 데코레이터는 무엇을 합니까?

🚀 장 요약:

새로운 API의 "하이퍼드라이브"를 성공적으로 조립하고 실행했습니다! 이제 다음이 있습니다: - 🛠️ 격리된 개발 환경 (venv) - 🚀 FastAPI 및 Uvicorn 서버 설치 완료 - 🛰️ 단일 엔드포인트로 작동하는 API - 📊 자동 생성된 문서

모든 시스템 정상! 다음 장에서는 우주선 목록을 반환하는 첫 번째 완전한 엔드포인트를 만들 것입니다.

📌 확인:

  • 터미널에서 (venv) 환경 활성화됨
  • uvicorn 서버 오류 없이 실행 중
  • http://127.0.0.1:8000/docs 주소가 브라우저에서 열림

⚠️ 오류 발생 시:

  • command not found: 가상 환경을 활성화했는지 확인하십시오.
  • Port ... is already in use: 다른 프로그램이 포트 8000을 사용 중입니다. 해당 프로그램을 중지하거나 다른 포트에서 uvicorn을 실행하십시오: uvicorn main:app --reload --port 8001.
  • PowerShell에서 venv 활성화 시 오류: 스크립트 실행 정책을 확인하십시오.