Загрузка файлов

До сих пор наш трекер питался JSON: TodoInput из урока про привязку, конверты Envelope из урока про ответы. Но JSON таскает только текст: аватар, вложение письма, импорт CSV в него не кладёшь — байты пришлось бы кодировать base64 (треть лишнего трафика) и держать всё тело в памяти до конца декодирования. Для файлов есть стандарт — multipart/form-data: тело режется на самодостаточные части (parts), каждая со своими заголовками Content-Disposition и Content-Type, а между частями стоит boundary — случайная строка из заголовка запроса. HTML-форма должна просить этот формат явно: <form method="post" enctype="multipart/form-data">, — забудете enctype, и форма уедет как application/x-www-form-urlencoded: сервер получит только имя файла, а не содержимое. curl собирает multipart за вас: curl -F "avatar=@cat.jpg" localhost:8080/upload — флаг -F читает файл, ставит Content-Type по расширению и режет boundary сам. На стороне gin gin загрузка файлов — это одна пара вызовов: c.FormFile достаёт файл из разобранной формы, c.SaveUploadedFile пишет его на диск. Всё остальное в уроке — гигиена вокруг этой пары: куда уходят большие файлы, почему имя и тип от клиента нельзя верить, как принять пачку за один POST и где стоит настоящий лимит размера. Хендлер повесим на POST: загрузка создаёт ресурс, и 201 Created здесь уместнее 200, как и для POST /todos из четвёртого урока.

Заглянем в context.go — там пять строк, и все про net/http. c.FormFile первым делом проверяет c.Request.MultipartForm и, если форма ещё не разобрана, зовёт c.Request.ParseMultipartForm(c.engine.MaxMultipartMemory): поле движка уходит в стандартную библиотеку как maxMemory. ParseMultipartForm читает всё тело запроса и раскладывает части: текстовые поля — в Value, файловые — в буфер объёмом maxMemory, а что в буфер не влезло, переливается во временные файлы в os.TempDir. Второй вызов разбора не случится: MultipartForm уже не nil, поэтому и c.FormFile, и c.PostForm, и c.MultipartForm на одном запросе спокойно делят одну разобранную форму. Возврат — Request.FormFile(name): первый *multipart.FileHeader поля. FileHeader — это снимок части: Filename дословно как назвал файл клиент, Size — фактический размер части в байтах, посчитанный при разборе, Header — MIME-заголовки самой части, включая Content-Type, присланный клиентом. fh.Open() отдаёт multipart.File — интерфейс io.Reader, io.ReaderAt, io.Seeker и io.Closer: для мелких файлов это окно в память, для крупных — чтение секции временного файла. Пара FormFile и SaveUploadedFile — это весь formfile gin: получить хедер, открыть, скопировать. Разница между «заработало» и «не утекло в прод» — в деталях вокруг: имени файла, типе содержимого, лимитах и поведении при пачке. Их и разберём по порядку, начиная с того, куда именно пишет SaveUploadedFile.

SaveUploadedFile — обёртка из четырёх строк над net/http-миром: fh.Open(), os.MkdirAll(filepath.Dir(dst), 0o750), os.Create(dst) и io.Copy. Каталог назначения она создаёт сама — ./uploads не нужно готовить руками; файл получает права 0666 до umask, а в свежих версиях gin есть и SaveUploadedFileWithPermissions с явным perm. io.Copy работает потоково с буфером 32 КиБ: память хендлера не зависит от размера файла — хоть из буфера, хоть из временного файла на диске. Главная дыра здесь — fh.Filename: он приходит с клиента дословно. Браузер шлёт только базовое имя, но curl позволяет filename=..., а руками собранный multipart — вообще что угодно, хоть ../../.bashrc. filepath.Join фильтром не служит: он склеивает путь и вызывает Clean, а Clean честно разрешает ../.. — и путь выезжает за пределы каталога. Минимальная страховка — filepath.Base(fh.Filename), отрезающая каталоги; пустое имя (filename=) после Base превращается в «.», и os.Create на каталоге честно упадёт ошибкой — обрабатывайте её как 400. Норма для боевого кода — вообще не использовать клиентское имя для сохранения: метка времени плюс случайный суффикс, а оригинал хранить в базе и показывать в ответе. Это убивает разом traversal, коллизии двух пользователей с одинаковым cat.jpg и проблемы с юникодом в файловых системах.

c.FormFile всегда возвращает только первый файл поля. Для пачки — галереи, набора вложений — есть c.MultipartForm(): она доводит ParseMultipartForm и возвращает multipart.Form с двумя картами: Value map[string][]string для текстовых полей и File map[string][]multipart.FileHeader для файлов. Ключи повторяются ровно как в форме: три раза -F "photos=..." дают File["photos"] из трёх хедеров — тот же механизм, что у повторяющихся query-ключей из третьего урока. Текст рядом с файлами достаётся c.PostForm("caption") — метод сам разберёт multipart, если это ещё не случилось, и вернёт первое значение поля. Есть и путь через binding: multipart/form-data у ShouldBind — отдельный биндер, и структура с полями multipart.FileHeader и []multipart.FileHeader по тегу form заполнится файлами так же, как TodoInput заполнялся JSON-ом; binding:"required" на поле-файле проверит, что файл приложили, а validate прогонит остальные теги — механика четвёртого урока без изменений. Ручной путь с c.MultipartForm оставляет больше контроля: пофайловые логи, частичный успех, свои сообщения об ошибках — для загрузок это обычно и нужно. Общий принцип прежний: binder — для простых случаев с готовой валидацией, ручные вызовы — когда обработка файла сама по себе логика.

