FastAPI 가이드 | AI DevOps Korea

목차 15개 섹션

가이드 사용법
구조 다이어그램
FastAPI란?
프로젝트 설정
라우팅
Pydantic 스키마
의존성 주입
동기 vs 비동기 처리
전역 예외 처리
LLM 토큰 스트리밍
API 테스트
실행 & 배포
FastAPI 설계
운영 기준
검증 전략

가이드 사용법

읽는 방향

FastAPI를 실무 흐름으로 이해하기

FastAPI로 타입 안전한 REST API를 빠르게 만듭니다. 라우팅, Pydantic 모델, 의존성 주입, 동기/비동기 처리, 전역 예외 처리, LLM 토큰 스트리밍, 테스트, 배포까지 실무 흐름으로 정리했습니다. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.

핵심 관점

백엔드 / 시스템 개발

문법보다 요청이 들어와 검증, 처리, 저장, 응답으로 이어지는 경계를 먼저 잡습니다.

REST API 서버AI 모델 서빙 & 토큰 스트리밍마이크로서비스백엔드 프로토타입

구조 다이어그램

글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 FastAPI를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

FastAPI란?

FastAPI를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.

FastAPI는 Python 타입 힌트를 기반으로 API 서버를 빠르게 만드는 프레임워크입니다. 자동 문서화, 입력 검증, 비동기 처리, 높은 실행 성능을 함께 제공해 AI/데이터 서비스의 API 계층으로 많이 사용됩니다.

다이어그램 렌더링 중…

특징	설명
타입 기반 개발	Python 타입 힌트와 Pydantic 모델로 요청/응답을 검증합니다.
자동 문서화	OpenAPI, Swagger UI, ReDoc 문서가 자동 생성됩니다.
비동기 지원	async/await 기반 I/O 작업을 자연스럽게 처리합니다.
테스트 친화성	TestClient로 API 동작을 빠르게 검증할 수 있습니다.

프로젝트 설정

여기서는 프로젝트 설정을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

uv 또는 venv로 프로젝트 환경을 분리한 뒤 FastAPI와 ASGI 서버인 Uvicorn을 설치합니다.

BASH

uv venv
source .venv/bin/activate
uv pip install fastapi uvicorn[standard] pydantic

mkdir -p app
touch app/main.py

라우팅

여기서는 라우팅을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

FastAPI 앱은 HTTP 메서드 데코레이터로 엔드포인트를 정의합니다.

app/main.pyPYTHON

from fastapi import FastAPI

app = FastAPI(title="AI DevOps API")

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

@app.get("/users/{user_id}")
def get_user(user_id: int, active: bool = True) -> dict:
    return {"id": user_id, "active": active}

Pydantic 스키마

여기서는 Pydantic 스키마을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

요청과 응답 모델을 명시하면 검증, 직렬화, 문서화가 한 번에 정리됩니다.

PYTHON

from pydantic import BaseModel, Field

class CreateItem(BaseModel):
    name: str = Field(min_length=2, max_length=80)
    price: float = Field(gt=0)

class Item(CreateItem):
    id: int

@app.post("/items", response_model=Item)
def create_item(payload: CreateItem) -> Item:
    return Item(id=1, **payload.model_dump())

의존성 주입

여기서는 의존성 주입을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Depends를 사용하면 인증, DB 세션, 설정 객체 같은 공통 의존성을 라우터 밖으로 분리할 수 있습니다. require_token 같은 의존성 함수는 여러 엔드포인트에서 그대로 재사용할 수 있고, 테스트에서는 app.dependency_overrides로 손쉽게 가짜 구현으로 바꿔치기할 수 있어 인증 로직을 매 핸들러마다 중복 작성하지 않아도 됩니다.

PYTHON

from fastapi import Depends, Header, HTTPException

async def require_token(authorization: str | None = Header(default=None)) -> str:
    if authorization != "Bearer test-token":
        raise HTTPException(status_code=401, detail="Unauthorized")
    return authorization

@app.get("/me")
def me(token: str = Depends(require_token)) -> dict[str, str]:
    return {"token": token}

동기 vs 비동기 처리

여기서는 동기 vs 비동기 처리을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

경로 함수를 `def`로 선언하면 FastAPI가 자동으로 별도 스레드 풀에서 실행해 이벤트 루프를 막지 않게 해줍니다. `async def`로 선언하면 메인 이벤트 루프에서 직접 실행되므로, 그 안에서 동기 라이브러리(requests, 동기 DB 드라이버 등)를 호출하면 그동안 서버 전체가 다른 요청을 처리하지 못하고 멈춥니다.

