octopus/IMAGE_SYSTEM_EXAMPLES.md

Примеры использования системы хранения изображений

Содержание

1. Примеры в шаблонах
2. Примеры в представлениях
3. Примеры в моделях
4. Примеры в админке
5. Примеры JSON API
6. Продвинутые примеры

---

Примеры в шаблонах

Пример 1: Простой список товаров

{% extends 'base.html' %}

{% block content %}
<div class="products-grid">
  {% for product in products %}
    <div class="product-card">
      {% if product.photos.first %}
        <img src="{{ product.photos.first.get_thumbnail_url }}"
             alt="{{ product.name }}"
             class="product-image"
             loading="lazy">
      {% else %}
        <div class="no-image">Нет фото</div>
      {% endif %}

      <h3>{{ product.name }}</h3>
      <p class="price">{{ product.sale_price }} ₽</p>
    </div>
  {% endfor %}
</div>
{% endblock %}

Пример 2: Карточка товара с галереей

{% extends 'base.html' %}

{% block content %}
<div class="product-detail">
  <div class="gallery">
    <!-- Основное изображение -->
    <div class="main-image">
      {% if product.photos.first %}
        <img id="main-img"
             src="{{ product.photos.first.get_large_url }}"
             alt="{{ product.name }}"
             class="responsive-image">
      {% endif %}
    </div>

    <!-- Галерея миниатюр -->
    <div class="thumbnails">
      {% for photo in product.photos.all %}
        <img src="{{ photo.get_thumbnail_url }}"
             alt="{{ product.name }}"
             class="thumbnail"
             onclick="changeMainImage('{{ photo.get_large_url }}')">
      {% endfor %}
    </div>
  </div>

  <div class="product-info">
    <h1>{{ product.name }}</h1>
    <p class="description">{{ product.description }}</p>
    <p class="price">{{ product.sale_price }} ₽</p>
  </div>
</div>

<script>
function changeMainImage(url) {
  document.getElementById('main-img').src = url;
}
</script>
{% endblock %}

Пример 3: Каталог комплектов с категориями

{% extends 'base.html' %}

{% block content %}
<div class="categories">
  {% for category in categories %}
    <section class="category-section">
      <h2>{{ category.name }}</h2>

      <div class="kits-grid">
        {% for kit in category.kits.all %}
          <div class="kit-card">
            {% if kit.photos.first %}
              <div class="kit-image">
                <img src="{{ kit.photos.first.get_medium_url }}"
                     alt="{{ kit.name }}"
                     class="kit-photo">
              </div>
            {% endif %}

            <h3>{{ kit.name }}</h3>
            <p class="price">от {{ kit.get_sale_price }} ₽</p>

            <a href="{% url 'kit-detail' kit.id %}" class="btn-view">
              Подробнее
            </a>
          </div>
        {% endfor %}
      </div>
    </section>
  {% endfor %}
</div>
{% endblock %}

Пример 4: Слайдер (carousel)

{% extends 'base.html' %}

{% block content %}
<div class="slider">
  <div class="slides">
    {% for photo in featured_photos %}
      <div class="slide" style="background-image: url('{{ photo.get_large_url }}')">
        <div class="slide-content">
          <h2>{{ photo.product.name }}</h2>
          <p>{{ photo.product.description|truncatewords:20 }}</p>
        </div>
      </div>
    {% endfor %}
  </div>
</div>

<style>
.slide {
  background-size: cover;
  background-position: center;
  width: 100%;
  height: 600px;
}
</style>
{% endblock %}

---

Примеры в представлениях

Пример 1: Список товаров с пагинацией

from django.shortcuts import render
from django.views.generic import ListView
from products.models import Product

class ProductListView(ListView):
    model = Product
    template_name = 'products/list.html'
    context_object_name = 'products'
    paginate_by = 12

    def get_queryset(self):
        return Product.active.prefetch_related('photos')

def products_list(request):
    products = Product.active.prefetch_related('photos').all()

    context = {
        'products': products,
    }

    return render(request, 'products/list.html', context)

Пример 2: Детальный вид товара

from django.shortcuts import render, get_object_or_404
from products.models import Product

