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는 개발 중 파일 변경을 감지하므로 운영에서는 사용하지 않습니다.

용어 정리

용어	무엇인가	이 강의의 예
FastAPI	경로·검증·응답 규칙을 정의하는 Python 웹 프레임워크	app = FastAPI(...)
Uvicorn	TCP 연결을 받고 ASGI 앱을 실행하는 서버	python -m uvicorn ...
ASGI	Python 서버와 비동기 웹 앱 사이의 호출 규약	Uvicorn이 FastAPI를 호출
엔드포인트	특정 method와 path로 접근하는 API 기능	GET /health
path operation	경로·메서드와 연결된 처리 함수	health()
JSON 직렬화	Python 값을 전송 가능한 JSON으로 변환	dict → {"status":"ok"}

FastAPI만 설치했다고 네트워크 포트가 열리는 것은 아닙니다. FastAPI 객체가 "어떤 요청을 어떻게 처리할지"를 정의하고, Uvicorn이 그 객체를 불러와 127.0.0.1:8000에서 실제 요청을 기다립니다.

가장 작은 응답 함수

def health() -> dict[str, str]:
    return {"status": "ok"}

이 함수만으로는 HTTP에서 호출할 수 없습니다. @app.get("/health") 데코레이터가 GET 요청과 함수를 연결해야 엔드포인트가 됩니다.

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

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

시작 전에는 2강에서 만든 가상 환경에 FastAPI와 Uvicorn이 설치되어 있어야 합니다. 터미널 위치는 app 폴더 안이 아니라 그 상위 프로젝트 루트 game-ranking-api입니다.

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"}

코드 한 줄씩 이해하기

1. from fastapi import FastAPI는 앱 객체를 만들 클래스를 가져옵니다.
2. FastAPI(title=..., version=...)는 API 메타 정보를 가진 ASGI 앱을 만듭니다. /docs의 문서에도 사용됩니다.
3. @app.get("/health", tags=["system"])는 바로 아래 함수를 GET /health에 등록합니다.
4. 반환 타입 dict[str, str]은 문자열 키와 문자열 값을 가진 dict라는 개발자용 타입 정보입니다.
5. return {"status": "ok"}를 FastAPI가 JSON 본문으로 변환하고 기본 성공 상태 200을 보냅니다.

실행 위치: game-ranking-api/

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

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

요청부터 응답까지 확인하기

브라우저/PowerShell
  → GET http://127.0.0.1:8000/health
  → Uvicorn이 요청 수신
  → FastAPI가 GET + /health 규칙 검색
  → health() 실행
  → dict를 JSON으로 변환
  → 200 OK + {"status":"ok"}

서버 터미널에는 GET /health ... 200 OK 로그가 남습니다. /missing을 요청하면 일치하는 path operation이 없어 404 Not Found와 {"detail":"Not Found"}가 반환됩니다. 두 결과를 비교하면 서버가 실행되지 않는 문제와 경로가 없는 문제를 구분할 수 있습니다.

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

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

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

!자주 하는 실수

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

✎7. 직접 실습

✎직접 실습

실습 목표

서버를 실행하고 /, /health, /missing 요청의 JSON과 상태 코드를 비교합니다.

시작 전 상태

가상 환경을 활성화하고 프로젝트 루트에서 app/main.py와 app/__init__.py 경로를 확인합니다. 예제 /health를 먼저 실행해 200 응답을 확인합니다.

1단계: 따라 하기

Uvicorn을 실행하고 브라우저와 Invoke-RestMethod로 /health를 호출합니다. JSON 본문과 서버 터미널의 method·path·상태 코드를 기록합니다.

2단계: 값을 바꾸고 결과 비교

반환값의 "ok"를 "ready"로 바꿉니다. --reload가 변경을 감지한 뒤 새로 고침하면 JSON만 달라지고 상태 코드는 200인 것을 확인합니다.

3단계: 직접 적용

GET /에 {"name": "Game Ranking API", "version": "0.1.0"}을 반환하는 함수를 추가합니다. /, /health, 존재하지 않는 /missing의 상태 코드를 비교합니다.

4단계: 스스로 확인

• app.main:app의 모듈 경로와 객체 이름을 설명할 수 있나요?
• 서버 로그와 응답 본문을 모두 확인했나요?
• 파일을 바꾸지 않은 상태에서 /missing이 404인 이유를 설명할 수 있나요?

막혔을 때

• Could not import module: 프로젝트 루트에서 실행했는지, app/main.py와 app 변수 철자를 확인합니다.
• 연결 자체가 거부됨: Uvicorn 터미널이 실행 중인지와 사용 포트를 확인합니다.
• 404 응답: 서버 장애가 아니라 method와 path가 등록됐는지 확인합니다.
• 변경이 반영되지 않음: 저장 여부와 reload 로그를 확인하고, 운영 환경처럼 reload가 없다면 서버를 재시작합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. FastAPI와 Uvicorn은 각각 어떤 역할을 하나요?
2. app/main.py 안의 FastAPI 변수 이름을 api로 바꾸었다면 Uvicorn의 app.main:app을 어떻게 수정해야 하나요?
3. --reload를 운영에서 피하는 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

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

§다음 강의 연결

실행 가능한 서버가 준비됐습니다. 4강. HTTP 요청·응답과 REST API 설계에서 path operation을 기록 리소스의 method·path·상태 코드 계약으로 확장합니다.