Загрузка больших файлов через API: как согласовать пределы и продолжение

До выбора способа загрузки стоит описать один маршрут: какой документ передают, как продолжают остановленную передачу и чем подтверждают завершение. Общие границы интерфейса можно закрепить в контракте API-модуля; здесь предмет договорённости — именно файл и его состояние.

Размер и тип входного файла

Ограничение размера должно быть понятно до начала передачи. Зафиксируйте максимально допустимый объём, единицу измерения, разрешённые типы документов и место проверки. Клиентская подсказка помогает пользователю, но серверу всё равно нужно проверить поступившие данные. Название файла и указанный отправителем тип не доказывают, что содержимое пригодно для обработки.

Рассмотрим учебный пример: партнёр загружает комплект чертежей для одной заявки. В примере согласованы файлы до 120 МБ; это условная граница, а не рекомендация для любого продукта. Нужно отдельно решить, допускается ли архив, как обращаться с несколькими документами и что считать одним комплектом. Для сжатого файла размер передачи и объём после распаковки могут различаться, поэтому правила обработки содержимого тоже входят в обсуждение.

Неверный файл лучше отклонить с объяснением: какой предел нарушен и что пользователь может изменить. Общее «ошибка загрузки» заставляет повторять заведомо неподходящий ввод. Если проверка содержимого выполняется позже, интерфейс должен различать «передача принята» и «документ проверен».

Идентификатор сессии и продолжение после обрыва

Сессия связывает части передачи с конкретным документом и отправителем. Для примера назовём её upload-42. Клиент хранит этот идентификатор, а сервер сообщает, какие фрагменты действительно сохранены. Отправленные клиентом байты нельзя считать сохранёнными только потому, что запрос начался.

Продолжение требует неизменности исходного файла. Если пользователь после обрыва выбрал другой документ с тем же названием, прежние фрагменты нельзя незаметно присоединить к нему. В договорённости нужны признаки исходного файла, порядок сверки уже принятого диапазона и ответ на повтор одного фрагмента. Проверка права продолжить сессию обязательна даже при известном идентификаторе.

Для upload-42 учебный сервер подтвердил первые две части из трёх. После восстановления связи клиент запрашивает состояние и передаёт только отсутствующую часть. Если сохранённая точка недоступна, он получает явный ответ и решение о новой сессии. Срок жизни сессии выбирают с учётом процесса: длинная пауза может быть нормальной для выездного сотрудника и нежелательной для другого сценария.

Проверка целостности и завершения

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

В паспорте загрузки удобно отделить три состояния: «передаётся», «получен полностью», «допущен к использованию». Ошибка чтения чертежа относится к последнему переходу, а отсутствие части — к первому. Пользователю нужны разные действия: выбрать исправленный документ или продолжить передачу.

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

Матрица превышения лимита и истечения сессии

Четыре отрицательных примера делают паспорт проверяемым. Подготовьте файлы и последовательности действий, а не только названия ошибок.

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

Обсудить маршрут загрузки документа.