ingu627 🔅

Circuit rhythms, neural visions: the art of artificial intelligence 64.6 x 65

개인 저장공간입니다.
Since 2021.10

7 분 소요

현대의 API는 단순한 엔드포인트의 집합이 아니다. 높은 성능과 안정성, 뛰어난 개발자 경험(DX), 그리고 견고한 보안까지 모두 갖춘 복합적인 시스템을 요구한다. Python 진영에서 FastAPI는 이러한 현대적 요구사항을 가장 잘 만족시키는 웹 프레임워크로 평가받는다.
이 글은 FastAPI를 사용하여 프로덕션 수준의 API를 설계하고 운영하기 위한 핵심 원리와 실용적인 전략을 단계적으로 안내한다. FastAPI의 내부 동작 방식을 이해하고, 이를 바탕으로 실제 운영 환경에서 마주할 수 있는 다양한 문제들을 해결하는 데 초점을 맞춘다.


1. FastAPI의 핵심 원리: 제어 흐름과 구성 요소

FastAPI의 높은 생산성과 성능은 몇 가지 핵심적인 설계 원리에서 비롯된다. 코드를 작성하기 전에 요청이 어떻게 처리되고, 각 구성 요소가 어떤 역할을 하는지 이해하는 것이 중요하다.

1.1. 제어 및 데이터 흐름 시각화

FastAPI에서 요청이 처리되는 과정을 시각적으로 표현하면 다음과 같다. 각 단계에서 데이터가 어떻게 변환되고 전달되는지 이해하는 것이 중요하다.

[ 클라이언트 ]
     |
HTTP 요청 (Request Body: JSON)
     |
     V
[ ASGI 서버 (Uvicorn) ]
     |
     V
+-------------------------------------------------+
| FastAPI 애플리케이션                            |
|                                                 |
|  1. 경로 탐색                                   |
|     - 요청 URL/메서드에 맞는 경로 작동 함수 탐색  |
|     |                                           |
|     V                                           |
|  2. 데이터 유효성 검사 (with Pydantic)          |
|     - 요청 데이터를 Pydantic 모델로 변환 및 검증  |
|     - (실패 시 422 오류 즉시 반환)              |
|     |                                           |
|     V                                           |
|  3. 의존성 주입 (with Depends)                  |
|     - 의존성 함수를 실행하고 결과를 확보          |
|     |                                           |
|     V                                           |
|  4. 비즈니스 로직 실행 (경로 작동 함수)         |
|     - 검증된 데이터와 의존성 결과를 인자로 받아   |
|       함수 내부 로직 실행                       |
|     |                                           |
|     V                                           |
|  5. 응답 데이터 직렬화 (with Pydantic)          |
|     - 함수의 반환 값을 JSON으로 변환            |
|     - (response_model에 따라 필드 필터링)       |
|                                                 |
+-------------------------------------------------+
     |
     V
[ ASGI 서버 (Uvicorn) ]
     |
HTTP 응답 (Response Body: JSON)
     |
     V
[ 클라이언트 ]

1.2. 단계별 데이터 흐름 상세