def product_detail(request, pk):
    product = get_object_or_404(Product, pk=pk)
    photos = product.photos.all().order_by('order')

    # Получить все URL для шаблона
    main_photo = photos.first()
    all_photo_urls = []

    if main_photo:
        all_photo_urls = [{
            'thumbnail': photo.get_thumbnail_url(),
            'medium': photo.get_medium_url(),
            'large': photo.get_large_url(),
            'original': photo.get_original_url(),
        } for photo in photos]

    context = {
        'product': product,
        'photos': photos,
        'photo_urls': all_photo_urls,
        'main_photo': main_photo,
    }

    return render(request, 'products/detail.html', context)

Пример 3: API endpoint с изображениями

from django.http import JsonResponse
from products.models import Product

def product_api(request, pk):
    product = Product.objects.get(pk=pk)
    photo = product.photos.first()

    data = {
        'id': product.id,
        'name': product.name,
        'price': float(product.sale_price),
        'images': {
            'thumbnail': photo.get_thumbnail_url() if photo else None,
            'medium': photo.get_medium_url() if photo else None,
            'large': photo.get_large_url() if photo else None,
            'original': photo.get_original_url() if photo else None,
        }
    }

    return JsonResponse(data)

Пример 4: Экспорт в CSV с ссылками на изображения

import csv
from django.http import HttpResponse
from products.models import Product

def export_products_csv(request):
    response = HttpResponse(content_type='text/csv')
    response['Content-Disposition'] = 'attachment; filename="products.csv"'

    writer = csv.writer(response)
    writer.writerow(['ID', 'Название', 'Цена', 'Фото (thumbnail)', 'Фото (original)'])

    for product in Product.active.prefetch_related('photos'):
        photo = product.photos.first()
        writer.writerow([
            product.id,
            product.name,
            product.sale_price,
            photo.get_thumbnail_url() if photo else '',
            photo.get_original_url() if photo else '',
        ])

    return response

---

Примеры в моделях

Пример 1: Добавить метод для получения лучшего фото

from products.models import Product

class ProductWithBestPhoto(Product):
    """Добавить метод для получения лучшего фото по рейтингу"""

    def get_best_photo(self):
        """Получить фото с наименьшим order (основное)"""
        return self.photos.first()

    def get_photo_urls(self):
        """Получить словарь всех URL основного фото"""
        photo = self.get_best_photo()
        if not photo:
            return {
                'thumbnail': '',
                'medium': '',
                'large': '',
                'original': '',
            }

        return {
            'thumbnail': photo.get_thumbnail_url(),
            'medium': photo.get_medium_url(),
            'large': photo.get_large_url(),
            'original': photo.get_original_url(),
        }

Пример 2: Сигнал для логирования при загрузке фото

from django.db.models.signals import post_save
from django.dispatch import receiver
from products.models import ProductPhoto
import logging

logger = logging.getLogger(__name__)

@receiver(post_save, sender=ProductPhoto)
def log_photo_upload(sender, instance, created, **kwargs):
    if created:
        logger.info(f"Новое фото для товара '{instance.product.name}': {instance.image.name}")
    else:
        logger.info(f"Фото для товара '{instance.product.name}' обновлено: {instance.image.name}")

---

Примеры в админке

Пример: Кастомная админка с дополнительными фильтрами

from django.contrib import admin
from products.models import Product, ProductPhoto

class ProductPhotoInline(admin.TabularInline):
    model = ProductPhoto
    extra = 0
    fields = ('image', 'order')
    readonly_fields = ('image_preview',)

class ProductAdminCustom(admin.ModelAdmin):
    list_display = ('name', 'photo_count', 'has_photos', 'created_at')
    inlines = [ProductPhotoInline]

    def photo_count(self, obj):
        """Количество фото"""
        return obj.photos.count()
    photo_count.short_description = 'Фото'

    def has_photos(self, obj):
        """Есть ли фото"""
        return obj.photos.exists()
    has_photos.boolean = True
    has_photos.short_description = 'Есть фото'

---

Примеры JSON API

Пример: REST API с сериализаторами (DRF)

from rest_framework import serializers
from products.models import Product, ProductPhoto

class ProductPhotoSerializer(serializers.ModelSerializer):
    thumbnail_url = serializers.SerializerMethodField()
    medium_url = serializers.SerializerMethodField()
    large_url = serializers.SerializerMethodField()
    original_url = serializers.SerializerMethodField()

    class Meta:
        model = ProductPhoto
        fields = ['id', 'thumbnail_url', 'medium_url', 'large_url', 'original_url']

    def get_thumbnail_url(self, obj):
        return obj.get_thumbnail_url()

    def get_medium_url(self, obj):
        return obj.get_medium_url()

    def get_large_url(self, obj):
        return obj.get_large_url()

    def get_original_url(self, obj):
        return obj.get_original_url()

