FastAPI에서 영감을 받은 API로 Django 개발 가속화하기

소개

끊임없이 진화하는 웹 개발 환경에서 강력하고 성능이 뛰어난 API를 구축하는 것이 무엇보다 중요합니다. Django는 "포함된 배터리" 접근 방식과 ORM 기능으로 오랫동안 선호되어 왔지만, 전통적인 REST API 솔루션은 강력하지만 현대적이고 유형 힌트가 적용된 API 사양에 대해 다소 많은 보일러플레이트와 약간 더 가파른 학습 곡선을 도입하는 경우가 있습니다. 반면에 FastAPI와 같은 프레임워크의 등장은 속도, 사용 편의성, 자동 대화형 문서화에 중점을 두어 API 개발에 혁명을 일으켰으며, 이 모든 것은 Python 유형 힌트에 의해 지원됩니다. 이로 인해 많은 Django 개발자가 기존 프로젝트에 이러한 매력적인 FastAPI와 유사한 기능을 통합할 방법을 모색하게 되었습니다. 이 글에서는 familiar Django 환경 내에서 최소한의 노력으로 고성능 API를 구축할 수 있도록 하여 FastAPI와 유사한 개발 경험을 제공하는 현대 Python 웹 프레임워크인 Django Ninja에 대해 자세히 알아봅니다.

Django에서 현대 API 개발의 해방

Django Ninja의 구체적인 내용에 들어가기 전에, 이 현대적인 API 개발 접근 방식을 정의하고 Django 프로젝트를 어떻게 강화하는지에 대한 핵심 개념을 명확히 이해해 봅시다.

핵심 용어

유형 힌트(PEP 484): Python 유형 힌트는 Python 3.5에 도입된 구문으로, 개발자가 변수, 함수 인수 및 반환 값의 예상 유형을 표시할 수 있습니다. 기본적으로 런타임에 적용되지는 않지만, 정적 분석 도구, IDE 및 FastAPI, Django Ninja와 같은 프레임워크가 데이터 유효성 검사, 직렬화 및 자동 문서화와 같은 기능을 제공하는 데 중요합니다.
Pydantic: Python 유형 주석을 사용하는 데이터 유효성 검사 및 설정 관리 라이브러리입니다. Pydantic 모델은 FastAPI 및 Django Ninja에서 요청(입력 유효성 검사) 및 응답(출력 직렬화)의 데이터 스키마를 정의하는 데 광범위하게 사용되어 데이터 무결성 및 일관성을 보장합니다.
OpenAPI(Swagger): RESTful 웹 서비스를 설명, 생성, 소비 및 시각화하기 위한 언어에 구애받지 않는 사양입니다. Swagger UI와 같은 도구는 OpenAPI 사양에서 대화형 API 문서를 자동으로 생성하여 개발자가 API를 이해하고 테스트하는 것을 더 쉽게 만듭니다. FastAPI 및 Django Ninja는 Pydantic 모델과 유형 힌트를 활용하여 OpenAPI 문서를 자동으로 생성합니다.
ASGI(Asynchronous Server Gateway Interface): WSGI의 정신적 후계자로, 비동기 Python 웹 애플리케이션을 지원하도록 설계되었습니다. Django는 주로 WSGI를 사용하지만, Django Ninja는 ASGI를 기반으로 구축되어 I/O 바운드 작업에서 성능을 향상시키기 위해 비동기 기능을 활용할 수 있습니다.
의존성 주입: 객체 또는 함수가 자체적으로 생성하는 대신 외부 소스에서 필요한 종속성을 받는 소프트웨어 설계 패턴입니다. API 프레임워크에서는 종종 데이터베이스 세션, 인증 또는 기타 공유 리소스를 관리하는 데 사용되어 코드를 더 모듈화하고 테스트하기 쉽게 만듭니다.

Django Ninja의 힘

Django Ninja는 Django를 사용하여 API를 구축하는 웹 프레임워크로, FastAPI에서 많은 영감을 받았습니다. 주요 철학은 기존 Django 프로젝트와 원활하게 통합하면서 API 개발을 가능한 한 빠르고 직관적이며 성능을 발휘하도록 만드는 것입니다.

