3강. FastAPI 프로젝트 생성과 서버 실행

?1. 이번 강의에서 해결할 문제

설치한 패키지가 실제 HTTP 요청을 받을 수 있는지 확인해야 합니다. 가장 작은 FastAPI 앱과 /health 엔드포인트를 실행합니다.

✓2. 학습 목표

✓이 강의를 마치면

• FastAPI 애플리케이션 객체와 path operation을 만듭니다.
• 모듈:객체 형식으로 Uvicorn을 실행합니다.
• 브라우저와 PowerShell에서 JSON 응답을 확인합니다.

◇3. 핵심 개념

FastAPI는 ASGI 애플리케이션을 만들고 Uvicorn은 네트워크에서 요청을 받아 앱에 전달하는 ASGI 서버입니다. app.main:app은 app/main.py 모듈의 app 변수를 뜻합니다. --reload는 개발 중 파일 변경을 감지하므로 운영에서는 사용하지 않습니다.

</>4. 단계별 코드 예시

파일 경로: game-ranking-api/app/__init__.py

app/__init__.py

# app 디렉터리를 Python 패키지로 표시합니다.

파일 경로: game-ranking-api/app/main.py

app/main.py

from fastapi import FastAPI

app = FastAPI(title="Game Ranking API", version="0.1.0")


@app.get("/health", tags=["system"])
def health() -> dict[str, str]:
    return {"status": "ok"}

실행 위치: game-ranking-api/

python -m uvicorn app.main:app --reload
Invoke-RestMethod http://127.0.0.1:8000/health

응답은 {"status":"ok"}이며 서버 종료는 Ctrl+C입니다.

→5. 코드가 동작하는 이유

데코레이터가 GET /health 요청과 health 함수를 연결합니다. 함수가 반환한 dict는 JSON 응답으로 직렬화됩니다. Uvicorn이 ASGI 호출 규약에 따라 FastAPI 객체를 실행합니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: Could not import module 오류가 납니다. 해결: 프로젝트 루트에서 파일 경로와 app.main:app 철자를 확인합니다.
• 실수: 8000 포트가 이미 사용 중입니다. 해결: 기존 서버를 종료하거나 --port 8001을 사용합니다.
• 실수: 운영에서도 --reload를 사용합니다. 해결: 자동 재시작은 개발 환경에만 둡니다.

✎7. 직접 실습

✎직접 실습

/ 경로에 API 이름과 버전을 반환하는 GET 엔드포인트를 추가하세요. 서버 로그에서 /, /health, 존재하지 않는 /missing의 상태 코드를 비교합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. FastAPI와 Uvicorn은 각각 어떤 역할을 하나요?
2. app.main:app의 앞과 뒤 app은 무엇을 뜻하나요?
3. --reload를 운영에서 피하는 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

FastAPI 객체가 요청 규칙을 정의하고 Uvicorn이 이를 네트워크에 노출합니다. 이제 실행 가능한 /health API가 프로젝트의 기준점입니다.