Реализация загрузки файлов: валидация, прогресс-бар, безопасность

Вы запустили MVP за месяц, а на первом же клиентском файле в 200 МБ сервер лёг — тайм-аут, 502, пользователь в гневе. Знакомо? Проблема не в железе, а в отсутствии правильной реализации загрузки файлов: без chunked upload, без валидации на клиенте и сервере, без прогресс-бара. Мы настраивали такие кейсы десятки раз, и каждый раз сталкивались с одними и теми же граблями. В этой статье расскажем, как сделать upload правильно — с валидацией, прогрессом, безопасностью и поддержкой больших файлов.

Какие проблемы решаем?

Неожиданный тайм-аут при загрузке. Файл 200 МБ, Nginx настроен на 30 секунд — сервер убивает соединение, пользователь перезагружает страницу. Решение — chunked upload (разбивка на части) или настройка client_max_body_size и fastcgi_read_timeout, но это паллиатив. Chunked upload работает всегда.

Валидация только на клиенте. Любой школьник отправит POST с curl и загрузит .exe вместо .jpg. На сервере проверяем MIME через finfo, не доверяя заголовку. Ограничиваем размер, количество файлов, проверяем сигнатуру.

Потеря прогресса. Пользователь не видит, сколько ещё ждать, и закрывает вкладку. Добавляем прогресс-бар через onUploadProgress (Axios) или XMLHttpRequest. Для chunked — показываем части. Экономия на доработках и снижение количества тикетов в поддержку — вот что даёт правильная загрузка файлов.

Как мы это делаем: стек и реализация

Используем Laravel 11 (PHP 8.3) + S3 (MinIO или AWS) + React 18 (TypeScript). Для больших файлов — multipart upload через S3 SDK. Ниже — код, который работает в продакшене.

Сервер: Laravel

class FileUploadController extends Controller
{
    public function store(Request $request): JsonResponse
    {
        $request->validate([
            'file' => [
                'required',
                'file',
                'max:51200', // 50 MB в КБ
                'mimes:jpg,jpeg,png,gif,webp,pdf,docx,xlsx,zip',
            ],
        ]);

        $file = $request->file('file');

        // Генерируем безопасное имя — оригинальное имя не используем
        $filename = Str::uuid() . '.' . $file->getClientOriginalExtension();
        $path = 'uploads/' . auth()->id() . '/' . date('Y/m') . '/' . $filename;

        // Загрузка в S3
        Storage::disk('s3')->putFileAs(
            dirname($path),
            $file,
            basename($path),
            ['visibility' => 'private']
        );

        $upload = Upload::create([
            'user_id' => auth()->id(),
            'path' => $path,
            'original_name' => $file->getClientOriginalName(),
            'mime_type' => $file->getMimeType(),
            'size' => $file->getSize(),
        ]);

        return response()->json(['id' => $upload->id, 'path' => $path], 201);
    }
}

Клиент: React с прогресс-баром

function FileUploader() {
  const [progress, setProgress] = useState(0);
  const [uploading, setUploading] = useState(false);

  async function handleUpload(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0];
    if (!file) return;

    const formData = new FormData();
    formData.append('file', file);

    setUploading(true);
    try {
      await axios.post('/api/upload', formData, {
        headers: { 'Content-Type': 'multipart/form-data' },
        onUploadProgress: (e) => {
          setProgress(Math.round((e.loaded / (e.total ?? 1)) * 100));
        },
      });
    } finally {
      setUploading(false);
    }
  }

  return (
    <div>
      <input type="file" onChange={handleUpload} disabled={uploading} />
      {uploading && <progress value={progress} max={100}>{progress}%</progress>}
    </div>
  );
}

Chunked Upload для больших файлов

Файлы >100 MB загружают по частям через S3 Multipart Upload:

// Инициализация
public function initChunked(Request $request): JsonResponse
{
    $s3 = Storage::disk('s3')->getClient();
    $result = $s3->createMultipartUpload([
        'Bucket' => config('filesystems.disks.s3.bucket'),
        'Key' => 'uploads/' . Str::uuid() . '.' . $request->extension,
    ]);
    return response()->json(['upload_id' => $result['UploadId'], 'key' => $result['Key']]);
}

// Загрузка части
public function uploadPart(Request $request): JsonResponse
{
    $s3 = Storage::disk('s3')->getClient();
    $result = $s3->uploadPart([
        'Bucket' => config('filesystems.disks.s3.bucket'),
        'Key' => $request->key,
        'UploadId' => $request->upload_id,
        'PartNumber' => $request->part_number,
        'Body' => $request->getContent(),
    ]);
    return response()->json(['etag' => $result['ETag']]);
}

Сравнение подходов: обычный upload vs chunked

Дополнительно: chunked upload снижает количество тайм-аутов на 80% по нашим данным, что критично для пользовательского опыта. Стоимость внедрения окупается за счёт снижения нагрузки на поддержку.

Почему стоит выбрать chunked upload?

Разберём два подхода: обычный upload vs chunked. Обычный проще в реализации, но на файлах > 100 МБ даёт большое количество тайм-аутов (80% случаев по нашим данным). Chunked upload решает проблему, но требует настройки S3 и дополнительных эндпоинтов. Мы используем второй вариант для всех проектов, где планируется загрузка больших файлов. Это оправдано: пользователь не теряет данные, не перезагружает страницу, а прогресс загрузки держит его в курсе.

Как избежать типовых ошибок?

Чек-лист: что проверить перед деплоем:

• Забыли про Nginx limit. client_max_body_size должен быть больше, чем ваш max. Иначе 413.
• Оригинальное имя файла. Никогда не сохраняйте как есть — используйте UUID.
• Только одна проверка. Валидация на клиенте + сервере обязательна.
• Не настроена очистка. Если пользователь начал загрузку, но не закончил, файлы висят в S3. Cron-задача раз в день удаляет "зависшие" части.

Этапы работы и ориентировочные сроки

Всего: 3–5 дней в зависимости от сложности.

Что входит в работу

• Документация по API эндпоинтам и форматам запросов.
• Доступы к S3-хранилищу и дашборду для мониторинга.
• Обучение команды работе с новой функциональностью.
• Поддержка после запуска — исправление багов и оптимизация в течение месяца.

Процесс работы

1. Аналитика. Определяем типы файлов, максимальный размер, локацию хранения.
2. Проектирование. Решаем, нужен ли chunked, где хранить (S3/MinIO/локально).
3. Реализация. Пишем контроллеры, валидацию, клиентский код с прогресс-баром.
4. Тестирование. Загружаем файлы разных размеров, проверяем ошибки, тайм-ауты, безопасность.
5. Деплой. Настраиваем S3, CI/CD, мониторинг.

Сроки и стоимость

Загрузка файлов с валидацией в S3 для Laravel/Node.js: 1–2 дня. Chunked upload + прогресс-бар: 2–3 дня. Стоимость рассчитывается индивидуально — напишите нам, и мы оценим ваш проект. Работаем по договору с гарантией качества — 5+ лет опыта, более 30 проектов с загрузкой файлов.

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