Django REST Framework ViewSets: API 엔드포인트 구성 마스터하기

현대 웹 개발에서 강력하고 잘 구성된 API를 구축하는 것은 매우 중요합니다. Django REST Framework (DRF)는 Django로 RESTful API를 만들기 위한 강력한 툴킷입니다. DRF는 API 엔드포인트를 만들기 위한 다양한 도구를 제공하지만, ViewSets는 관련 보기를 단일 클래스로 구성하는 우아한 방법을 제공하여 더 깔끔하고 유지 관리하기 쉬운 코드를 만듭니다. 이 종합 가이드는 ViewSets의 이점, 사용법 및 고급 사용자 정의 기술을 포함하여 자세히 살펴봅니다.

ViewSet이란 무엇입니까?

ViewSet은 list, create, retrieve, update 및 destroy와 같은 표준 작업에 대한 구현을 제공하는 클래스 기반 View입니다. 각 작업에 대해 별도의 보기를 정의하는 대신 ViewSet은 이러한 작업을 단일 클래스로 결합하여 API 구조를 단순화하고 코드 중복을 줄입니다. ViewSets는 이러한 표준 작업이 일반적으로 필요한 모델 기반 API로 작업할 때 특히 유용합니다. ViewSet을 특정 리소스에 대한 작업의 논리적 그룹으로 생각하십시오.

ViewSet 사용의 이점

• 코드 재사용성: ViewSets는 일반적인 API 로직을 단일 클래스에 캡슐화하여 코드 재사용을 촉진합니다. 이렇게 하면 중복성이 줄어들고 코드를 더 쉽게 유지 관리할 수 있습니다.
• 간소화된 라우팅: ViewSets는 관련 보기를 단일 URL 접두사로 그룹화하여 라우팅을 단순화합니다. 이렇게 하면 더 깔끔하고 구성된 URL 구조가 됩니다.
• 감소된 상용구: ViewSets는 일반적인 API 작업에 대한 기본 구현을 제공하여 상용구 코드를 줄입니다. 이를 통해 개발자는 애플리케이션에 특정한 사용자 지정 로직 구현에 집중할 수 있습니다.
• 향상된 가독성: ViewSets는 관련 보기를 단일 클래스로 구성하여 코드 가독성을 향상시킵니다. 이렇게 하면 API 구조를 더 쉽게 이해하고 탐색할 수 있습니다.
• 일관성: ViewSets는 표준 작업 및 규칙 세트를 적용하여 API 전체의 일관성을 보장하는 데 도움이 됩니다. 이렇게 하면 API가 더 예측 가능하고 사용하기 쉬워집니다.

ViewSet의 기본 사용법

ViewSet을 사용하여 제품 관리를 위한 API를 만드는 간단한 예제부터 시작하겠습니다. 먼저 모델을 정의합니다.

            # 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)

    def __str__(self):
        return self.name

            

              
                Copy
              
            
          

다음으로 Product 모델에 대한 직렬화 프로그램을 정의합니다.

            # serializers.py
from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = '__all__'

            

              
                Copy
              
            
          

이제 Product 모델에 대한 ViewSet을 만듭니다.

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

            

              
                Copy
              
            
          

마지막으로 URL 라우팅을 구성합니다.

            # urls.py
from django.urls import path, include
from rest_framework import routers
from . import views

