Вьюсеты в Django. Расширенные возможности

Бытует мнение, что у котиков с доминирующим белым окрасом голубой цвет глаз более глубокий, чем у остальных, и это считается достоинством. Вот именно они и представляют интерес для наших пользователей.

В связи с повышенным спросом на белых котиков требуется расширить возможности API: по специальному запросу нужно отдавать информацию о пяти последних добавленных котиках белого цвета. Для таких запросов уже придумали эндпоинт: cats/recent-white-cats/.

Задача не выглядит типичной: можно получить данные о всех котиках или о каком-то одном, но не о пяти, да ещё и определённого цвета.

Нестандартные действия во вьюсетах

Ещё раз переберём список стандартных действий (англ. actions) во вьюсетах:

  • create: создание экземпляра;
  • retrieve: получение экземпляра;
  • list: получение списка экземпляров;
  • update: обновление экземпляра (все поля);
  • partial_update: обновление экземпляра (только выбранные поля);
  • destroy: удаление экземпляра.

Для поставленной задачи ни один из них не подойдёт.Необходимо нестандартное действие; для этого во вьюсете пишут отдельные методы, которые оборачивают в декоратор @action («действие»). Этот декоратор настраивает метод и создаёт эндпоинты для этих действий.

Имя такого метода-«действия» может быть произвольным.Декоратор @action по умолчанию отслеживает только GET-запрос. Но если передать в декоратор параметр methods, то можно разрешить и другие методы запросов.

