Guia de implementação de upload de arquivos Django | FileField · Validação · Suporte a S3

Django possui um ecossistema robusto para upload de arquivos, incluindo <code>FileField</code> e <code>ImageField</code>, validação baseada em formulários e integração com S3 via <code>django-storages</code>. Este artigo explica sistematicamente a implementação de upload de arquivos em nível profissional, desde a definição de campos em <code>models.py</code>, validação em <code>forms.py</code>, configuração de <code>MEDIA_ROOT</code>/<code>MEDIA_URL</code> em <code>settings.py</code>, até o armazenamento em AWS S3 usando <code>django-storages</code>.

Definição de FileField e ImageField

<code>FileField</code> funciona com qualquer arquivo, enquanto <code>ImageField</code> é apenas para imagens (requer Pillow). Em ambos os casos, o banco de dados armazena o caminho do arquivo (string) e não o arquivo real, e os arquivos reais são armazenados em <code>MEDIA_ROOT</code>.

# models.py
from django.db import models


def upload_to_documents(instance, filename):
    """ユーザーIDごとにサブディレクトリを作成するアップロードパス関数"""
    return f'documents/{instance.user.id}/{filename}'


class UserProfile(models.Model):
    user = models.OneToOneField('auth.User', on_delete=models.CASCADE)

    # 画像フィールド（Pillowが必要: pip install Pillow）
    avatar = models.ImageField(
        upload_to='avatars/',   # MEDIA_ROOT/avatars/ 以下に保存
        blank=True,
        null=True,
        verbose_name='プロフィール画像',
    )

    def __str__(self):
        return str(self.user)


class Document(models.Model):
    title = models.CharField(max_length=255)
    file = models.FileField(
        upload_to=upload_to_documents,  # 関数でパスを動的に決定
        verbose_name='添付ファイル',
    )
    uploaded_at = models.DateTimeField(auto_now_add=True)
    file_size = models.PositiveIntegerField(default=0)
    mime_type = models.CharField(max_length=100, blank=True)

    class Meta:
        ordering = ['-uploaded_at']

    def save(self, *args, **kwargs):
        # 保存時にファイルサイズを記録
        if self.file:
            self.file_size = self.file.size
        super().save(*args, **kwargs)

    def delete(self, *args, **kwargs):
        # レコード削除時に実ファイルも削除
        storage = self.file.storage
        path = self.file.name
        super().delete(*args, **kwargs)
        storage.delete(path)

Implementação de validação em forms.py

Ao usar formulários Django, você pode validar o tipo MIME, tamanho, extensão e outros atributos do arquivo usando o método <code>clean_nome_do_campo()</code>. Também é possível adicionar validadores customizados aos campos do modelo.

# forms.py
from django import forms
from django.core.exceptions import ValidationError
from .models import Document

# 許可するMIMEタイプの定義
ALLOWED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']
ALLOWED_DOC_TYPES = ['application/pdf', 'application/msword',
                     'application/vnd.openxmlformats-officedocument.wordprocessingml.document']

MAX_UPLOAD_SIZE = 10 * 1024 * 1024  # 10MB


class AvatarUploadForm(forms.Form):
    avatar = forms.ImageField(
        label='プロフィール画像',
        help_text='JPEG・PNG・GIF・WebP、最大5MB',
    )

    def clean_avatar(self):
        image = self.cleaned_data.get('avatar')
        if not image:
            return image

        # ファイルサイズの検証
        max_size = 5 * 1024 * 1024  # 5MB
        if image.size > max_size:
            raise ValidationError(
                f'ファイルサイズは5MB以下にしてください（現在: {image.size // 1024 // 1024}MB）'
            )

        # MIMEタイプの検証（content_type はクライアント申告値なので補助的に使用）
        if image.content_type not in ALLOWED_IMAGE_TYPES:
            raise ValidationError(
                f'許可されていないファイル形式です（{image.content_type}）。'
                'JPEG・PNG・GIF・WebP のみ使用できます。'
            )

        return image


class DocumentUploadForm(forms.ModelForm):
    class Meta:
        model = Document
        fields = ['title', 'file']

    def clean_file(self):
        file = self.cleaned_data.get('file')
        if not file:
            return file

        # ファイルサイズ検証
        if file.size > MAX_UPLOAD_SIZE:
            raise ValidationError(
                f'ファイルサイズは{MAX_UPLOAD_SIZE // 1024 // 1024}MB以下にしてください。'
            )

        # MIMEタイプ検証
        if file.content_type not in ALLOWED_DOC_TYPES:
            raise ValidationError('PDF または Word ファイルのみアップロードできます。')

        # 拡張子の検証
        ext = file.name.rsplit('.', 1)[-1].lower()
        if ext not in ['pdf', 'doc', 'docx']:
            raise ValidationError('ファイルの拡張子が不正です。')

        return file

Processamento de upload em views.py

No Django, os arquivos de formulários multipart são recuperados de <code>request.FILES</code>. A validação é executada simplesmente passando <code>request.FILES</code> para a classe do formulário.

# views.py
from django.shortcuts import render, redirect
from django.contrib import messages
from django.views import View
from .forms import DocumentUploadForm


class DocumentUploadView(View):
    template_name = 'documents/upload.html'

    def get(self, request):
        form = DocumentUploadForm()
        return render(request, self.template_name, {'form': form})

    def post(self, request):
        # request.POST と request.FILES の両方を渡す
        form = DocumentUploadForm(request.POST, request.FILES)

        if form.is_valid():
            document = form.save(commit=False)
            document.user = request.user  # ログインユーザーを設定
            document.save()
            messages.success(request, 'ファイルをアップロードしました。')
            return redirect('documents:list')

        return render(request, self.template_name, {'form': form})


