FastAPI에 대해 알아보기

맑음·2025년 5월 5일
FastAPIpython
0
post-thumbnail

FastAPI는 Python 기반의 최신 웹 프레임워크로 빠르고 간결하게 API 서버를 만들 수 있습니다
이 글에서는 FastAPI의 핵심 개념과 기본 사용법을 정리해 보았습니다

FastAPI란 무엇인가?

FastAPI는 Python 3.6+를 위한 현대적이고 고성능의 웹 프레임워크로 표준 Python 타입 힌트를 기반으로 API를 쉽고 빠르게 개발할 수 있도록 설계되었습니다
내부적으로는 비동기 지원을 위한 ASGI 서버인 Starlette 위에서 동작하며 데이터 모델 검증을 위해 Pydantic을 사용합니다
이를 통해 FastAPI는 동시성 (비동기)을 활용하여 Node.js나 Go와 견줄 정도의 뛰어난 성능을 제공하고 개발 생산성을 크게 높여줍니다
또한 Swagger UI와 ReDoc 같은 자동 문서화 도구를 기본으로 지원해 API 문서를 자동으로 생성합니다

이 글에서는 FastAPI의 핵심 개념과 기본 사용법을 정리해 보았습니다

FastAPI의 주요 특징과 장점

FastAPI는 다음과 같은 장점을 갖추고 있어 API 개발에 유리합니다

  • 고성능 (비동기 지원): FastAPI는 속도 최적화를 위해 설계되었으며, async/await를 사용한 비동기 처리를 기본으로 지원합니다
    덕분에 많은 수의 동시 요청을 효율적으로 처리할 수 있고 NodeJS/Go 수준의 성능을 보여줍니다

  • 자동 문서화: OpenAPI (이전의 Swagger) 표준을 활용해 /docs(Swagger UI)와 /redoc 경로에서 인터랙티브 API 문서를 자동 생성합니다
    별도 구현 없이 API 스키마를 기반으로 실시간으로 문서가 업데이트됩니다

  • 타입 검증 및 Pydantic: Python 타입 힌트로 요청 및 응답 모델을 선언하면 FastAPI가 Pydantic으로 자동 검증하고 직렬화합니다
    개발자는 올바른 데이터 타입을 정의하기만 하면 FastAPI가 입력 데이터의 유효성을 자동으로 검사해 줍니다

  • 빠른 개발 속도: 타입 힌트와 자동화된 직렬화 덕분에 작성해야 할 코드가 줄어들고 IDE 자동완성도 원활해 개발 속도가 크게 향상됩니다
    공식 문서도 튜토리얼부터 고급 과정까지 잘 정리되어 있어 학습이 비교적 쉽습니다

  • 의존성 주입 시스템: FastAPI는 내장된 의존성 주입 (Dependency Injection) 시스템이 있어, 데이터베이스 세션, 인증 정보 등 공통 로직을 재사용하기 쉽습니다
    이는 컴포넌트 간 결합도를 낮추고 모듈화를 돕습니다

  • 안정성·표준 준수: 보안과 관련된 기능 (인증, 권한 관리)도 내장되어 있고 OpenAPI/JSON Schema 같은 표준을 완벽히 따릅니다

Starlette 기반 비동기 처리

FastAPI는 ASGI(Asynchronous Server Gateway Interface) 서버인 Starlette를 기반으로 구축되었습니다
이 아키텍처는 동시에 수천 개의 연결을 처리할 수 있는 비동기 처리 능력을 제공하며 전통적인 WSGI 기반 프레임워크 대비 3배 이상의 처리량을 자랑합니다
아래는 비동기 엔드포인트 구현 예시입니다

from fastapi import FastAPI
import asyncio

app = FastAPI()

@app.get("/async-example")
async def async_endpoint():
    await asyncio.sleep(1)
    return {"message": "비동기 처리 완료"}

Python의 async def, await를 사용하면 비동기 함수가 됩니다
비동기 처리를 통해 I/O 작업 (예: DB 호출, 외부 API 통신) 중에 CPU를 차지하지 않고 다른 작업을 동시에 실행할 수 있게 해 줍니다

Pydantic을 활용한 데이터 모델링