@action(methods=['get', 'delete', ...] 

В декораторе можно явным образом указать, должен ли метод работать с одним объектом или с коллекцией объектов. Для этого используется параметр detail, который может принимать значения True (разрешена работа с одним объектом) или False (работаем с коллекцией).

URL эндпоинта по умолчанию генерируется из двух частей: <URL-префикс ресурса>/<название метода>/.

# К такому методу можно обратиться через эндпоинт cats/cats_for_sale/
@action()
def cats_for_sale()
    ... 

Если URL эндпоинта не должен совпадать с именем метода, URL можно изменить: для этого нужно передать в декоратор аргумент url_path с необходимым значением.

Решим задачу с получением последних пяти белых котиков. Для этого опишем метод recent_white_cats для вьюсета CatViewSet.

from rest_framework.decorators import action
from rest_framework.response import Response

...

class CatViewSet(viewsets.ModelViewSet):
    queryset = Cat.objects.all()
    serializer_class = CatSerializer

    # Пишем метод, а в декораторе разрешим работу со списком объектов
    # и переопределим URL на более презентабельный
    @action(detail=False, url_path='recent-white-cats')
    def recent_white_cats(self, request):
        # Нужны только последние пять котиков белого цвета
        cats = Cat.objects.filter(color='White')[:5]
        # Передадим queryset cats сериализатору 
        # и разрешим работу со списком объектов
        serializer = self.get_serializer(cats, many=True)
        return Response(serializer.data) 

Готово, проверяем.

При отправке GET-запроса на эндпоинт cats/recent-white-cats/ должен быть получен примерно такой результат (конечно, если у вас в базе есть достаточно белых котиков):

Различные сериализаторы для одного вьюсета

В Kittygram для сериализации и десериализации каждой модели использовался лишь один сериализатор. Но если некоторые поля сериализатора доступны только для чтения, то по факту для чтения применяется один набор полей, а для записи — другой. Это равносильно использованию разных сериализаторов.

Да, так тоже можно: для модели можно описать несколько сериализаторов и использовать их, например, в зависимости от типа запроса.Допустим, когда

  • добавляется новый котик,
  • запрашивается детальная информация о конкретном котике,
  • обновляется информация о конкретном котике,

будем обрабатывать все доступные поля модели, а вот если запрашивается список котиков, то необходимы только id, имя и цвет.

Опишем для этого ещё один сериализатор, который назовём CatListSerializer:

class CatListSerializer(serializers.ModelSerializer):
    color = serializers.ChoiceField(choices=CHOICES)
    
    class Meta:
        model = Cat
        fields = ('id', 'name', 'color') 

Добавьте во вьюсет стандартный метод get_serializer_class: в нём можно определить, какой из доступных сериализаторов должен обрабатывать данные в зависимости от действия:

class CatViewSet(viewsets.ModelViewSet):
    queryset = Cat.objects.all()
    serializer_class = CatSerializer

    ...
    
    def get_serializer_class(self):
        # Если запрошенное действие (action) — получение списка объектов ('list')
        if self.action == 'list':
            # ...то применяем CatListSerializer
            return CatListSerializer
        # А если запрошенное действие — не 'list', применяем CatSerializer
        return CatSerializer 

Проверим результаты, отправив GET-запрос на получение списка всех котиков.

По ответу видно, что отработал новый сериализатор: всё по плану. А при запросе к конкретному котику всё работает как и раньше:

Нестандартный набор стандартных действий

Чаще всего мы наследовали вьюсеты от ModelViewSet. По умолчанию это даёт возможность обрабатывать шесть типичных действий:

  • создание нового объекта;
  • получение информации об одном объекте;
  • удаление объекта;
  • полное замещение существующего объекта;
  • изменение одного или нескольких полей объекта;
  • получение списка объектов.

Если требуется только получать данные из БД, можно унаследоваться от ReadOnlyModelViewSet. В этом случае доступный набор действий будет таким:

  • получение информации об одном объекте;
  • получение списка объектов.

А если требуется иной набор действий — например, нужно только создавать новый объект и получать информацию об одном объекте? Эта задача может быть решена с использованием миксинов (от англ. mix in, «смешивать»).

Миксины и ваш собственный базовый класс для вьюсетов

Никто не знает, что придёт в голову разработчикам и какие вьюсеты им понадобятся, поэтому готовых вьюсетов на все случаи жизни нет и быть не может. Но есть классы-«детали», из которых можно быстро собрать практически любой необходимый базовый вьюсет: миксины.

Чтобы самостоятельно создать базовый вьюсет с особым набором действий — нужно унаследовать его от одного или нескольких миксинов с нужными действиями и, дополнительно, от базового класса GenericViewSet:

from rest_framework import mixins

...

# Собираем вьюсет, который будет уметь изменять или удалять отдельный объект.
# А ничего больше он уметь не будет.
class UpdateDeleteViewSet(mixins.UpdateModelMixin, mixins.DestroyModelMixin,
                          viewsets.GenericViewSet):
    pass 

В DRF есть пять предустановленных классов миксинов, они соответствуют пяти операциям с данными:

  • CreateModelMixin — создать объект (для обработки запросов POST);
  • ListModelMixin — вернуть список объектов (для обработки запросов GET);
  • RetrieveModelMixin — вернуть объект (для обработки запросов GET);
  • UpdateModelMixin — изменить объект (для обработки запросов PUT и PATCH);
  • DestroyModelMixin — удалить объект (для обработки запросов DELETE).

Опишем собственный базовый класс вьюсета: он будет создавать экземпляр объекта и получать экземпляр объекта; назовём его CreateRetrieveViewSet.

# cats/views.py
...

from rest_framework import mixins

...

class CreateRetrieveViewSet(mixins.CreateModelMixin, mixins.RetrieveModelMixin,
                            viewsets.GenericViewSet):
    # В теле класса никакой код не нужен! Пустячок, а приятно.
    pass 

Базовый вьюсет готов, он получился не хуже, чем ModelViewSet. Теперь можно унаследоваться от этого базового класса.Опишем вьюсет LightCatViewSet, унаследованный от CreateRetrieveViewSet.

class LightCatViewSet(CreateRetrieveViewSet):
    queryset = Cat.objects.all()
    serializer_class = CatSerializer 

Зарегистрируем этот вьюсет в роутере:

from cats.views import CatViewSet, LightCatViewSet, OwnerViewSet

...

router.register(r'mycats', LightCatViewSet) 

Нужно разобраться, что за странный синтаксис в первом аргументе метода register(), ведь там должен быть просто префикс для URL.

Неожиданное откровение

При регистрации эндпоинтов для вьюсета в качестве URL-префикса используется не обычная строка, а регулярное выражение. За счёт этого URL-префикс может обрабатывать множество вариантов URL.

...
# При регистрации эндпоинтов с таким URL-префиксом
router.register(r'profile/(?P<username>[\w.@+-]+)/', AnyViewSet)
# ...вьюсет AnyViewSet будет получать на обработку все запросы с адресов
# /profile/toh@/
# /profile/nik.nik/
# /profile/leo/
# ...и подобных, ограниченных маской регулярного выражения. 

В уроке о роутерах в первый параметр метода register() мы передавали просто строку, но «просто строка» — это частный случай регулярного выражения, и Django эту «просто строку» тоже интерпретировал как regExp.

Префикс r перед строкой определяет raw-строку (или r-строку, так короче). Такую строку система будет читать как простую последовательность символов, игнорируя escape-последовательности (англ. escape sequence) — комбинации обратного слеша и символа.

Например, escape-последовательность \n интерпретируется как перенос строки, но в raw-строке это будут просто два текстовых символа без всякого скрытого смысла; в результате вся r-строка будет считана как регулярное выражение.

Вернёмся к нашим миксинам

Базовый вьюсет собран, наследник описан и применён в коде.

Проверьте работу нового вьюсета: сделайте запросы на новый эндпоинт mycats/.

GET-запрос к конкретному котику отрабатывает на «отлично»:

А вот получить список котиков через этот эндпоинт нельзя:

Работает! Теперь можно монтировать базовые вьюсеты с любым набором действий.

Мой вьюсет — мои правила: наследование от класса ViewSet

В тех случаях, когда нужно получить больше контроля и возможностей что-то «подкрутить» во вьюсетах, можно наследоваться от базового класса ViewSet. Именно от него наследуется, например, класс ModelViewSet.Класс ViewSet, в свою очередь, наследуется от APIView.

При работе с низкоуровневыми вьюсетами все нужные методы вам придётся описать самостоятельно.

В классе ViewSet есть шесть предопределённых методов:

  • list(self, request) — для получения списка объектов из queryset;
  • create(self, request) — для создания объекта в модели;
  • retrieve(self, request, pk=None) — для получения определённого объекта из queryset;
  • update(self, request, pk=None) — для перезаписи (полного обновления) определённого объекта из queryset;
  • partial_update(self, request, pk=None) — для частичного обновления объекта из queryset;
  • destroy(self, request, pk=None) — для удаления одного из объектов queryset.

Чтобы применить любой из этих методов, нужно полностью описать его; в классе ViewSet эти методы объявлены, но не описаны.

Например, в приложении нужно создать вьюсет, который будет получать сериализованный объект одного котика (методом retrieve()) и полный список всех котиков (методом list()). Это можно сделать так:

from rest_framework import viewsets
from rest_framework.response import Response

from django.shortcuts import get_object_or_404

from .models import Cat
from .serializers import CatSerializer


class CatViewSet(viewsets.ViewSet):
    def list(self, request):
        queryset = Cat.objects.all()
        serializer = CatSerializer(queryset, many=True)
        return Response(serializer.data)

    def retrieve(self, request, pk=None):
        queryset = Cat.objects.all()
        cat = get_object_or_404(queryset, pk=pk)
        serializer = CatSerializer(cat)
        return Response(serializer.data) 

Похоже на то, как мы работали в APIView, с той разницей, что здесь присутствуют поля queryset и serializer.

Документацию по предустановленным методам класса ViewSet можно посмотреть на официальном сайте проекта.



Вы можете оставить комментарий, или Трекбэк с вашего сайта.

Оставить комментарий