이를 달성하는 방법:

유형 힌트 및 Pydantic 활용: Django Ninja는 Python 유형 힌트와 Pydantic 모델을 광범위하게 활용합니다. Pydantic 모델(기본적으로 유형 주석이 있는 Python 클래스)을 사용하여 API 요청 본문, 쿼리 매개변수 및 응답 구조를 정의합니다. Django Ninja는 다음을 자동으로 처리합니다:
- 데이터 유효성 검사: 들어오는 요청 데이터는 Pydantic 스키마에 대해 자동으로 유효성 검사됩니다. 잘못된 데이터는 명확하고 표준화된 오류 응답으로 처리됩니다.
- 데이터 직렬화: Python 개체(예: Django 모델 인스턴스)는 Pydantic 출력 스키마에 따라 JSON 응답으로 자동으로 직렬화됩니다.
- 자동 문서화: FastAPI와 마찬가지로 Django Ninja는 유형 힌트가 적용된 API 엔드포인트에서 포괄적인 OpenAPI 문서(Swagger UI 및 ReDoc)를 자동으로 생성합니다. 이를 통해 API 문서화에 필요한 노력을 크게 줄일 수 있습니다.
현대 라우팅 및 데코레이터: Django Ninja는 Flask 또는 FastAPI와 같은 프레임워크의 단순성을 반영하는 깨끗하고 데코레이터 기반 구문을 제공하여 API 엔드포인트를 정의합니다. Python 함수를 데코레이션하여 API 경로를 정의하고 HTTP 메서드를 지정하며 입력/출력 유형을 선언합니다.
의존성 주입: Django Ninja는 강력한 의존성 주입 시스템을 제공합니다. 이를 통해 데이터베이스 세션, 인증된 사용자 또는 구성 설정과 같은 공통 구성 요소를 API 함수에 쉽게 주입하여 재사용성을 높이고 테스트를 단순화할 수 있습니다.
비동기 지원(ASGI): Django Ninja는 ASGI와 호환되므로 async def를 사용하여 비동기 뷰 함수를 작성할 수 있습니다. 이를 통해 API 엔드포인트는 여러 요청을 동시에 처리할 수 있으며, 이는 I/O 바운드 작업에 특히 유용합니다.

실용적인 구현 및 예제

몇 가지 실제 코드 예제를 통해 이러한 개념을 Django 프로젝트 내에서 설명해 보겠습니다.

먼저 Django Ninja를 설치합니다.

pip install django-ninja pydantic

그런 다음 settings.py에서 INSTALLED_APPS에 ninja를 추가합니다.

1. Pydantic 모델을 사용한 기본 API 엔드포인트:

Product라는 Django 모델이 있다고 가정해 보겠습니다.

# app/models.py
from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2)
    in_stock = models.BooleanField(default=True)

    def __str__(self):
        return self.name

이제 제품을 관리하기 위한 Django Ninja API를 만들어 보겠습니다.

# app/api.py
from ninja import NinjaAPI, Schema
from typing import List
from .models import Product

api = NinjaAPI()

# 새 제품 생성을 위한 Pydantic 스키마
class ProductIn(Schema):
    name: str
    description: str
    price: float
    in_stock: bool = True # 기본값

# 제품 반환을 위한 Pydantic 스키마 (ID 포함)
class ProductOut(Schema):
    id: int
    name: str
    description: str
    price: float
    in_stock: bool

# 제품을 생성하는 API 엔드포인트
@api.post("/products", response=ProductOut)
def create_product(request, product: ProductIn):
    product_obj = Product.objects.create(**product.dict())
    return product_obj # Django Ninja는 Django 모델을 ProductOut으로 자동 변환합니다.

# 모든 제품을 가져오는 API 엔드포인트
@api.get("/products", response=List[ProductOut])
def list_products(request):
    return Product.objects.all()

