Как загрузить несколько файлов в Django REST Framework?

16.10.2025
57473

6 мин
75

Работа с файлами является частой задачей в веб-разработке. В контексте API на базе Django REST Framework (DRF) возникает потребность не только в загрузке одиночных файлов, но и в передаче и обработке нескольких файлов одновременно в одном запросе. Эта задача имеет свои особенности, требующие правильной настройки сериализаторов и представлений.

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

Сценарии, требующие одновременной загрузки нескольких файлов, разнообразны и встречаются во многих типах приложений:

Галереи изображений: Пользователи загружают набор фотографий для создания альбома или профиля.

Прикрепление документов: К одной записи (например, к заявке, заказу или комментарию) необходимо прикрепить несколько подтверждающих документов (PDF, Word, изображения).

Пакетная обработка: Загрузка нескольких файлов данных (например, CSV или Excel) для последующего анализа или импорта в систему.

3D-модели и связанные текстуры: Загрузка файла модели и нескольких файлов текстур, которые к ней относятся.

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

Обзор подходов к реализации загрузки нескольких файлов

Основной подход в Django REST Framework для приема нескольких файлов заключается в использовании стандартных механизмов обработки запросов с формой (multipart/form-data) и применении специфических полей сериализатора для работы со списками файлов. Вместо того чтобы обрабатывать каждый файл по отдельности на уровне представления (View), DRF позволяет делегировать эту задачу сериализатору, используя поле ListField, содержащее экземпляры FileField.

Такой подход централизует логику валидации и частичного сохранения данных в одном месте — сериализаторе, что соответствует принципам DRF и упрощает структуру View.

Настройка Django REST Framework для приема нескольких файлов

Для работы с файлами в Django проекте требуется минимальная настройка, большая часть которой стандартна и не специфична именно для DRF или множественной загрузки.

Установка необходимых пакетов (если требуются)

Стандартные возможности Django и Django REST Framework достаточны для реализации загрузки файлов. Дополнительные пакеты не требуются специально для этой задачи. Убедитесь, что у вас установлены:

pip install django
pip install djangorestframework

Также необходимо иметь установленный Pillow, если вы планируете работать с изображениями (например, для создания превью).

pip install Pillow

Настройка `settings.py` для обработки файлов (MEDIA_ROOT, MEDIA_URL)

Важно правильно настроить пути для хранения загруженных пользовательских файлов. В settings.py необходимо определить:

MEDIA_ROOT: Полный путь к директории, где будут храниться загруженные файлы.

MEDIA_URL: URL, по которому эти файлы будут доступны из браузера.

Пример базовой настройки:

# settings.py

import os

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# ... другие настройки ...

MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
MEDIA_URL = '/media/'

# В режиме отладки (DEBUG=True) необходимо также
# добавить маршрут для отдачи медиафайлов в urls.py основного проекта.
# Пример:
# from django.conf import settings
# from django.conf.urls.static import static
#
# urlpatterns = [
#     # ... ваши URL-маршруты ...
# ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Убедитесь, что директория, на которую указывает MEDIA_ROOT, существует и доступна для записи веб-серверу, под которым запускается ваше Django-приложение.

Реализация сериализатора для загрузки нескольких файлов

Ключевым моментом при работе с несколькими файлами в DRF является определение соответствующего сериализатора. Он будет отвечать за прием списка файлов из запроса, их валидацию и, возможно, инициацию процесса сохранения.

Создание сериализатора с полем `ListField` и `FileField`

Для приема списка файлов используется поле rest_framework.serializers.ListField. В качестве аргумента child этому полю передается тип элемента списка, в данном случае rest_framework.serializers.FileField (или ImageField, если ожидаются только изображения).

# serializers.py

from rest_framework import serializers
from django.core.files.uploadedfile import UploadedFile