async_pitfall.pyPYTHON

import httpx
import requests   # 동기 라이브러리

# 잘못된 예 — async def 안에서 동기 호출 → 이벤트 루프 전체 블로킹
@app.get("/bad")
async def bad_endpoint():
    response = requests.get("https://api.example.com/data")  # 여기서 서버 전체가 멈춤
    return response.json()

# 올바른 예 — async 클라이언트로 논블로킹 호출
@app.get("/good")
async def good_endpoint():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()

선언	실행 위치	주의할 점
def 핸들러	별도 스레드 풀	CPU 바운드 작업이 많으면 스레드 풀 자체가 병목이 될 수 있음
async def + await	메인 이벤트 루프	내부에서 반드시 async 라이브러리만 호출해야 함 (httpx, asyncpg 등)
async def + 동기 호출	메인 이벤트 루프	이벤트 루프 전체가 멈춤 — 가장 흔한 성능 사고

전역 예외 처리

여기서는 전역 예외 처리을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

엔드포인트마다 try-except를 반복하는 대신, `@app.exception_handler`로 특정 예외 타입을 전역에서 잡아 일관된 에러 응답으로 변환합니다. 이렇게 하면 비즈니스 로직 코드에서는 그냥 예외를 raise하기만 하면 되고, HTTP 응답 형식은 한 곳에서만 관리합니다.

errors.pyPYTHON

from fastapi import Request
from fastapi.responses import JSONResponse

class ItemNotFoundError(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

@app.exception_handler(ItemNotFoundError)
async def item_not_found_handler(request: Request, exc: ItemNotFoundError):
    return JSONResponse(
        status_code=404,
        content={"error": "ITEM_NOT_FOUND", "item_id": exc.item_id},
    )

@app.get("/items/{item_id}")
def get_item(item_id: int) -> dict:
    if item_id not in db:
        raise ItemNotFoundError(item_id)   # 핸들러에서 형식만 결정, 여기선 그냥 raise
    return db[item_id]

LLM 토큰 스트리밍

여기서는 LLM 토큰 스트리밍을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

ChatGPT처럼 답변이 한 글자씩 나타나는 UX는 전체 응답이 완성될 때까지 기다리지 않고, 토큰이 생성되는 즉시 클라이언트로 흘려보내는 `StreamingResponse`로 구현합니다. 제너레이터 함수(`yield`)를 응답으로 넘기면, FastAPI가 그 값이 만들어지는 대로 순서대로 클라이언트에 전송합니다.

streaming.pyPYTHON

from fastapi.responses import StreamingResponse
import asyncio

async def generate_tokens(prompt: str):
    tokens = ["안녕", "하세요", "!", " 무엇을", " 도와드릴까요", "?"]
    for token in tokens:
        yield token
        await asyncio.sleep(0.1)   # 실제로는 LLM API의 스트리밍 청크 도착 시점

@app.post("/chat")
async def chat(prompt: str):
    return StreamingResponse(generate_tokens(prompt), media_type="text/event-stream")

API 테스트

여기서는 API 테스트을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

FastAPI는 Starlette 기반 TestClient를 통해 네트워크 없이 엔드포인트를 검증할 수 있습니다.

tests/test_main.pyPYTHON

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_health():
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "ok"}

실행 & 배포

여기서는 실행 & 배포을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

개발 중에는 reload 모드로 실행하고, 운영에서는 Gunicorn/Uvicorn 워커나 컨테이너 환경으로 배포합니다.

BASH

# 개발 실행
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

# 문서 확인
# http://127.0.0.1:8000/docs
# http://127.0.0.1:8000/redoc

FastAPI 실무 설계

FastAPI 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

FastAPI는 라우터가 얇아야 유지보수됩니다. request/response schema, dependency, service, repository를 분리하고, 라우터는 HTTP 상태 코드와 입출력 변환만 담당하게 두는 것이 좋습니다.

결정 지점	확인 질문	실무 기준
경계	FastAPI 코드에서 바뀌기 쉬운 부분은 어디인가?	입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다.
상태	상태가 어디서 생성되고 어디서 사라지는가?	상태 소유자와 수명 주기를 코드로 드러냅니다.
장애	실패했을 때 호출자는 무엇을 받는가?	timeout, fallback, error contract를 먼저 정합니다.