Самое коварное место темы. r.MaxMultipartMemory = 8 << 20 — поле движка, по умолчанию 32 МиБ; gin передаёт его в ParseMultipartForm как maxMemory. Семантика у параметра одна: сколько байтов файловой части жить в памяти. Читатель multipart сначала заполняет буфер, а дальше переливает остаток части во временный файл в os.TempDir — загрузка в 2 ГиБ при maxMemory 8 МиБ завершится успешно: место на диске, а не в RAM. После возврата хендлера net/http удаляет временные файлы формы сам — чистить нечего, но и подхватить их не выйдет: копируйте содержимое в своём хендлере, как мы и делаем через SaveUploadedFile. Жёсткий же лимит тела в gin не встроен — его ставит http.MaxBytesReader: обёртка c.Request.Body в звене из шестого урока, c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, limit). При превышении ParseMultipartForm получает ошибку «http: request body too large», и хендлер отвечает 413 Request Entity Too Large. Дешёвый фильтр до разбора — проверка c.Request.Content-Length: клиент её может соврать, поэтому это только первый рубеж, авторитетный — MaxBytesReader, читающий по факту. Для очень больших файлов, где даже временные файлы не нужны, есть c.Request.MultipartReader() — потоковый разбор частей на лету без ReadForm-буферизации: NextPart, ручной разбор Content-Disposition и io.Copy сразу в хранилище. Gin-удобств там нет, но для гигабайтов и ограниченного диска это единственный путь; в 95% случаев хватает FormFile с нормальными лимитами.

В загруженном файле доверять можно только фактам. Filename — слова клиента: годится для показа («вы загрузили cat.jpg») и ни для чего больше. Header.Get("Content-Type") — Content-Type части — тоже слова клиента: curl -F "avatar=@evil.exe;type=image/jpeg" подделывает его одним флагом. fh.Size — вычислен net/http по факту чтения части, ему верить можно; проверка верхней границы всё равно должна случиться заранее — звеном с MaxBytesReader, а не после сохранения двух гигабайт на диск. Настоящий тип говорит содержимое: http.DetectContentType по первым 512 байтам — тот самый sniffing из net/http с таблицей магических байтов: JPEG начинается с \xFF\xD8\xFF, PNG — с \x89PNG, PDF — с %PDF-. На неизвестных байтах вернёт application/octet-stream — «непонятно, скачивается, не исполняется». Механика: fh.Open(), io.ReadFull в буфер на 512 байтов, DetectContentType по прочитанному куску, а перед дальнейшим копированием — Seek(0, io.SeekStart): multipart.File поддерживает Seek, но голова уже съедена. Whitelist расширений (.jpg, .png, .gif) оставьте второй линией: совпадение расширения и сниффнутого типа — признак здравого файла, расхождение — повод для 415 Unsupported Media Type. И помните из девятого урока: validator валидирует структуру и строки, байты — ваша работа. Последний штрих — раскладка по каталогам: тысячи файлов в одной папке тормозят файловую систему, раскладывайте по дате или префиксу имени.

Отправлять multipart удобно curl-ом: -F "avatar=@cat.jpg" читает файл и ставит Content-Type по расширению; -F "avatar=@cat.jpg;type=image/jpeg" задаёт тип части явно; текстовые поля — просто ещё один -F; повторяйте имя поля — получите пачку, как в form.File["photos"]. HTML-форма симметрична: method="post", enctype="multipart/form-data", input type="file" с name="avatar", атрибут multiple для пачки и accept="image/*" как фильтр диалога — но помните, что accept фильтрует только окно выбора, серверная проверка всё равно ваша. Забытый enctype — самый частый дебют: сервер получит urlencoded и упадёт с ErrNotMultipart на разборе. Обрезанный curl (Ctrl+C посреди передачи) даст ошибку unexpected EOF от multipart-читателя — отвечайте 400 с «файл не долетел». Дальше файл живёт своей жизнью: сохранить сохранили, а отдать — штатными средствами прошлого урока: r.Static("/uploads", "./uploads") раздаёт сохранённое по URL, c.FileAttachment отдаёт с Content-Disposition для скачивания под исходным именем. Для тестов тело собирает mime/multipart.NewWriter — разберём его в уроке 21-testirovanie вместе с httptest. И последняя карта — прод: локальный диск удобен на одном узле, а под горизонтальное масштабирование файлы уезжают в объектное хранилище, и тогда вместо SaveUploadedFile io.Copy пишет в клиент S3 — механика разбора формы не меняется ни на байт.