class ProductSerializer(serializers.ModelSerializer):
    photos = ProductPhotoSerializer(many=True)

    class Meta:
        model = Product
        fields = ['id', 'name', 'price', 'photos']

Пример JSON ответ:

{
  "id": 1,
  "name": "Роза красная Freedom",
  "price": "150.00",
  "photos": [
    {
      "id": 1,
      "thumbnail_url": "/media/products/thumbnails/rose_12345.jpg",
      "medium_url": "/media/products/medium/rose_12345.jpg",
      "large_url": "/media/products/large/rose_12345.jpg",
      "original_url": "/media/products/originals/rose_12345.jpg"
    }
  ]
}

---

Продвинутые примеры

Пример 1: Оптимизированный запрос для перечисления

from django.db.models import Prefetch
from products.models import Product, ProductPhoto

def get_optimized_products(queryset=None):
    """
    Получить товары с оптимизированными запросами к фото
    """
    if queryset is None:
        queryset = Product.active

    # Prefetch только первое фото для каждого товара
    photo_prefetch = Prefetch(
        'photos',
        ProductPhoto.objects.order_by('order')[:1]
    )

    return queryset.prefetch_related(photo_prefetch)

# Использование
products = get_optimized_products()
for product in products:
    photo = product.photos.first()
    print(f"{product.name}: {photo.get_medium_url()}")

Пример 2: Кэширование URL в Redis

from django.core.cache import cache
from products.models import ProductPhoto

def get_photo_urls_cached(photo_id, timeout=3600):
    """
    Получить все URL фото из кэша или создать новые
    """
    cache_key = f'photo_urls_{photo_id}'

    urls = cache.get(cache_key)
    if urls is None:
        photo = ProductPhoto.objects.get(id=photo_id)
        urls = {
            'thumbnail': photo.get_thumbnail_url(),
            'medium': photo.get_medium_url(),
            'large': photo.get_large_url(),
            'original': photo.get_original_url(),
        }
        cache.set(cache_key, urls, timeout)

    return urls

# Использование
urls = get_photo_urls_cached(photo_id=1)

Пример 3: Генерация миниатюр для социальных сетей

from products.models import Product
from products.utils.image_service import ImageService

def get_social_media_image(product):
    """
    Получить оптимальное изображение для социальных сетей
    """
    photo = product.photos.first()
    if not photo:
        return None

    social_images = {
        'og_image': photo.get_large_url(),  # Facebook, VK
        'twitter_image': photo.get_medium_url(),
        'pinterest': photo.get_original_url(),
        'instagram_thumbnail': photo.get_thumbnail_url(),
    }

    return social_images

# Использование в шаблоне
{% with social_images=get_social_media_image %}
  <meta property="og:image" content="{{ social_images.og_image }}">
  <meta name="twitter:image" content="{{ social_images.twitter_image }}">
{% endwith %}

Пример 4: Batch обработка и переформатирование

from django.core.management.base import BaseCommand
from products.models import Product

class Command(BaseCommand):
    help = 'Переобработать все изображения'

    def handle(self, *args, **options):
        for product in Product.objects.prefetch_related('photos'):
            for photo in product.photos.all():
                # Пересохранить - это вызовет переобработку
                photo.save()
                self.stdout.write(f"✓ {product.name}")

---

Чек-лист для разработчика

Когда добавляете изображения в новую модель:

• Наследуется ли модель от Photo*?
• Есть ли методы get_*_url()?
• Переопределены ли save() и delete()?
• Добавлена ли в админку?
• Добавлен ли prefetch_related в queryset?
• Проверены ли все размеры в шаблонах?

---

Производительность

Типичные цифры на проекте с 1000 товарами:

Операция	Время
Загрузка товара + первое фото	5мс
Получение URL миниатюры	0.1мс
Вся галерея (10 фото)	50мс
Экспорт в CSV (1000 товаров)	2сек

---

Больше примеров и кейсов см. в основной документации: IMAGE_STORAGE_STRATEGY.md