위 다이어그램의 각 단계에서 데이터는 다음과 같이 구체적으로 변환되고 처리된다.

  1. HTTP 요청 (Raw Data): 클라이언트는 서버로 {"name": "my-item", "price": 15.5}와 같은 순수 텍스트 형태의 JSON 문자열을 HTTP 요청 본문에 담아 전송한다.

  2. 파싱 및 유효성 검사 (Text -> Python Dict -> Pydantic Model):
    • FastAPI는 요청 본문의 원시 바이트(raw bytes)를 읽어 UTF-8과 같은 형식으로 디코딩하여 Python의 str으로 변환한다.
    • 이 문자열을 JSON 파서로 분석하여 Python의 dict 객체로 변환한다. ( {'name': 'my-item', 'price': 15.5} )
    • 경로 작동 함수에 item: Item과 같이 Pydantic 모델 타입이 선언되어 있으면, FastAPI는 이 dict를 Item 모델의 생성자에 키워드 인자로 전달하여 Item의 인스턴스를 생성한다. ( my_item = Item(**{'name': 'my-item', 'price': 15.5}) )
    • 이 과정에서 Pydantic은 price 필드가 float 타입인지, name의 길이는 적절한지 등 모델에 정의된 모든 규칙에 따라 타입 변환과 유효성 검사를 자동으로 수행한다. 규칙에 어긋나면, Pydantic은 어떤 필드가 왜 잘못되었는지에 대한 상세한 오류를 발생시키고 FastAPI는 이를 422 상태 코드와 함께 클라이언트에게 반환한다.
  3. 경로 작동 함수 실행 (Pydantic Model as Argument):
    • 성공적으로 생성된 Item 모델의 인스턴스(my_item)와 Depends를 통해 실행된 의존성의 결과(예: db_session)가 경로 작동 함수의 인자로 전달된다.
    • 개발자는 함수 내에서 타입 힌트의 지원을 받으며 my_item.price와 같이 속성에 안전하게 접근하여 비즈니스 로직을 처리한다.
  4. 응답 데이터 직렬화 (Python Object -> JSON Text):
    • 경로 작동 함수가 처리 결과를 반환한다. (예: 데이터베이스에 저장된 후의 Item 객체)
    • FastAPI는 이 반환 값을 @app.post 데코레이터의 response_model로 지정된 Pydantic 모델에 맞추어 직렬화한다.
    • 이때 response_model에 포함되지 않은 필드(예: 보안상 노출되면 안 되는 password 필드)는 자동으로 제외된다.
    • 최종적으로 Pydantic 모델 객체는 dict를 거쳐 다시 JSON 문자열로 변환되어 HTTP 응답 본문에 포함된다.

이처럼 FastAPI는 Pydantic을 통해 지루하고 반복적인 데이터 검증 및 직렬화 작업을 자동화하여, 개발자가 핵심 비즈니스 로직에만 집중할 수 있도록 돕는다.

1.2. 경로 작동 함수 (Path Operation Function)

API의 각 엔드포인트를 정의하는 평범한 Python 함수다. @app.get, @app.post 같은 데코레이터를 사용하여 특정 URL 경로 및 HTTP 메서드와 연결한다.

  • 비동기 vs 동기 (async def vs def): FastAPI의 성능을 극대화하려면 작업의 성격을 이해하고 함수를 올바르게 정의해야 한다.
    • async def (I/O 바운드 작업용): 데이터베이스 조회, 외부 API 호출처럼 네트워크 대기가 발생하는 작업에 사용한다. await 키워드로 대기하는 동안 이벤트 루프는 다른 요청을 처리할 수 있어 높은 동시성을 보장한다.
    • def (CPU 바운드 작업용): 복잡한 수학 계산, 머신러닝 모델 추론처럼 CPU를 계속 사용하는 작업에 사용한다. FastAPI는 동기 함수를 별도의 스레드 풀에서 실행하여, 이벤트 루프가 막히는 현상(Blocking)을 방지한다.

1.3. 데이터 계약 (Pydantic Models)

Pydantic은 Python 타입 힌트를 사용하여 데이터 유효성 검사와 설정을 관리하는 라이브러리로, FastAPI의 핵심적인 부분이다. Pydantic 모델은 API의 ‘데이터 계약(Data Contract)’ 역할을 수행하며, 다음과 같은 이점을 자동으로 제공한다.

  • 명확한 데이터 구조: API가 어떤 형식의 데이터를 받고 어떤 형식으로 응답하는지 명확하게 정의한다.
  • 자동 유효성 검사: 클라이언트가 보낸 데이터가 정의된 타입과 제약 조건에 맞는지 자동으로 검사하고, 오류가 있을 경우 상세한 정보를 담은 응답을 생성한다.
  • 자동 문서화: Pydantic 모델 정의는 그대로 OpenAPI 문서에 반영되어, 개발자가 API의 데이터 구조를 쉽게 파악할 수 있게 한다.
  • 지능적인 에디터 지원: 타입 힌트 덕분에 코드 자동 완성, 타입 체크 등 개발 도구의 지원을 최대한 활용할 수 있다.