# ID별 단일 제품을 가져오는 API 엔드포인트
@api.get("/products/{product_id}", response=ProductOut)
def get_product(request, product_id: int):
    product = Product.objects.get(id=product_id)
    return product

마지막으로 API를 Django의 URL 라우팅에 연결합니다.

# project_name/urls.py
from django.contrib import admin
from django.urls import path
from app.api import api # NinjaAPI 인스턴스 가져오기

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", api.urls), # NinjaAPI를 /api/에 마운트합니다.
]

Django 개발 서버를 실행하고 http://127.0.0.1:8000/api/docs로 이동하면 Pydantic 모델과 유형 힌트에서 모두 파생된 요청 본문 예제와 응답 스키마가 포함된 완전한 대화형 Swagger UI가 자동으로 생성된 것을 볼 수 있습니다!

2. 쿼리 매개변수 및 경로 매개변수:

Django Ninja는 유형 힌트를 사용하여 이를 자연스럽게 처리합니다.

# app/api.py (계속)
@api.get("/products/search", response=List[ProductOut])
def search_products(request, q: str, min_price: float = 0.0, max_price: float = 1000.0):
    products = Product.objects.filter(name__icontains=q, price__gte=min_price, price__lte=max_price)
    return products

여기서 q는 필수 쿼리 매개변수이고, min_price와 max_price는 기본값이 있는 선택적 매개변수입니다.

3. 인증을 위한 의존성 주입:

간단한 API 키 인증을 상상해 보겠습니다.

# app/api.py (계속)
from ninja.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

def get_current_user(request, api_key: str = Depends(api_key_header)):
    # 실제 앱에서는 API 키를 데이터베이스와 비교할 것입니다.
    if api_key == "supersecretkey":
        return {"username": "admin_user", "id": 1}
    raise Http401("Invalid API Key")

@api.get("/secure-data", auth=api_key_header) # 인증에 APIKeyHeader 사용
def get_secure_data(request, user: dict = Depends(get_current_user)):
    return {"message": f"Welcome, {user['username']}! Here's your secure data."}

@api.get 데코레이터에 auth=api_key_header를 추가하면 Django Ninja가 이 인증 스키마를 자동으로 적용합니다. get_current_user에 대한 Depends 개체는 get_secure_data 함수가 호출되기 전에 헤더에서 api_key가 추출되고 유효성이 검사되도록 합니다.

애플리케이션 시나리오:

고성능 REST API 구축: 속도와 명확한 API 계약이 필수적인 마이크로서비스 또는 백엔드 for 프론트엔드(BFF) 아키텍처용.
빠른 API 프로토타이핑: 자동 문서화 및 스키마 유효성 검사는 새로운 API 엔드포인트 개발 및 반복을 훨씬 빠르게 처리합니다.
기존 Django 프로젝트와 통합: DRF를 대체하는 것이 아니라, 특히 새로운 API 개발을 위해 DRF와 함께 존재할 수 있는 보완적인 도구입니다.
엄격한 데이터 계약이 필요한 프로젝트: Pydantic은 API로 들어오고 나가는 데이터가 정의된 스키마를 정확하게 준수하도록 합니다.

결론

Django Ninja는 Django 개발자가 FastAPI와 유사한 개발 경험을 통해 현대적이고 성능이 뛰어나며 잘 문서화된 API를 구축할 수 있도록 지원합니다. Python 유형 힌트, 데이터 유효성 검사 및 직렬화를 위한 Pydantic, 자동 OpenAPI 생성을 채택함으로써 API 개발을 간소화하고, 보일러플레이트를 줄이며, 개발자 생산성을 크게 향상시킵니다. 현대 API 디자인 모범 사례를 통합하려는 모든 Django 프로젝트에 대해 Django Ninja는 API 개발의 미래를 여러분의 손끝에 직접 제공하는 강력하고 우아한 솔루션입니다. Django Ninja를 사용하여 강력하고 효율적인 API를 제작하여 Django 프로젝트를 기능적일 뿐만 아니라 개발하고 유지 관리하기 즐겁게 만드십시오.