Pydantic은 Python 타입 힌트를 기반으로 데이터 유효성 검사 및 직렬화/역직렬화를 자동화해주는 데이터 모델링 라이브러리입니다
FastAPI는 Pydantic을 활용하여 요청 (Request) 데이터 유효성 검사, 응답 (Response) 데이터 직렬화, OpenAPI 문서 자동 생성을 수행합니다
아래는 기본 모델 정의 예제입니다

from pydantic import BaseModel
from typing import Optional

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

주요 구성 요소

FastAPI 애플리케이션의 기본 구성 요소는 다음과 같습니다

  • 경로 연산 함수 (Path Operation): @app.get(), app.post()등의 데코레이터로 URL 경로와 HTTP 메서드를 지정합니다
    함수의 파라미터는 URL 경로나 쿼리, 본문 등의 요청 데이터와 매핑됩니다

  • 요청/응답 모델: 복잡한 요청 본문(JSON 등)은 Pydantic의 BaseModel 클래스를 상속하여 모델을 정의하고 엔드포인트 함수의 인자로 선언할 수 있습니다
    아래는 모델 정의의 예시입니다

    from typing import Union
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: Union[bool, None] = None

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "name": item.name, "price": item.price}

    이처럼 FastAPI는 함수 파라미터의 타입으로 Pydantic 모델을 사용하면 전달된 JSON을 자동으로 Item 객체로 변환하고 검증하여 처리합니다

  • 의존성 주입 (Dependency Injection): FastAPI의 강력한 특징으로 공통 로직을 Depends로 묶어 재사용할 수 있습니다
    예를 들어 데이터베이스 연결이나 인증 처리를 의존성 함수로 분리하면 각 경로 함수에서 쉽게 주입받아 사용할 수 있습니다
    FastAPI는 이러한 의존성을 자동으로 관리해 모듈화와 테스트가 용이합니다

설치 및 기본 예제

FastAPI는 간단하게 설치할 수 있습니다
아래의 코드처럼 pip를 사용해 FastAPI와 ASGI 서버인 Uvicorn을 함께 설치합니다

pip install fastapi
pip install "uvicorn[standard]"

이제 main.py 파일을 만들어 다음과 같이 간단한 애플리케이션을 작성합니다

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

혹은 async def를 사용해보고 싶으면 아래의 코드도 괜찮습니다

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

코드를 저장한 후 아래의 명령어를 통해 Uvicorn을 실행하여 서버를 구동합니다
그럼 아래의 사진과 같이 나타날 것입니다

$ uvicorn main:app --reload

--reload: 코드 변경 시 자동으로 서버가 재시작됩니다

이제 서버를 실행시켰으니 localhost:8000 혹은 127.0.0.1:8000에 접속해봅시다
아래와 같이 뜨는 것을 확인할 수 있습니다

{"Hello":"World"}

이제 우리는 엔드포인트의 root에 도달했습니다!
FastAPI에서 엔드 포인트 중 root는 기본 URL(/)로 접근했을 때 동작하는 엔드포인트를 말합니다
즉, 사용자가 웹 브라우저나 HTTP 클라이언트를 통해 http://localhost:8000/ 또는 https://example.com/처럼 도메인 뒤에 아무 경로도 붙이지 않고 접근할 때 실행되는 API입니다

이번에는 http://127.0.0.1:8000/items/5?q=somequery를 열어봅시다
아래와 같은 결과가 나타날 것입니다

{"item_id":5,"q":"somequery"}

Swagger 및 ReDoc을 이용한 API 문서화

FastAPI는 자동 문서화를 기본 지원합니다
서버를 실행하면 /docs 경로에서 Swagger UI를, /redoc 경로에서 ReDoc 문서를 볼 수 있습니다

Swagger UI

FastAPI는 자동 문서화를 기본 지원합니다
Swagger는 RESTful API를 설계, 문서화, 테스트할 수 있게 도와주는 오픈소스 프레임워크입니다

http://127.0.0.1:8000/docs 에 접속하면 아래와 같이 나타나게 됩니다
GET 요청을 Swagger UI에서 직접 해봅시다
Try it out을 누른 후 item_id에 숫자를 넣고 q에 원하는 string을 넣어봅시다
그 다음 Execute를 누르면 아래의 사진과 같이 응답을 확인할 수 있습니다
제대로 응답을 받았다면 HTTP 200이 뜰 것이고 작성한 대로 응답을 받을 수 있습니다
이렇게 브라우저에서 편하게 직접 API와 상호작용이 가능합니다!