1.4. 의존성 주입 (Dependency Injection)

인증, 데이터베이스 세션 관리처럼 여러 엔드포인트에서 반복적으로 사용되는 로직을 분리하고 재사용하기 위한 강력한 기능이다.

  • 관심사 분리: 경로 작동 함수는 비즈니스 로직에만 집중하고, 인증이나 DB 연결 같은 부가적인 책임은 의존성 함수로 분리할 수 있다.
  • 코드 재사용: 공통 의존성을 여러 경로에서 공유하여 코드 중복을 줄인다.
  • 자원 관리: yield를 사용하는 의존성은 DB 커넥션처럼 전후 처리가 필요한 자원을 안전하게 관리하는 데 유용하다. yield 이전 코드는 요청 처리 전에, 이후 코드는 응답이 전송된 후에 실행되어 자원 반납을 보장한다.


2. FastAPI 구현: 주요 기능 활용법

이론을 바탕으로 실제 코드에서 FastAPI의 주요 기능을 어떻게 활용하는지 살펴본다.

2.1. 기본 API와 데이터 유효성 검사

Pydantic 모델을 사용하여 요청 본문을 정의하고 유효성을 검사하는 기본적인 예제다.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional

app = FastAPI()

class Item(BaseModel):
    name: str = Field(..., min_length=1, description="아이템의 이름")
    price: float = Field(..., gt=0, description="가격은 0보다 커야 함")
    tags: List[str] = []
    description: Optional[str] = None

@app.post("/items/", response_model=Item)
def create_item(item: Item):
    """
    새로운 아이템을 생성한다.
    - 요청 본문은 Item 모델의 스키마를 따라야 한다.
    - 성공 시 생성된 아이템 정보를 반환한다.
    """
    # 실제로는 여기서 DB에 저장하는 로직이 들어간다.
    # 예: db.add(item); db.commit();
    return item

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id > 100:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id, "name": "Sample Item"}

2.2. 실시간 응답을 위한 스트리밍

LLM(거대 언어 모델) 기반 챗봇처럼 응답 생성에 시간이 오래 걸리는 경우, StreamingResponse를 사용하면 생성되는 내용을 토큰 단위로 실시간 전송하여 사용자 경험을 크게 향상시킬 수 있다.

import asyncio
from fastapi import FastAPI
from fastapi.responses import StreamingResponse

app = FastAPI()

async def fake_llm_response_generator():
    """LLM이 토큰을 생성하는 것을 흉내 내는 비동기 제너레이터"""
    response_chunks = ["안녕하세요! ", "저는 FastAPI로 ", "만들어진 ", "AI 챗봇입니다."]
    for chunk in response_chunks:
        yield chunk
        await asyncio.sleep(0.5) # 각 토큰 생성 간의 지연 시간

@app.get("/chat")
async def stream_chat():
    """SSE(Server-Sent Events)를 사용하여 채팅 응답을 스트리밍한다."""
    return StreamingResponse(fake_llm_response_generator(), media_type="text/event-stream")

2.3. 의존성 주입을 활용한 공통 로직 처리

모든 요청에 공통적으로 적용되어야 하는 헤더 값을 검증하는 의존성을 만들어본다.

from fastapi import FastAPI, Depends, Header, HTTPException

app = FastAPI()

async def verify_api_key(x_api_key: str = Header(...)):
    """API 키를 검증하는 의존성 함수"""
    if x_api_key != "fake-secret-api-key":
        raise HTTPException(status_code=403, detail="Invalid API Key")
    return x_api_key

# /protected-route 엔드포인트는 verify_api_key 의존성을 가진다.
# 따라서 유효한 X-API-Key 헤더가 없으면 이 함수는 실행되지 않는다.
@app.get("/protected-route", dependencies=[Depends(verify_api_key)])
async def protected_route():
    return {"message": "You have access to the protected route!"}


3. 프로덕션 배포 및 운영 전략

