Использование метода `to_representation()`

В процессе работы с API иногда требуется изменять формат данных перед их отправкой клиенту. Например, вы хотите:

• Упрощённо отображать связанные объекты.
• Переименовать поля или объединить данные из нескольких полей.
• Исключить или изменить некоторые данные в зависимости от условий.

Метод to_representation() — тот самый магический инструмент, который позволяет кастомизировать процесс преобразования данных объектов модели в JSON и другие форматы.

Основы метода to_representation()

Метод to_representation() отвечает за преобразование объекта модели в сериализуемые данные. Представьте, что он как добрая бабушка, которая переводит сложный язык ваших моделей в удобоваримый для клиента JSON:

class MyCustomSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = ['id', 'name', 'created_at']

    def to_representation(self, instance):
        # Преобразуем объект модели в понятный формат
        representation = super().to_representation(instance)

        # Добавим кастомное поле
        representation['formatted_date'] = instance.created_at.strftime('%d-%m-%Y')
        return representation

Здесь, после стандартного преобразования данных с помощью базового to_representation, мы добавляем новое поле formatted_date, которое содержит отформатированную дату.

Когда нужно переопределять to_representation()?

1. Меняем структуру данных

Предположим, есть модель с одним ключевым связным полем:

class Book(models.Model):
    title = models.CharField(max_length=255)
    published_date = models.DateField()
    author = models.ForeignKey("Author", on_delete=models.CASCADE)

class Author(models.Model):
    name = models.CharField(max_length=255)
    country = models.CharField(max_length=100)

Стандартный ModelSerializer легко сериализует Book, включая author, но он вернёт только id автора:

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ["title", "published_date", "author"]

Результат:

{
  "title": "Python for Humans",
  "published_date": "2023-09-21",
  "author": 1  # ID автора
}

Ваш клиент не хочет видеть ID автора, он хочет видеть имя. Используем to_representation:

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['title', 'published_date', 'author']

    def to_representation(self, instance):
        representation = super().to_representation(instance)
        # Заменяем ID автора на его имя
        representation['author'] = instance.author.name
        return representation

Результат:

{
  "title": "Python for Humans",
  "published_date": "2023-09-21",
  "author": "Guido van Rossum"
}

Теперь читаемость повысилась. Клиент доволен!

2. Условное отображение данных

Иногда важно адаптировать данные в зависимости от условий. Например, поле author_country доступно только для админов:

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['title', 'published_date', 'author']

    def to_representation(self, instance):
        representation = super().to_representation(instance)
        request = self.context.get('request')

        # Добавляем страну, если пользователь - админ
        if request and request.user.is_staff:
            representation['author_country'] = instance.author.country
        return representation

3. Работа с вложенными структурами

Для вложенных данных to_representation() позволяет более гибко контролировать, как связные объекты будут отображаться. Например, если вы хотите показать больше данных об авторе:

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['title', 'published_date', 'author']

    def to_representation(self, instance):
        representation = super().to_representation(instance)
        representation['author'] = {
            'name': instance.author.name,
            'country': instance.author.country
        }
        return representation

Результат:

{
  "title": "Python for Humans",
  "published_date": "2023-09-21",
  "author": {
    "name": "Guido van Rossum",
    "country": "Netherlands"
  }
}

Переопределение to_representation(): Best Practices

1. Используйте super().to_representation()
   Начинайте с получения стандартной сериализованной версии объекта. Это избавляет от необходимости вручную описывать каждое поле.

2. Минимизируйте логику в to_representation()
   Делайте метод простым и понятным. Если требуется сложная обработка, лучше вынесите её в отдельный метод.

3. Контекст имеет значение
   Используйте self.context, чтобы адаптировать данные в зависимости от пользователя или запроса.

4. Избегайте перегрузки данных
   Если один объект имеет много вложенных данных, подумайте о пагинации или фильтрации вместо того, чтобы запихивать в ответ всё и сразу.

Ошибки, которых следует избегать

Первая и самая частая ошибка — игнорировать базовый метод super().to_representation(). Если вы этого не сделаете, все стандартные поля, описанные в Meta: fields, исчезнут, и нужно будет вручную их сериализовать.

Кроме того, всегда нужно помнить о производительности. Слишком сложная логика в to_representation() увеличивает время обработки запроса, особенно если вы выполняете запросы к базе данных внутри метода. Например, избегайте такого:

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['title', 'published_date']

    def to_representation(self, instance):
        representation = super().to_representation(instance)
        # Плохая практика — каждый вызов делает новый запрос к базе!
        representation['author'] = {
            'name': Author.objects.get(id=instance.author_id).name
        }
        return representation

Используйте select_related или заранее предзагружайте необходимые данные.

Пример: финальная версия

Реализуем сериализацию, которая:

1. Показывает базовую информацию о книге.
2. Включает детальную информацию об авторе.
3. Условно добавляет информацию о стране, если запрос от администратора.

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['title', 'published_date', 'author']

    def to_representation(self, instance):
        representation = super().to_representation(instance)
        representation['author'] = {
            'name': instance.author.name,
            'country': instance.author.country if self.context.get('request').user.is_staff else None
        }
        return representation

Результат:

• Для обычного пользователя:

  {
    "title": "Python for Humans",
    "published_date": "2023-09-21",
    "author": {
      "name": "Guido van Rossum",
      "country": null
    }
  }
  

• Для администратора:

  {
  "title": "Python for Humans",
  "published_date": "2023-09-21",
  "author": {
    "name": "Guido van Rossum",
    "country": "Netherlands"
  }
  }
  

Метод to_representation() станет вашим лучшим другом, когда нужно адаптировать данные для клиента (и сделать их счастливыми!). Главное — не забывайте про производительность и бережное отношение к данным.