class MultipleFilesUploadSerializer(serializers.Serializer):
    files = serializers.ListField(
        child=serializers.FileField(),
        min_length=1, # Опционально: требовать хотя бы один файл
        allow_empty=False # Опционально: запретить пустой список
    )

    class Meta:
        # Метакласс здесь не используется, так как это не ModelSerializer
        pass

    # Валидация на уровне сериализатора, если нужна более сложная логика
    # def validate_files(self, file_list: list[UploadedFile]):
    #     # Пример валидации: проверить размер или тип каждого файла
    #     max_size = 5 * 1024 * 1024 # 5 MB
    #     for file in file_list:
    #         if file.size > max_size:
    #             raise serializers.ValidationError(f"Файл '{file.name}' слишком большой (макс. {max_size / 1024 / 1024} MB).")
    #         # Дополнительные проверки на тип MIME, и т.д.
    #     return file_list

    def create(self, validated_data: dict) -> dict:
        # Этот метод вызывается при .save() на валидном сериализаторе
        # Здесь происходит логика сохранения файлов
        uploaded_files: list[UploadedFile] = validated_data.get('files', [])
        saved_file_info = []

        for file in uploaded_files:
            # Логика сохранения файла. 
            # Обычно это создание модели и присвоение ей файла.
            # Например, если есть модель FileEntry с полем file = FileField():
            # file_instance = FileEntry(file=file)
            # file_instance.save()
            # saved_file_info.append({'name': file.name, 'url': file_instance.file.url})

            # Пример без модели: просто работа с UploadedFile объектом
            # В реальном приложении нужно сохранять файл куда-то (например, через FileSystemStorage)
            print(f"Получен файл: {file.name}, размер: {file.size} байт, тип: {file.content_type}")
            saved_file_info.append({'name': file.name, 'size': file.size, 'content_type': file.content_type})
            
        # В реальном приложении здесь возвращается что-то более полезное,
        # например, список объектов созданных моделей или их ID.
        # Возвращаем информацию о принятых файлах для демонстрации.
        return {'status': 'success', 'files_processed': len(uploaded_files), 'details': saved_file_info}

Валидация списка файлов в сериализаторе

Базовая валидация, такая как проверка на пустой список или минимальное количество элементов, настраивается прямо в аргументах ListField (allow_empty, min_length, max_length).

Более сложная валидация, например, проверка типа, размера или содержимого каждого файла в списке, реализуется в методе validate_files (где files — имя поля ListField). Этот метод получает весь список объектов UploadedFile после первичной валидации DRF.

Сохранение загруженных файлов после валидации

Сохранение файлов обычно происходит в методе create (или update) вашего сериализатора, если вы не используете ModelSerializer. После того как serializer.is_valid(raise_exception=True) успешно выполнен, вы получаете доступ к валидированным данным, включая список объектов UploadedFile в validated_data['files']. Итерируясь по этому списку, вы можете сохранить каждый файл, например, создавая для каждого отдельную запись в базе данных через Django модели, использующие FileField.

Создание ViewSet для обработки запросов с несколькими файлами

Для обработки HTTP-запросов, содержащих несколько файлов, мы можем использовать ViewSet или APIView. Рассмотрим пример с ViewSet.

Определение `ViewSet` с методом `create`

Поскольку загрузка файлов по сути является операцией создания новых ресурсов (например, записей о файлах, или основного ресурса, к которому прикрепляются файлы), часто используется HTTP-метод POST и соответствующий ему метод create во ViewSet.

# views.py

from rest_framework.viewsets import ViewSet
from rest_framework.response import Response
from rest_framework import status
from rest_framework.parsers import MultiPartParser, FormParser # Важно для обработки файлов
from .serializers import MultipleFilesUploadSerializer

class FileUploadViewSet(ViewSet):
    # Указываем парсеры для обработки multipart/form-data запросов
    parser_classes = [MultiPartParser, FormParser]
    serializer_class = MultipleFilesUploadSerializer

    def create(self, request):
        """
        Принимает POST запрос с несколькими файлами.
        """
        # request.data содержит разобранные данные, включая файлы
        serializer = self.serializer_class(data=request.data)

        # Выполняем валидацию. raise_exception=True автоматически
        # вернет 400 Bad Request с подробностями ошибок валидации DRF.
        serializer.is_valid(raise_exception=True)

        # Логика сохранения файлов теперь находится в методе create сериализатора.
        # Сериализатор возвращает результат своей работы.
        result = serializer.save()

        # Возвращаем успешный ответ. Содержание ответа зависит
        # от того, что возвращает метод create сериализатора.
        return Response(result, status=status.HTTP_201_CREATED)

    # Если нужна отдельная точка для загрузки, можно использовать @action
    # from rest_framework.decorators import action
    # @action(detail=False, methods=['post'])
    # def upload_multiple(self, request):
    #    ...

