ПРО АНАЛИТИКА | СИСТЕМНЫЙ АНАЛИТИК | АЛЕКСАНДР НЕЗДЕМИНА
Образование · 6 июля 2026 г.
КАК ЗАГРУЖАТЬ ФАЙЛЫ В API? — 6 июля 2026 г. в 05:24:27.609
КАК ЗАГРУЖАТЬ ФАЙЛЫ В API? Представьте, что вам надо сделать загрузку документов, например, сканы паспорта. Как правильно это сделать? Первое, что может прийти в голову - это воткнуть в JSON в формате base64, но так делать не надо! Потому что кодировка может очень сильно раздуть файл. - если это маленькая картиночка, то это еще терпимо, - если это pdf со сканами всех страниц документа, то это будет полная жесть. И ладно, что нам это надо отправить, но нам еще стороне API такое добро нужно обработать, а обработка такой дикой JSON-ины заставит сервер не то что задуматься, а дико затупить и подвиснуть. И есть риск, что результат будет плачевным 🥲 Поэтому давайте обсудим, как лучше грузить файлы? ➖➖➖ 1️⃣ Content-Type: Multipart/form-data. Отправка файла через ваш бэкенд. Это классический способ. Клиент отправляет файл на сервер, как multipart, вместе с метаданными в виде байтиков, а бэк принимает байты и кладёт их в хранилище. Пример, POST /documents Content-Type: multipart/form-data (file=скан.pdf, type=passport) Этот способ хорошо использовать, когда файл имеет небольшой размер, например, аватарка или один документ. Ну и тогда, когда не хочется заморачиваться, так как в этом случае у нас один запрос и валидация проходит прям на серваке, то есть никакой доп логики и усложнений. Однако, этот способ очень плох, когда у вас файлы много весят или их очень много, например, вы хотите передать не один документ, а пачку док разом. При использовании этого варианта в какой-то момент бэк может начать захлебываться и вальнется по таймауту, поэтому для этого используем способ 2. 2️⃣ Presigned URL При этом варианте мы отправляем файлы напрямую в хранилище, то есть API-шки у нас тут участвуют только в роли указателя, что сделать с файлом, но не передают его. При этом сервер выдает просто доступ к хранилищу и никак не взаимодействует с самим файлом. Как это выглядит: 1. Клиент дергает API и говорит: хочу загрузить файл. POST /uploads → { "uploadUrl": "https://storage/...&sig=...", "key": "docs/abc123", "expiresIn": 600 } 2. Клиент грузит файл НАПРЯМУЮ в хранилище по ссылкам при помощи PUT метода. 3. Клиент дергает бэк, чтобы проверить, что все загрузилось. Если загрузлось, то возвращается ключ, по которому можно работать с документами. POST /documents { "key": "docs/abc123", "type": "passport" } Главный жирный плюс такого подхода это то, что тяжёлую работу берёт на себя хранилище и этот подход легко масштабировать. Однако, в использовании такого подхода есть нюанс в сложности его проектирования. Например, надо учитывать типы данных, которые вы готовы отправлять и их максимальный размер. Еще, стоит продумывать проверку таких загруженных файлов на вирусы. И конечно же, надо продумывать правила доступа, кто может писать файлы напрямую, а кто нет. ➖➖➖ Подытожу Первый мы используем когда надо прокидываь низковесные файлы в единственном числе, загружать файлы на диск лучше, когда у вас большой скоуп или вес файлов. Было полезно - ставь 🔥