FastAPI 운영 기준

이 섹션은 FastAPI 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

운영 API에서는 worker 수보다 DB pool, 외부 API timeout, validation 비용, response serialization 비용이 먼저 병목이 됩니다. read/write endpoint를 구분하고 pagination, cache, idempotency key를 설계해야 합니다.

FastAPI 검증 전략

FastAPI 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

TestClient 수준을 넘어 dependency override, transaction rollback, OpenAPI contract 검증, 422/401/409 같은 실패 응답 테스트를 포함해야 합니다.

품질 축	검증 방법	완료 기준
정확성	정상/실패 케이스를 자동화합니다.	핵심 시나리오가 재현 가능하게 통과합니다.
회귀 방지	버그 수정 시 동일 케이스를 테스트로 남깁니다.	같은 장애가 다시 배포되지 않습니다.
운영성	로그, 메트릭, 알림을 확인합니다.	문제가 생겼을 때 원인 추적 경로가 있습니다.

목차 15개 섹션

가이드 사용법
구조 다이어그램
FastAPI란?
프로젝트 설정
라우팅
Pydantic 스키마
의존성 주입
동기 vs 비동기 처리
전역 예외 처리
LLM 토큰 스트리밍
API 테스트
실행 & 배포
FastAPI 설계
운영 기준
검증 전략

가이드 사용법

읽는 방향

FastAPI를 실무 흐름으로 이해하기

핵심 관점

백엔드 / 시스템 개발

문법보다 요청이 들어와 검증, 처리, 저장, 응답으로 이어지는 경계를 먼저 잡습니다.

REST API 서버AI 모델 서빙 & 토큰 스트리밍마이크로서비스백엔드 프로토타입

구조 다이어그램

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

FastAPI란?

다이어그램 렌더링 중…

특징	설명
타입 기반 개발	Python 타입 힌트와 Pydantic 모델로 요청/응답을 검증합니다.
자동 문서화	OpenAPI, Swagger UI, ReDoc 문서가 자동 생성됩니다.
비동기 지원	async/await 기반 I/O 작업을 자연스럽게 처리합니다.
테스트 친화성	TestClient로 API 동작을 빠르게 검증할 수 있습니다.

프로젝트 설정

uv 또는 venv로 프로젝트 환경을 분리한 뒤 FastAPI와 ASGI 서버인 Uvicorn을 설치합니다.

BASH

uv venv
source .venv/bin/activate
uv pip install fastapi uvicorn[standard] pydantic

mkdir -p app
touch app/main.py

라우팅

FastAPI 앱은 HTTP 메서드 데코레이터로 엔드포인트를 정의합니다.

app/main.pyPYTHON

from fastapi import FastAPI

app = FastAPI(title="AI DevOps API")

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

@app.get("/users/{user_id}")
def get_user(user_id: int, active: bool = True) -> dict:
    return {"id": user_id, "active": active}

Pydantic 스키마

요청과 응답 모델을 명시하면 검증, 직렬화, 문서화가 한 번에 정리됩니다.

PYTHON

from pydantic import BaseModel, Field

class CreateItem(BaseModel):
    name: str = Field(min_length=2, max_length=80)
    price: float = Field(gt=0)

class Item(CreateItem):
    id: int

@app.post("/items", response_model=Item)
def create_item(payload: CreateItem) -> Item:
    return Item(id=1, **payload.model_dump())

의존성 주입

PYTHON

from fastapi import Depends, Header, HTTPException

async def require_token(authorization: str | None = Header(default=None)) -> str:
    if authorization != "Bearer test-token":
        raise HTTPException(status_code=401, detail="Unauthorized")
    return authorization

@app.get("/me")
def me(token: str = Depends(require_token)) -> dict[str, str]:
    return {"token": token}

동기 vs 비동기 처리

async_pitfall.pyPYTHON

import httpx
import requests   # 동기 라이브러리

# 잘못된 예 — async def 안에서 동기 호출 → 이벤트 루프 전체 블로킹
@app.get("/bad")
async def bad_endpoint():
    response = requests.get("https://api.example.com/data")  # 여기서 서버 전체가 멈춤
    return response.json()

# 올바른 예 — async 클라이언트로 논블로킹 호출
@app.get("/good")
async def good_endpoint():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()

