Обработка загрузки файлов в Go-сервисе: рабочие приёмы

Почему ParseMultipartForm — не единственный вариант

Стандартный пакет net/http в Go предлагает удобный метод r.ParseMultipartForm(maxMemory). Он парсит тело запроса, складывает файлы до maxMemory байт в оперативку, а остальное сбрасывает во временные файлы на диск. Для внутреннего сервиса с картинками до 5 МБ этого хватает. Но стоит дать пользователям загружать видео или архивы на сотни мегабайт — и начинаются проблемы: временные файлы в /tmp не чистятся, память растёт в пиках, а при десятках параллельных загрузок сервис упирается в лимит файловых дескрипторов.

Ниже — четыре подхода к приёму файлов. Каждый решает конкретную задачу и за что-то платит.

Подход 1. ParseMultipartForm — быстрый старт

Классический путь из документации Go (версия 1.22+). Вызываете ParseMultipartForm, получаете multipart.File, копируете в нужное место.

// Go 1.22+
func uploadHandler(w http.ResponseWriter, r *http.Request) {
    // Ограничиваем тело запроса — без этого клиент может отправить сколько угодно
    r.Body = http.MaxBytesReader(w, r.Body, 50<<20) // 50 МБ

    // maxMemory: сколько байт хранить в RAM, остальное — во временный файл
    if err := r.ParseMultipartForm(10 << 20); err != nil {
        http.Error(w, "Файл слишком большой или повреждён", http.StatusBadRequest)
        return
    }
    defer r.MultipartForm.RemoveAll() // чистим временные файлы

    file, header, err := r.FormFile("document")
    if err != nil {
        http.Error(w, "Поле document отсутствует", http.StatusBadRequest)
        return
    }
    defer file.Close()

    dst, err := os.Create(filepath.Join("/var/uploads", header.Filename))
    if err != nil {
        http.Error(w, "Ошибка сервера", http.StatusInternalServerError)
        return
    }
    defer dst.Close()

    if _, err := io.Copy(dst, file); err != nil {
        http.Error(w, "Ошибка записи", http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

Проверка: отправьте файл через curl -F "document=@test.pdf" http://localhost:8080/upload — ответ 201, файл на диске.

За что платите

• Временные файлы: если забыть RemoveAll() или сервис упадёт до вызова — /tmp растёт.
• Весь файл буферизуется до того, как вы начнёте с ним работать. Для потоковой обработки (хеширование, отправка в S3) это лишний шаг.
• Имя файла из header.Filename контролируется клиентом — путь к файлу нужно санитизировать, иначе ../../etc/passwd попадёт куда не надо.

Подход 2. Потоковый multipart.Reader — минимум памяти

Вместо парсинга всей формы читаете части по одной через r.MultipartReader(). Каждая часть — это io.Reader, и вы копируете данные порциями напрямую куда нужно: в файл, в S3, в хеш-функцию. Временных файлов не создаётся вовсе.

// Go 1.22+
func streamUploadHandler(w http.ResponseWriter, r *http.Request) {
    r.Body = http.MaxBytesReader(w, r.Body, 500<<20) // 500 МБ

    mr, err := r.MultipartReader()
    if err != nil {
        http.Error(w, "Не multipart запрос", http.StatusBadRequest)
        return
    }

    for {
        part, err := mr.NextPart()
        if err == io.EOF {
            break
        }
        if err != nil {
            http.Error(w, "Ошибка чтения формы", http.StatusBadRequest)
            return
        }

        if part.FormName() != "document" {
            part.Close()
            continue
        }

        // Санитизируем имя файла
        safeName := filepath.Base(part.FileName())
        if safeName == "." || safeName == string(os.PathSeparator) {
            safeName = "unnamed"
        }

        dst, err := os.Create(filepath.Join("/var/uploads", safeName))
        if err != nil {
            part.Close()
            http.Error(w, "Ошибка сервера", http.StatusInternalServerError)
            return
        }

        // Копируем потоком — в памяти только буфер io.Copy (32 КБ по умолчанию)
        if _, err := io.Copy(dst, part); err != nil {
            dst.Close()
            part.Close()
            http.Error(w, "Ошибка записи", http.StatusInternalServerError)
            return
        }
        dst.Close()
        part.Close()
    }
    w.WriteHeader(http.StatusCreated)
}

Проверка: загрузите файл на 200 МБ. RSS процесса не должен вырасти больше чем на пару мегабайт.

За что платите

• Нельзя обратиться к другим полям формы (title, description) после начала чтения — они тоже приходят как части и их нужно читать в том же цикле.
• Код сложнее: вы сами управляете закрытием каждой части.
• Если клиент отправляет 50 частей, а вам нужна одна — остальные всё равно пройдут через цикл.

Подход 3. io.TeeReader — параллельные действия на лету

Часто файл нужно одновременно сохранить и посчитать контрольную сумму, или сохранить и отправить в вирусный сканер. Вместо двух проходов по данным используйте io.TeeReader: он дублирует поток — что прочитали из одного источника, автоматически записывается во второй.

// Go 1.22+
// Внутри цикла из подхода 2, после создания dst:
hasher := sha256.New()
tee := io.TeeReader(part, hasher)

if _, err := io.Copy(dst, tee); err != nil {
    // обработка ошибки
}

checksum := hex.EncodeToString(hasher.Sum(nil))
// checksum готов без повторного чтения файла

Тот же приём работает для отправки в объектное хранилище: вместо хешера подставляете io.Pipe, читающую сторону которого отдаёте в горутину с вызовом S3 PutObject.

Подход 4. Приём через PUT и Content-Length — без multipart

Если фронтенд контролируете вы, multipart не обязателен. Файл приходит как тело PUT-запроса, метаданные — в заголовках. Это упрощает серверный код до предела: r.Body — уже io.Reader, никакого парсинга форм.

// Go 1.22+
func putUploadHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPut {
        http.Error(w, "PUT only", http.StatusMethodNotAllowed)
        return
    }
    r.Body = http.MaxBytesReader(w, r.Body, 500<<20)

    contentType := r.Header.Get("Content-Type")
    if !isAllowedType(contentType) {
        http.Error(w, "Тип файла не разрешён", http.StatusUnsupportedMediaType)
        return
    }

    dst, err := os.CreateTemp("/var/uploads", "upload-*")
    if err != nil {
        http.Error(w, "Ошибка сервера", http.StatusInternalServerError)
        return
    }
    defer dst.Close()

    if _, err := io.Copy(dst, r.Body); err != nil {
        http.Error(w, "Ошибка записи", http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

Подходит для загрузки через JavaScript (fetch с body: file) и CLI-клиенты. Не подходит, если в одном запросе нужно передать и файл, и текстовые поля формы.

Сравнение подходов

Главное правило загрузки файлов: не доверяйте ни одному байту от клиента. Ни имени файла, ни Content-Type, ни размеру. Всё проверяется на сервере, всё ограничивается на сервере.

Общие грабли — независимо от подхода

1. Нет MaxBytesReader — нет лимита. Без него клиент может слать гигабайты, пока у сервера не кончится диск или память. Content-Length контролируется клиентом и может врать, поэтому ограничивайте именно чтение.
2. Имя файла не санитизировано. header.Filename может содержать ../, абсолютный путь или спецсимволы. Используйте filepath.Base() и дополнительно проверяйте результат.
3. Content-Type из заголовка — не гарантия типа. Клиент может отправить исполняемый файл с Content-Type: image/png. Если тип критичен — проверяйте содержимое. Пакет net/http предлагает http.DetectContentType(), которому достаточно первых 512 байт.
4. Нет таймаута на чтение тела. Медленный клиент держит горутину и файловый дескриптор. Выставляйте ReadTimeout на уровне http.Server или используйте контекст с дедлайном.
5. Запись на тот же диск, откуда читает ОС. Если /tmp и /var/uploads на одном разделе, массовая загрузка может забить диск и уронить весь сервер, включая логи. Мониторьте свободное место и выносите загрузки на отдельный раздел или в объектное хранилище.

Сноска: multipart/form-data — формат кодирования тела HTTP-запроса, описанный в RFC 2046 и RFC 7578. Браузер использует его по умолчанию при отправке формы с enctype="multipart/form-data". Каждое поле и каждый файл передаются как отдельная «часть» (part) с собственными заголовками, разделённые уникальной строкой-разделителем (boundary).

Что делать дальше

• Если файлы уходят в S3-совместимое хранилище — изучите multipart upload API на стороне хранилища: он позволяет загружать файл частями параллельно, а не ждать полного приёма на сервере.
• Добавьте метрику upload_bytes_total (Prometheus-счётчик) — она покажет реальную нагрузку по объёму раньше, чем вы заметите её по CPU.
• Для антивирусной проверки на лету смотрите в сторону ClamAV с потоковым интерфейсом: файл можно передать через io.TeeReader, не сохраняя на диск отдельно.
• Тестируйте граничные случаи: нулевой файл, файл ровно на границе лимита, оборванное соединение на середине загрузки. В Go это удобно делать через httptest.NewServer и кастомный io.Reader, возвращающий ошибку после N байт.