ReDoc

ReDoc은 Swagger(OpenAPI) 스펙을 기반으로 한 API 문서화 도구입니다
Swagger UI와 함께 자동으로 제공되는 또 다른 API 문서 인터페이스입니다
Swagger UI가 API 테스트 중심이라면 ReDoc의 경우 API 문서 열람이 중심이 됩니다

이번에는 http://127.0.0.1:8000/redoc 으로 접속해봅시다
아래의 사진처럼 나타날 것입니다
읽기 좋은 레이아웃으로 깔끔한 것이 특징입니다

Swagger UI는 인터랙티브한 테스트 기능이 강점이고 ReDoc은 문서형 API 문서를 제공하는 데 적합합니다

Django/Flask 등 기존 프레임워크와 비교

Django

전통적인 풀스택 웹 프레임워크 모델-뷰-템플릿(Model-View-Template) 아키텍처를 채택했습니다
기본적으로 많은 강력한 기능을 내장하고 있습니다
그리고 대규모 프로젝트에서의 구조적 일관성 유지에 최적화되어 있습니다
하지만 프레임워크가 제공하는 방식대로 개발해야 하기 때문에 유연성이 떨어질 수 있고 복잡한 커스터마이징이 필요할 경우 구조가 다소 부담스러울 수 있습니다

아래는 Django의 기본 뷰 예제입니다

# Django 기본 뷰 예제
from django.http import HttpResponse

def index(request):
    return HttpResponse("Hello, Django!")

Flask

Flask는 WSGI 기반의 마이크로 프레임워크로, 코어 기능만 제공하고 확장성을 염두에 둔 설계가 특징입니다
이름 그대로 최소한의 기능만 제공하며 나머지는 모두 개발자가 필요한 대로 구성해야 합니다
유연함 덕분에 Flask는 실험적인 프로젝트나 소규모 웹 애플리케이션에 적합합니다
이는 자유도가 높다는 장점이 있지만 반대로 말하면 개발자가 모든 구조를 설계해야 하므로 규모가 커질수록 복잡도가 올라갈 수 있습니다

아래는 Flask 기본 앱 예제입니다

# Flask 기본 앱 예제
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello, Flask!"

FastAPI

Starlette 기반의 ASGI 프레임워크로 비동기 처리를 기본으로 지원하며, Pydantic을 통한 타입 힌트 기반 데이터 검증 시스템이 특징입니다
또한 API 문서를 Swagger와 ReDoc으로 자동 생성해주기 때문에 REST API 백엔드를 구축할 때 개발 효율이 뛰어납니다
JSON 기반의 API 서버를 만들거나 프론트엔드와의 분리가 명확한 프로젝트에 매우 유리하지만 Django처럼 전통적인 웹사이트를 만드는 데는 적합하지 않을 수 있습니다

아래는 FastAPI 비동기 엔드포인트 예제입니다

# FastAPI 비동기 엔드포인트 예제
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello FastAPI"}

각 프레임워크는 무조건 이것이 좋다가 아닌 서로 고유한 강점을 갖추고 있어 프로젝트 요구사항, 팀 역량, 장기적 로드맵을 종합적으로 고려한 선택이 필요합니다
그렇기에 중요한 것은 어떤 문제에 어떻게 활용하냐는 것입니다

마무리

FastAPI는 RESTful API 구축에 최적화되어 있어 마이크로서비스부터 대규모 웹 애플리케이션까지 폭넓게 사용됩니다
예를 들어 초당 수천 건의 요청을 처리해야 하는 고성능 API나, 입력 데이터 검증이 필수인 머신러닝 배포 환경에 잘 어울립니다
하지만 FastAPI는 상대적으로 신규 프레임워크이므로 Django/Flask에 비해 생태계와 플러그인이 아직 적은 편입니다

공식 문서에서 튜토리얼과 레퍼런스를 확인할 수 있습니다 -> FastAPI 공식문서 한글 번역도 존재합니다!
이 글도 공식 문서를 참고해 정리했습니다!

Python으로 백엔드 개발을 해보고 싶다면 FastAPI를 선택해보는 건 어떨까요? 매력적인 선택이 될 것입니다!

profile
맑음
내일도 맑음
이전 포스트

Docker에 대해 알아보기

다음 포스트

SQL 기본 문법에 대해 알아보기

0개의 댓글