API 개발만큼이나 안정적인 배포와 운영은 중요하다. 프로덕션 환경에서 고려해야 할 핵심 전략들을 알아본다.

3.1. 배포: Uvicorn과 Gunicorn

  • Uvicorn: FastAPI가 권장하는 고성능 ASGI(Asynchronous Server Gateway Interface) 서버다. 단일 프로세스로 실행되며, 개발 환경이나 소규모 트래픽에 적합하다.
  • Gunicorn: 여러 Uvicorn 워커 프로세스를 관리해주는 프로세스 매니저다. 멀티코어 CPU의 이점을 최대한 활용하고, 워커 중 하나가 다운되어도 다른 워커가 요청을 처리하도록 하여 안정성을 높인다.
  • 프로덕션 실행 명령어: gunicorn -w 4 -k uvicorn.workers.UvicornWorker my_app.main:app
    • -w 4: 4개의 워커 프로세스를 실행한다. (일반적으로 (2 * CPU 코어 수) + 1로 설정)
    • -k uvicorn.workers.UvicornWorker: Gunicorn이 Uvicorn 워커 클래스를 사용하도록 설정한다.

3.2. API 버전 관리

API가 진화함에 따라 기존 클라이언트의 호환성을 깨지 않기 위해 버전 관리는 필수다. 가장 직관적이고 널리 쓰이는 방법은 URL 경로에 버전을 명시하는 것이다.

  • 예시: /api/v1/users, /api/v2/users
  • 구현: FastAPI의 APIRouter를 사용하여 버전별로 라우팅 파일을 분리하고, 메인 앱에서 이를 포함시키는 방식으로 관리할 수 있다.

3.3. 보안: 인증과 인가

  • 인증(Authentication): 사용자가 누구인지 확인하는 과정. FastAPI에서는 OAuth2와 JWT(JSON Web Tokens)를 사용하는 것이 표준적인 패턴이다. fastapi.security 모듈은 이를 구현하기 위한 헬퍼 클래스를 제공한다.
  • 인가(Authorization): 인증된 사용자가 특정 작업을 수행할 권한이 있는지 검증하는 과정. OWASP API Security Top 10의 1위인 BOLA(Broken Object Level Authorization) 취약점을 막는 것이 가장 중요하다.
    • 핵심 원칙: 모든 엔드포인트에서 요청된 리소스의 소유자가 현재 인증된 사용자와 일치하는지 반드시 확인해야 한다.
    • 구현: 리소스를 조회하거나 변경하는 로직의 시작 부분에 소유권 검증 코드를 추가한다. (예: if resource.owner_id != current_user.id: raise HTTPException(403))

3.4. 성능 최적화: 캐싱과 사용량 제한

  • 캐싱(Caching): 데이터베이스 조회나 외부 API 호출처럼 비용이 비싼 작업의 결과를 Redis와 같은 인메모리 저장소에 캐싱하여 응답 속도를 높이고 부하를 줄인다. fastapi-cache2와 같은 라이브러리를 활용할 수 있다.
  • 사용량 제한(Rate Limiting): 악의적인 공격이나 비정상적인 요청으로부터 API를 보호하기 위해 특정 시간 동안의 요청 횟수를 제한한다. slowapi 라이브러리를 사용하여 IP 주소별, 사용자별, 엔드포인트별로 유연한 제한 정책을 적용할 수 있다.

3.5. 관찰 가능성: 로깅과 에러 처리

  • 구조화된 로깅(Structured Logging): 단순 텍스트가 아닌 JSON 형식으로 로그를 남기면, 나중에 로그를 검색, 필터링, 분석하기 용이하다. structlog 라이브러리를 FastAPI와 함께 사용하면 요청마다 고유 trace_id를 부여하여 분산 환경에서의 요청 흐름을 추적하는 데 도움이 된다.
  • 전역 예외 핸들러: @app.exception_handler() 데코레이터를 사용하여 예상치 못한 예외가 발생했을 때, 일관된 형식의 오류 응답을 클라이언트에게 반환하도록 중앙에서 처리할 수 있다.

3.6. 문서화와 개발자 경험(DX)