# REST API（Django REST Framework）の場合
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.parsers import MultiPartParser, FormParser
from rest_framework import status


class DocumentUploadAPIView(APIView):
    parser_classes = [MultiPartParser, FormParser]

    def post(self, request):
        file = request.FILES.get('file')
        if not file:
            return Response({'error': 'ファイルが見つかりません。'}, status=status.HTTP_400_BAD_REQUEST)

        # バリデーション
        if file.size > 10 * 1024 * 1024:
            return Response({'error': 'ファイルが大きすぎます（上限10MB）。'}, status=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE)

        # 保存処理（forms.py のロジックを再利用することを推奨）
        from django.core.files.storage import default_storage
        path = default_storage.save(f'uploads/{file.name}', file)

        return Response({'path': path, 'url': default_storage.url(path)})

Configuração de MEDIA_ROOT e MEDIA_URL em settings.py

Para servir arquivos de mídia no ambiente de desenvolvimento, defina <code>MEDIA_ROOT</code> (diretório de destino de salvamento) e <code>MEDIA_URL</code> (prefixo da URL), e adicione a distribuição de arquivo estático em <code>urls.py</code>.

# settings.py
import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

# メディアファイルの保存先（開発環境）
MEDIA_ROOT = BASE_DIR / 'media'

# メディアファイルの URL プレフィックス
MEDIA_URL = '/media/'

# ファイルアップロードのデフォルト設定
# 2.5MB 以下はメモリ上で処理、それ以上は一時ファイルに書き込む
FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440  # 2.5MB

# Django が受け付けるリクエストボディの上限
DATA_UPLOAD_MAX_MEMORY_SIZE = 10 * 1024 * 1024  # 10MB

# アップロードハンドラーのカスタマイズ（デフォルト）
FILE_UPLOAD_HANDLERS = [
    'django.core.files.uploadhandler.MemoryFileUploadHandler',
    'django.core.files.uploadhandler.TemporaryFileUploadHandler',
]

# urls.py（開発環境でのメディアファイル配信）
from django.conf import settings
from django.conf.urls.static import static
from django.urls import path, include

urlpatterns = [
    # ... アプリの URL
]

# 開発環境のみメディアファイルを Django で配信
if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Configuração de S3 usando django-storages

Com <code>django-storages</code> e <code>boto3</code>, você pode alternar o destino de armazenamento de arquivos de mídia para S3 adicionando apenas algumas linhas ao <code>settings.py</code>.

pip install django-storages[s3] boto3

# settings.py（S3 設定）
import os

INSTALLED_APPS = [
    # ...
    'storages',
]

# S3 バックエンドを使用
DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'

# 静的ファイルも S3 に配置する場合
# STATICFILES_STORAGE = 'storages.backends.s3boto3.S3StaticStorage'

AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID')
AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY')
AWS_STORAGE_BUCKET_NAME = os.environ.get('AWS_STORAGE_BUCKET_NAME')
AWS_S3_REGION_NAME = os.environ.get('AWS_S3_REGION_NAME', 'ap-northeast-1')

# S3 の URL 設定
AWS_S3_CUSTOM_DOMAIN = f'{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com'
MEDIA_URL = f'https://{AWS_S3_CUSTOM_DOMAIN}/media/'

# CloudFront を使う場合
# AWS_S3_CUSTOM_DOMAIN = 'xxxxxxxx.cloudfront.net'

# ファイルの公開設定（デフォルトは private）
AWS_DEFAULT_ACL = 'private'
AWS_S3_OBJECT_PARAMETERS = {
    'CacheControl': 'max-age=86400',  # 1日キャッシュ
}

# アップロードファイルのプレフィックス
AWS_LOCATION = 'media'

# 署名付きURL の有効期間（秒）
AWS_QUERYSTRING_EXPIRE = 3600  # 1時間

# HTTPS を強制
AWS_S3_USE_SSL = True

Validador personalizado para limite de tamanho de arquivo

Especificando <code>validators</code> no campo do modelo, a validação é aplicada tanto no formulário quanto no modelo.

# validators.py
from django.core.exceptions import ValidationError


def validate_file_size(value, max_mb=10):
    """ファイルサイズを検証するバリデーター"""
    max_bytes = max_mb * 1024 * 1024
    if value.size > max_bytes:
        raise ValidationError(
            f'ファイルサイズは {max_mb}MB 以下にしてください。'
            f'（現在: {value.size / 1024 / 1024:.1f}MB）'
        )


def validate_file_extension(value, allowed_extensions=None):
    """ファイル拡張子を検証するバリデーター"""
    if allowed_extensions is None:
        allowed_extensions = ['jpg', 'jpeg', 'png', 'gif', 'pdf']

    ext = value.name.rsplit('.', 1)[-1].lower()
    if ext not in allowed_extensions:
        raise ValidationError(
            f'許可されていない拡張子です（.{ext}）。'
            f'使用可能: {", ".join(allowed_extensions)}'
        )


# models.py での使用例
from django.db import models
from .validators import validate_file_size, validate_file_extension


class Attachment(models.Model):
    file = models.FileField(
        upload_to='attachments/',
        validators=[
            validate_file_size,
            lambda v: validate_file_extension(v, ['pdf', 'docx', 'xlsx']),
        ],
    )