router = routers.DefaultRouter()
router.register(r'products', views.ProductViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

            

              
                Copy
              
            
          

이 구성은 다음 API 엔드포인트를 자동으로 생성합니다.

• /products/ (GET: list, POST: create)
• /products/{id}/ (GET: retrieve, PUT: update, PATCH: partial_update, DELETE: destroy)

ModelViewSet은 모든 표준 CRUD 작업에 대한 기본 구현을 제공합니다. queryset 속성은 ViewSet이 작동해야 하는 개체 세트를 지정하고 serializer_class 속성은 데이터를 직렬화하고 역직렬화하는 데 사용할 직렬화 프로그램을 지정합니다.

ViewSet 유형

DRF는 다양한 사용 사례에 맞는 여러 내장 ViewSet 클래스를 제공합니다.

• ViewSet: 모든 ViewSet의 기본 클래스입니다. 요청 및 응답 처리를 위한 기본 인프라를 제공합니다.
• ReadOnlyModelViewSet: 읽기 전용 작업(list 및 retrieve)을 제공하는 ViewSet입니다. 데이터 검색만 허용하는 API에 유용합니다.
• ModelViewSet: 모든 표준 CRUD 작업(list, create, retrieve, update 및 destroy)을 제공하는 ViewSet입니다. 모델 기반 API에 가장 일반적으로 사용되는 ViewSet입니다.
• GenericViewSet: 일반적인 API 작업에 대한 일반 구현을 제공하는 ViewSet입니다. 사용자 지정 ViewSet을 만드는 데 기본 클래스로 사용할 수 있습니다.

올바른 ViewSet 선택은 API의 특정 요구 사항에 따라 다릅니다. 읽기 전용 작업만 필요한 경우 ReadOnlyModelViewSet을 사용합니다. 모든 표준 CRUD 작업이 필요한 경우 ModelViewSet을 사용합니다. API 동작에 대한 더 많은 제어가 필요한 경우 GenericViewSet 또는 ViewSet에서 상속하여 사용자 지정 ViewSet을 만들 수 있습니다.

ViewSet 사용자 정의

내장 ViewSet은 API를 만드는 편리한 방법을 제공하지만 특정 요구 사항을 충족하기 위해 해당 동작을 사용자 정의해야 할 수 있습니다. DRF는 메서드 재정의, 사용자 지정 작업 추가 및 사용자 지정 직렬화 프로그램 사용을 포함하여 ViewSet을 사용자 정의하는 여러 가지 방법을 제공합니다.

메서드 재정의

ViewSet 클래스에서 이름이 같은 메서드를 정의하여 표준 API 작업의 기본 구현을 재정의할 수 있습니다. 예를 들어 새 개체를 만들기 전후에 사용자 지정 로직을 추가하기 위해 create 메서드를 재정의할 수 있습니다.

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.response import Response
from rest_framework import status

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        # Add custom logic here before creating the object
        self.perform_create(serializer)
        headers = self.get_success_headers(serializer.data)
        return Response(serializer.data, status=status.HTTP_201_CREATED, headers=headers)

            

              
                Copy
              
            
          

이 예제에서 create 메서드는 기본 구현을 재정의하고 개체를 만들기 전에 사용자 지정 로직을 추가합니다. perform_create 메서드는 실제로 개체를 만들기 위해 호출되고 응답은 201 Created 상태 코드로 반환됩니다.

사용자 지정 작업 추가

@action 데코레이터를 사용하여 ViewSet에 사용자 지정 작업을 추가할 수 있습니다. 사용자 지정 작업을 사용하면 ViewSet에서 관리하는 리소스에 대해 특정 작업을 수행하는 새 API 엔드포인트를 정의할 수 있습니다. 예를 들어 제품을 추천 제품으로 표시하는 작업을 추가할 수 있습니다.

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework import status

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

    @action(detail=True, methods=['post'])
    def feature(self, request, pk=None):
        product = self.get_object()
        product.is_featured = True
        product.save()
        serializer = self.get_serializer(product)
        return Response(serializer.data)

            

              
                Copy
              
            
          

이 예제에서 @action 데코레이터는 제품을 추천 제품으로 표시하는 새 API 엔드포인트 /products/{id}/feature/를 정의합니다. detail=True 인수는 작업이 모델의 특정 인스턴스에서 작동함을 나타냅니다. methods=['post'] 인수는 작업이 POST 요청만 수락하도록 지정합니다.

사용자 지정 직렬화 프로그램 사용

사용자 지정 직렬화 프로그램을 사용하여 ViewSet에서 데이터를 직렬화하고 역직렬화하는 방법을 사용자 정의할 수 있습니다. 이는 복잡한 데이터 구조를 처리하거나 사용자 지정 유효성 검사를 수행해야 할 때 유용합니다. 예를 들어 사용자 지정 직렬화 프로그램을 사용하여 API 응답에 관련 데이터를 포함할 수 있습니다.

            # serializers.py
from rest_framework import serializers
from .models import Product, Category

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ['id', 'name']

class ProductSerializer(serializers.ModelSerializer):
    category = CategorySerializer(read_only=True)

    class Meta:
        model = Product
        fields = '__all__'

            

              
                Copy
              
            
          

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

            

              
                Copy
              
            
          

이 예제에서 ProductSerializer는 관련 카테고리 데이터를 직렬화하기 위해 CategorySerializer를 포함합니다. 이렇게 하면 단일 API 요청에서 제품 정보와 함께 카테고리 정보를 검색할 수 있습니다.

고급 ViewSet 기술

기본 사용법 및 사용자 정의 외에도 ViewSets는 정교한 API를 구축하기 위한 고급 기술을 제공합니다.

필터링

DRF는 요청 매개변수를 기반으로 쿼리 집합을 필터링할 수 있는 강력한 필터링 기능을 제공합니다. filter_backends 속성을 사용하여 사용할 필터링 백엔드를 지정할 수 있습니다. 예를 들어 SearchFilter를 사용하여 사용자가 이름 또는 설명으로 제품을 검색할 수 있도록 할 수 있습니다.

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework import filters

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [filters.SearchFilter]
    search_fields = ['name', 'description']

            

              
                Copy
              
            
          

이 예제에서 filter_backends 속성은 SearchFilter를 사용해야 함을 지정합니다. search_fields 속성은 검색해야 하는 필드를 지정합니다.

페이지 매김

DRF는 쿼리 집합을 더 작은 페이지로 나눌 수 있는 페이지 매김 기능을 제공합니다. 이는 대규모 데이터 세트를 처리할 때 유용합니다. pagination_class 속성을 사용하여 사용할 페이지 매김 클래스를 지정할 수 있습니다. 예를 들어 PageNumberPagination을 사용하여 페이지 번호를 사용하여 결과를 페이지 매김할 수 있습니다.

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.pagination import PageNumberPagination

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    pagination_class = PageNumberPagination

            

              
                Copy
              
            
          

이 예제에서 pagination_class 속성은 PageNumberPagination을 사용해야 함을 지정합니다. 사용자 지정 페이지 매김 클래스를 만들어 페이지 매김 동작을 사용자 정의할 수도 있습니다.

인증 및 권한

DRF는 API 엔드포인트에 대한 액세스를 제어할 수 있는 유연한 인증 및 권한 메커니즘을 제공합니다. authentication_classes 및 permission_classes 속성을 사용하여 사용할 인증 및 권한 클래스를 지정할 수 있습니다. 예를 들어 TokenAuthentication을 사용하여 토큰을 사용하여 사용자를 인증하고 IsAuthenticated 권한을 사용하여 인증된 사용자만 API에 액세스하도록 할 수 있습니다.

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.authentication import TokenAuthentication
from rest_framework.permissions import IsAuthenticated

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    authentication_classes = [TokenAuthentication]
    permission_classes = [IsAuthenticated]

            

              
                Copy
              
            
          

이 예제에서 authentication_classes 속성은 TokenAuthentication을 사용해야 함을 지정하고 permission_classes 속성은 IsAuthenticated 권한을 사용해야 함을 지정합니다.

ViewSet 사용을 위한 모범 사례

ViewSet이 잘 설계되고 유지 관리 가능하도록 하려면 다음 모범 사례를 따르십시오.

• ViewSet을 집중적으로 유지하십시오: 각 ViewSet은 단일 리소스 또는 밀접하게 관련된 리소스 세트를 관리해야 합니다. 여러 개의 관련 없는 작업을 처리하는 지나치게 복잡한 ViewSet을 만들지 마십시오.
• 적절한 ViewSet 유형을 사용하십시오: API의 요구 사항에 가장 적합한 ViewSet 유형을 선택하십시오. 읽기 전용 API에는 ReadOnlyModelViewSet을 사용하고, CRUD API에는 ModelViewSet을 사용하고, 사용자 지정 API에는 GenericViewSet 또는 ViewSet을 사용하십시오.
• RESTful 원칙을 따르십시오: RESTful 원칙에 따라 API 엔드포인트를 설계하십시오. 표준 HTTP 메서드(GET, POST, PUT, PATCH, DELETE)를 사용하여 리소스에 대한 작업을 수행하십시오.
• 데이터 유효성 검사에 직렬화 프로그램을 사용하십시오: API로 보내고 API에서 받는 데이터를 유효성 검사하는 데 직렬화 프로그램을 사용하십시오. 이렇게 하면 데이터 무결성을 보장하고 오류를 방지하는 데 도움이 됩니다.
• 적절한 인증 및 권한을 구현하십시오: 적절한 인증 및 권한을 구현하여 API 엔드포인트를 보호하십시오. 이렇게 하면 무단 액세스로부터 데이터를 보호하는 데 도움이 됩니다.
• 포괄적인 테스트를 작성하십시오: ViewSet이 올바르게 작동하는지 확인하기 위해 포괄적인 테스트를 작성하십시오. 이렇게 하면 회귀를 방지하고 코드를 더 쉽게 유지 관리할 수 있습니다.

국제화(i18n) 및 현지화(l10n) 고려 사항

글로벌 대상을 위한 API를 구축할 때 국제화(i18n) 및 현지화(l10n)를 고려하는 것이 필수적입니다. ViewSet은 여러 언어와 지역을 지원하도록 조정할 수 있습니다.

• 직렬화 프로그램 필드: 번역된 필드 레이블과 도움말 텍스트를 표시하기 위해 적절한 번역 기능(예: Django의 i18n 프레임워크의 gettext)이 있는 DRF의 직렬화 프로그램 필드를 사용하십시오.
• 오류 메시지: API에서 반환된 오류 메시지가 사용자의 선호하는 언어로 번역되었는지 확인하십시오.
• 날짜 및 시간 형식: 사용자의 로케일을 기반으로 적절한 날짜 및 시간 형식을 사용하십시오. DRF는 날짜 및 시간 형식을 사용자 정의하기 위한 옵션을 제공합니다.
• 통화 형식: 사용자의 로케일에 따라 통화 값을 형식화하십시오. 통화 형식 지정을 위해 babel과 같은 라이브러리를 사용하는 것을 고려하십시오. 예를 들어 USD의 1234.56 가격은 미국에서는 $1,234.56으로 형식이 지정될 수 있지만 일부 유럽 국가에서는 1.234,56 $로 형식이 지정될 수 있습니다.
• 시간대: 시간대를 올바르게 처리하십시오. 날짜와 시간을 UTC로 저장하고 표시할 때 사용자의 현지 시간대로 변환하십시오.

예를 들어 제품에는 번역해야 하는 설명이 있을 수 있습니다. 직렬화 프로그램 내에서 Django의 번역 시스템을 사용합니다.

            # serializers.py
from rest_framework import serializers
from django.utils.translation import gettext_lazy as _
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
    description = serializers.CharField(help_text=_("Product description"))

    class Meta:
        model = Product
        fields = '__all__'

            

              
                Copy
              
            
          

그리고 이 직렬화 프로그램을 사용하는 템플릿 또는 코드에서 적절한 언어가 활성화되었는지 확인하십시오.

예제: 국제 지원이 있는 전자 상거래 API

전 세계적으로 제품을 판매하는 전자 상거래 API를 상상해보십시오. Product 모델에는 name, description, price 및 image와 같은 필드가 포함될 수 있습니다. API는 여러 언어와 통화를 지원해야 합니다.

ViewSet은 제품에 대한 기본 CRUD 작업을 처리합니다. 직렬화 프로그램은 제품 이름과 설명의 번역을 지원하도록 사용자 정의됩니다. API에는 카테고리별로 제품을 검색하고, 가격 범위별로 제품을 필터링하고, 키워드로 제품을 검색하기 위한 엔드포인트도 포함됩니다. 이러한 기능은 국제화, 특히 언어 간에 다를 수 있는 검색어 및 제품 설명과 관련하여 고려해야 합니다.

예제 URL:

• /en/products/ - 영어로 된 제품 목록
• /fr/products/ - 프랑스어로 된 제품 목록
• /en/products/?currency=USD - USD로 된 제품 목록
• /fr/products/123/?currency=EUR - 프랑스어로 된 제품 123의 세부 정보, EUR로 표시된 가격

결론

Django REST Framework ViewSets는 API 엔드포인트를 구성하는 강력하고 우아한 방법을 제공합니다. 관련 보기를 단일 클래스에 캡슐화함으로써 ViewSets는 코드 재사용을 촉진하고 라우팅을 단순화하며 코드 가독성을 향상시킵니다. 메서드 재정의, 사용자 지정 작업 추가 및 사용자 지정 직렬화 프로그램 사용을 통해 ViewSet을 사용자 정의할 수 있는 기능을 통해 API의 특정 요구 사항을 충족하도록 조정할 수 있습니다. 이 가이드에 설명된 모범 사례를 따르면 ViewSet이 잘 설계되고 유지 관리 가능하며 확장 가능하도록 하여 강력하고 효율적인 API를 만들 수 있습니다.

글로벌 대상을 위한 API를 구축할 때 국제화 및 현지화를 고려하는 것을 잊지 마십시오. 여러 언어, 통화 및 시간대를 지원하도록 ViewSet 및 직렬화 프로그램을 조정하여 전 세계 사용자에게 원활한 경험을 제공하십시오.

ViewSet을 마스터하면 Django REST Framework 기술을 한 단계 끌어올리고 강력하고 유지 관리 가능한 API를 구축할 수 있습니다. 이는 고품질 소프트웨어와 글로벌 고객에게 긍정적인 사용자 경험에 기여합니다.

이 가이드는 Django REST Framework 프로젝트에서 ViewSet을 이해하고 구현하기 위한 견고한 기반 역할을 해야 합니다. 진정한 ViewSet 마스터가 되기 위해 계속 연습하고 실험하고 DRF 설명서를 탐색하십시오!