👉 이 “주문 ↔ 전달 ↔ 처리 ↔ 전달” 구조가 바로 API의 핵심 흐름이다

🧪 시작하기 전에: 설치가 먼저!

FastAPI를 실행하려면 일단 설치가 필요하다.

그리고 설치 전에 거의 항상 같이 나오는 단어가 있다.

👉 가상환경(virtual environment).

⚠️ 가상환경이란?

가상환경은 프로젝트마다 독립된 Python 패키지 공간을 만든다.

• 프로젝트 A는 FastAPI 0.xx가 필요하고
• 프로젝트 B는 FastAPI 1.xx가 필요할 수도 있다

가상환경이 없으면 전역 설치된 패키지들이 서로 충돌해서 어느 날 갑자기 “어제 되던 게 오늘 안됨” 현상이 터진다.

👉 그래서 FastAPI 시작 전, 가상환경은 사실상 필수다

📦 FastAPI 설치 명령어

FastAPI는 여러 방식으로 설치할 수 있다. 하지만 입문자라면 아래가 가장 무난하다.

pip install "fastapi[standard]"

여기서 [standard]는 “FastAPI만 설치”가 아니라, 개발에 자주 필요한 구성 요소를 함께 설치하는 옵션이다.

🖥️ 튜토리얼 코드는 어떻게 실행할까?

FastAPI 튜토리얼의 코드 블록은 대부분 복사해서 파일로 저장하면 그대로 실행 가능하게 작성되어 있다.

먼저 “FastAPI가 어떤 방식으로 실행되는지 흐름”을 먼저 잡자.

✅ 1단계: main.py 파일 만들기

예제 코드를 실행하려면 먼저 파일이 필요하다.

• 프로젝트 폴더를 하나 만들고
• 그 안에 main.py 파일을 생성한다

👉 지금 단계에서는 “코드를 완벽히 이해”하는 것보다
FastAPI 실행 흐름을 눈으로 확인하는 게 더 중요하다

✅ 2단계: 개발 서버 실행 (fastapi dev)

FastAPI는 개발 서버를 띄울 때 아래 명령어를 많이 쓴다.

fastapi dev main.py

여기서 dev는 development(개발)의 약자다. 즉 “개발 모드로 실행하겠다”라는 뜻이다.

🔍 fastapi dev main.py를 실행하면 무슨 일이 벌어질까?

겉보기엔 “서버가 켜졌다”지만, 실제 내부에선 여러 단계가 있다.

• Python 인터프리터가 실행된다
• main.py 파일을 읽는다(로드)
• FastAPI 앱 객체(app)를 만든다
• Uvicorn(ASGI 서버)이 실행된다
• 서버가 특정 주소에서 요청을 기다린다

👉 핵심:
FastAPI는 프레임워크이고
실제로 요청을 받는 역할은 ASGI 서버(Uvicorn)가 한다

🌐 서버 주소는 어디에 뜰까?

대부분 개발 환경에서는 이런 주소가 나온다.

• 서버 주소 : http://127.0.0.1:8000
• 문서 주소(Swagger UI) : http://127.0.0.1:8000/docs

FastAPI의 장점 중 하나는 API 문서를 자동 생성해준다는 점이다.

👉 서버만 켜면, 문서가 자동으로 생긴다.

📌 콘솔 출력(로그)을 읽는 법

개발 서버를 띄우면 콘솔에 여러 문장이 뜬다. 보통 이런 것들을 보게 된다:

• Server started at : 서버가 열려있는 주소
• Documentation at : API 문서를 볼 수 있는 주소 (자동 생성)
• Will watch for changes : 코드 바뀌면 자동 서버 재시작
• Press CTRL+C to quit : 종료는 Ctrl+C

🧠 개발 환경에서의 코드 작성

🧷 타입 힌트(Type Hint)가 왜 자꾸 나오나요?

Python은 원래 타입을 안 써도 되는 언어지만, FastAPI는 타입 힌트를 적극적으로 사용한다.

왜냐면 타입 힌트를 기반으로

• 요청 데이터 검증
• 자동 문서 생성
• 자동완성 품질 향상

이런 것들이 “자동으로” 되기 때문이다.

예시: 타입 힌트 없음 vs 있음

# 타입 힌트 없음
def greet(name):
    return "안녕하세요, " + name

# 타입 힌트 사용
def greet(name: str) -> str:
    return "안녕하세요, " + name

👉 타입 힌트는 “귀찮은 문법”이 아니라
FastAPI의 자동화 기능을 끌어내는 핵심 재료다

🔹 FastAPI 코드

# main.py

# 1. FastAPI 클래스를 부르기
from fastapi import FastAPI

# 2. FastAPI 인스턴스를 생성
#    이 app 객체가 API 서버의 핵심입니다
app = FastAPI()

# 3. 경로(path)와 작업(operation)을 정의
#    @app.get("/")는 "루트 경로에 GET 요청이 오면"이라는 의미
@app.get("/")
async def root():
    # 4. 클라이언트에게 보낼 응답을 반환합니다
    #    딕셔너리는 자동으로 JSON 형식으로 변환됩니다
    return {"message": "Hello World"}

🔹 서버 실행하기

터미널에서 아래 명령어를 입력하여 개발 서버를 실행한다.

# fastapi dev: 개발 모드로 서버 실행
# main.py: 실행할 파일 이름
# 개발 모드에서는 코드 변경 시 서버가 자동으로 재시작됨.
fastapi dev main.py

서버가 정상적으로 실행 될 경우:

여기서 127.0.0.1은 localhost를 의미하며 8000은 포트번호이다

결과 확인

{"message": "Hello World"}

✅ 핵심 요약

• FastAPI는 개발 속도도 빠르고 성능도 빠른 Python 웹 프레임워크다
• fastapi dev main.py를 실행하면 Uvicorn 서버가 뜨고 요청을 받는다
• /docs에서 자동 문서(Swagger UI)를 바로 확인할 수 있다
• FastAPI의 장점은 타입 힌트 기반 자동화에서 나온다