선언	실행 위치	주의할 점
def 핸들러	별도 스레드 풀	CPU 바운드 작업이 많으면 스레드 풀 자체가 병목이 될 수 있음
async def + await	메인 이벤트 루프	내부에서 반드시 async 라이브러리만 호출해야 함 (httpx, asyncpg 등)
async def + 동기 호출	메인 이벤트 루프	이벤트 루프 전체가 멈춤 — 가장 흔한 성능 사고

전역 예외 처리

errors.pyPYTHON

from fastapi import Request
from fastapi.responses import JSONResponse

class ItemNotFoundError(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

@app.exception_handler(ItemNotFoundError)
async def item_not_found_handler(request: Request, exc: ItemNotFoundError):
    return JSONResponse(
        status_code=404,
        content={"error": "ITEM_NOT_FOUND", "item_id": exc.item_id},
    )

@app.get("/items/{item_id}")
def get_item(item_id: int) -> dict:
    if item_id not in db:
        raise ItemNotFoundError(item_id)   # 핸들러에서 형식만 결정, 여기선 그냥 raise
    return db[item_id]

LLM 토큰 스트리밍

streaming.pyPYTHON

from fastapi.responses import StreamingResponse
import asyncio

async def generate_tokens(prompt: str):
    tokens = ["안녕", "하세요", "!", " 무엇을", " 도와드릴까요", "?"]
    for token in tokens:
        yield token
        await asyncio.sleep(0.1)   # 실제로는 LLM API의 스트리밍 청크 도착 시점

@app.post("/chat")
async def chat(prompt: str):
    return StreamingResponse(generate_tokens(prompt), media_type="text/event-stream")

API 테스트

FastAPI는 Starlette 기반 TestClient를 통해 네트워크 없이 엔드포인트를 검증할 수 있습니다.

tests/test_main.pyPYTHON

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_health():
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "ok"}

실행 & 배포

개발 중에는 reload 모드로 실행하고, 운영에서는 Gunicorn/Uvicorn 워커나 컨테이너 환경으로 배포합니다.

BASH

# 개발 실행
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

# 문서 확인
# http://127.0.0.1:8000/docs
# http://127.0.0.1:8000/redoc

FastAPI 실무 설계

FastAPI 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

결정 지점	확인 질문	실무 기준
경계	FastAPI 코드에서 바뀌기 쉬운 부분은 어디인가?	입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다.
상태	상태가 어디서 생성되고 어디서 사라지는가?	상태 소유자와 수명 주기를 코드로 드러냅니다.
장애	실패했을 때 호출자는 무엇을 받는가?	timeout, fallback, error contract를 먼저 정합니다.

FastAPI 운영 기준

이 섹션은 FastAPI 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

FastAPI 검증 전략

FastAPI 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

TestClient 수준을 넘어 dependency override, transaction rollback, OpenAPI contract 검증, 422/401/409 같은 실패 응답 테스트를 포함해야 합니다.

품질 축	검증 방법	완료 기준
정확성	정상/실패 케이스를 자동화합니다.	핵심 시나리오가 재현 가능하게 통과합니다.
회귀 방지	버그 수정 시 동일 케이스를 테스트로 남깁니다.	같은 장애가 다시 배포되지 않습니다.
운영성	로그, 메트릭, 알림을 확인합니다.	문제가 생겼을 때 원인 추적 경로가 있습니다.

⚡ FastAPI 완전 가이드

가이드 사용법

FastAPI를 실무 흐름으로 이해하기

백엔드 / 시스템 개발

구조 다이어그램

학습 흐름

아키텍처 관점

FastAPI란?

프로젝트 설정

라우팅

Pydantic 스키마

의존성 주입

동기 vs 비동기 처리

전역 예외 처리

LLM 토큰 스트리밍

API 테스트

실행 & 배포

FastAPI 실무 설계

FastAPI 운영 기준

FastAPI 검증 전략

⚡ FastAPI 완전 가이드

가이드 사용법

FastAPI를 실무 흐름으로 이해하기

백엔드 / 시스템 개발

구조 다이어그램

학습 흐름

아키텍처 관점

FastAPI란?

프로젝트 설정

라우팅

Pydantic 스키마

의존성 주입

동기 vs 비동기 처리

전역 예외 처리

LLM 토큰 스트리밍

API 테스트

실행 & 배포

FastAPI 실무 설계

FastAPI 운영 기준

FastAPI 검증 전략