До реализации пакетной операции нужно выбрать её смысл. Либо все записи образуют неделимое действие, либо допускаются отдельные результаты. Это решение влияет на валидацию, отчёт и дальнейшие действия пользователя. Нельзя выводить его из того, что сервер вернул успешный сетевой ответ.
Граница пакета и идентификатор записи
В учебном примере партнёр передаёт пять заявок. Каждая имеет собственный идентификатор и может быть обработана независимо. Пакет получает обозначение batch-17; строки сохраняют свои row-1–row-5. Это придуманные имена для объяснения, а не схема действующего API.
Уточните, какие ограничения относятся к целому пакету: количество строк, общий размер и допустимый тип операции. Затем определите, чем строка связана с исходной заявкой. Номер позиции в списке неудобен как единственное основание, если отправитель переставляет строки при исправлении.
Если одна запись зависит от другой, независимая обработка может оказаться неверной моделью. Например, создание объекта и обращение к нему нельзя описать как пять совершенно отдельных заявок без порядка действий. Такие зависимости нужно выявить до согласования частичного успеха. Общие границы фиксируют в контракте API-модуля.
Результат каждой строки
Для независимых заявок ответ связывает каждую исходную запись с её результатом. По строке должны быть понятны состояние, причина и разрешённый следующий шаг. «Ошибка» без указания строки вынуждает пользователя заново искать проблему во всём наборе.
Разделяйте «не принята», «принята в обработку» и «операция завершена», если процесс допускает промежуточное состояние. Принятая заявка ещё не является выполненной услугой. Неизвестный исход не следует превращать в отказ ради удобства отчёта.
Отсутствующая строка ответа тоже требует трактовки. Если контракт обещает результат для каждой записи, неполный ответ не подтверждает обработку отсутствующей части. Получатель сохраняет пробел и сверяет состояние по предусмотренному пути, не повторяя действие по догадке.
Отделение валидации от выполнения
Проверка структуры может найти неправильный код или пустое поле до выполнения операции. Но успешная проверка не означает успешной записи: во время выполнения могут измениться права, доступность зависимости или допустимость действия.
Опишите, выполняется ли предварительная проверка всего пакета и что она гарантирует. В нашем примере она помогает исправить явные ошибки, но не резервирует право на будущую обработку. Для зависимого или неделимого пакета потребуется другая договорённость.
Пользователь должен понимать, были ли изменения в системе. Если строка остановлена до выполнения, это можно сообщить явно. Если запрос на выполнение был начат, а подтверждение потеряно, нельзя утверждать, что изменений точно нет. Здесь помогают принципы разбора известных и неизвестных исходов обмена, но отчёт пакета должен сохранить связь с каждой строкой.
Пример ответа для смешанных исходов
Ниже учебный протокол batch-17. Он описывает бизнес-смысл результата, а не обязательные названия полей или коды транспорта.
| Строка | Состояние | Причина или подтверждение | Следующее действие |
|---|---|---|---|
| row-1 | Завершена | Сохранена заявка Q-101 | Не отправлять заново как новую |
| row-2 | Не принята | Неизвестный код подразделения | Уточнить код и передать исправленную запись |
| row-3 | В обработке | Есть подтверждение приёма | Узнать окончательный результат |
| row-4 | Исход неизвестен | Подтверждение выполнения не получено | Сверить состояние до повтора |
| row-5 | Не выполнялась | Превышена согласованная граница количества | Исправить входные данные |
Итоговая сводка должна считаться из этих состояний и не скрывать их. Фраза «два ошибки» хуже, чем отдельный список записей, причин и решений. Если пакет выполняется долго, нужна связь первоначального ответа с последующим отчётом: обе стороны должны узнавать тот же пакет и те же строки.
Проверяйте смешанный набор, повтор получения отчёта и отсутствие одного поэлементного результата. Затем выполните исправление только выбранных строк и убедитесь, что уже завершённые не стали новыми заявками. Полезный артефакт — таблица ответа, которую сотрудник способен использовать без просмотра технического журнала.