FastAPI의 가장 큰 장점 중 하나는 코드로부터 대화형 API 문서를 자동 생성하는 기능이다.

  • Swagger UI (/docs): API 명세를 기반으로 각 엔드포인트를 직접 테스트해볼 수 있는 대화형 UI를 제공한다.
  • ReDoc (/redoc): 가독성이 뛰어난 정적 문서 뷰를 제공한다.
  • 문서 품질 향상: Pydantic 모델의 Field나 경로 작동 함수의 데코레이터에 description, summary, example 등의 메타데이터를 추가하면 문서의 품질을 크게 높일 수 있다.


4. 부록: 다른 API 아키텍처와의 비교

FastAPI가 주로 사용하는 REST 방식 외에도, 특정 요구사항에 더 적합할 수 있는 다른 API 아키텍처들이 있다.

4.1. 언제 다른 선택을 고려해야 하는가?

  • GraphQL: 다양한 클라이언트(웹, 모바일 등)가 각기 다른 데이터 조합을 필요로 할 때, 여러 백엔드 서비스의 데이터를 한 번의 요청으로 통합해야 할 때 유용하다.
  • gRPC: 마이크로서비스 간의 내부 통신처럼 지연 시간에 극도로 민감하고 초당 처리량이 매우 중요할 때, 혹은 대용량 데이터 스트리밍이 필요할 때 최고의 성능을 제공한다.

4.2. GraphQL: 클라이언트 중심의 유연한 데이터 요청

GraphQL은 클라이언트가 필요한 데이터의 구조를 쿼리로 직접 선언할 수 있게 하는 기술이다.

  • 장점: 클라이언트가 필요한 데이터만 정확히 요청하므로 오버-페칭(Over-fetching)과 언더-페칭(Under-fetching) 문제를 해결하여 네트워크 효율을 높인다.
  • 단점: 유연성이 높은 만큼 클라이언트가 너무 복잡한 쿼리를 요청하여 서버에 과부하를 줄 수 있으며, 표준 HTTP 캐싱을 적용하기 어렵다.
  • Python 구현: strawberry 라이브러리를 사용하면 FastAPI 위에서 GraphQL API를 쉽게 구현할 수 있다.

4.3. gRPC: 마이크로서비스를 위한 고성능 통신

gRPC는 구글이 개발한 고성능 원격 프로시저 호출(RPC) 프레임워크다.

  • 장점: 텍스트 기반의 JSON 대신 이진(binary) 형식의 프로토콜 버퍼(Protocol Buffers)를 사용하여 데이터를 직렬화하고, HTTP/2를 기반으로 통신하여 매우 빠르다. 양방향 스트리밍을 기본적으로 지원한다.
  • 단점: 브라우저에서 직접 호출하려면 gRPC-Web이라는 별도의 프록시가 필요하여, 주로 내부 백엔드 서비스 간 통신에 사용된다.


결론

FastAPI는 현대적인 API 개발에 필요한 성능, 생산성, 안정성을 모두 제공하는 강력한 프레임워크다. 이 글에서 다룬 FastAPI의 핵심 원리, 즉 Pydantic을 통한 데이터 계약, 의존성 주입을 통한 관심사 분리, 그리고 비동기 처리를 통한 성능 확보를 깊이 이해하는 것이 중요하다.

성공적인 API 운영을 위해서는 단순히 기능을 구현하는 것을 넘어, 버전 관리, 보안, 캐싱, 로깅 등 프로덕션 환경의 현실적인 문제들을 처음부터 고려하여 아키텍처를 설계해야 한다. 가장 효과적인 전략은 FastAPI와 REST로 작게 시작하여 핵심 기능을 안정적으로 구축하고, 시스템이 성장함에 따라 GraphQL 게이트웨이나 내부 gRPC 통신과 같은 특화된 기술을 점진적으로 도입하는 것이다. 결국, 장기적으로 유지보수하기 좋은 시스템을 만드는 비결은 ‘명확한 계약’과 ‘일관된 운영 패턴’을 초기에 확립하는 데 있다.

댓글남기기

참고