Использование сериализатора для обработки данных запроса

В методе create (или любом другом методе, обрабатывающем POST/PUT запросы), вы создаете экземпляр вашего сериализатора MultipleFilesUploadSerializer, передавая ему request.data. request.data для multipart/form-data запросов уже корректно разобран DRF парсерами (MultiPartParser, FormParser) и содержит как обычные поля формы, так и список объектов UploadedFile для поля files.

Вызов serializer.is_valid(raise_exception=True) выполняет всю определенную в сериализаторе валидацию. Если валидация проходит успешно, метод serializer.save() вызывает create (или update) сериализатора, где и происходит основная логика сохранения файлов.

Обработка ошибок и возвращение соответствующих ответов

Благодаря raise_exception=True в serializer.is_valid(), DRF автоматически обрабатывает ошибки валидации, возвращая клиенту ответ со статусом 400 Bad Request и подробным описанием ошибок в теле ответа. В случае успешной валидации и выполнения метода save(), возвращается ответ со статусом 201 Created, содержащий данные, возвращенные методом save() сериализатора.

Тестирование API загрузки нескольких файлов

После реализации сериализатора и представления необходимо протестировать API-эндпоинт для загрузки нескольких файлов.

Использование `curl` или `Postman` для отправки запросов

Для тестирования удобно использовать инструменты командной строки, такие как curl, или графические клиенты, такие как Postman или Insomnia.

Пример запроса с использованием curl для загрузки двух файлов:

curl -X POST \
  http://127.0.0.1:8000/api/upload/ \
  -H "Content-Type: multipart/form-data" \
  -F "files=@/path/to/your/file1.jpg" \
  -F "files=@/path/to/your/document.pdf"

Обратите внимание:

-X POST указывает метод запроса.

-H "Content-Type: multipart/form-data" устанавливает правильный заголовок (хотя curl часто делает это сам при использовании -F).

-F "files=@/path/to/your/file1.jpg" отправляет файл. @ перед путем указывает curl, что нужно прочитать содержимое файла. files — это имя поля в вашем сериализаторе (files = serializers.ListField(...)). Для каждого файла указывается отдельный -F с тем же именем поля.

В Postman или аналогичных клиентах вы выбираете тип запроса POST, вкладку body, тип form-data. Для ключа files (или как вы назвали поле в сериализаторе) выбираете тип File и добавляете несколько строк с тем же ключом, выбирая разные файлы.

Проверка сохранения файлов в указанной директории

После успешного ответа от API проверьте файловую систему сервера. Файлы должны появиться в директории, указанной в settings.py как MEDIA_ROOT, возможно, внутри поддиректорий, если ваша модель или логика сохранения предусматривает это.

Обработка крайних случаев (пустой список файлов, неверный формат)

Протестируйте, как API обрабатывает следующие ситуации:

Отправка запроса без файлов (пустое поле files или его отсутствие): DRF и ваш сериализатор должны вернуть 400 Bad Request с сообщением об ошибке валидации (если вы установили min_length > 0 или allow_empty=False).

Отправка файлов неверного формата (если вы добавили такую валидацию в validate_files).

Отправка слишком больших файлов (если добавлена проверка размера).

Корректная обработка этих сценариев гарантирует надежность вашего API.

Реализация загрузки нескольких файлов в Django REST Framework сводится к правильному использованию ListField(FileField()) в сериализаторе и настройке представления на прием multipart/form-data. Этот подход является гибким и хорошо интегрируется со стандартными механизмами DRF.