Контракт CSV-импорта: что согласовать до конвертации
Зафиксировать UTF-8, header, delimiter, типы, null и acceptance fixture
Правильно открывшийся CSV ещё не означает правильно выполненный импорт. Один получатель трактует 001 как код, другой — как число; пустая ячейка может означать пустую строку, пропуск или null. До конвертации запишите короткий контракт между отправителем и принимающей системой.
Контракт нужен для конкретной загрузки, а не для всех CSV на свете. Достаточно одной страницы с параметрами файла, колонками и несколькими ожидаемыми результатами. Чем меньше догадок остаётся у импортёра, тем проще проверить повторную загрузку.
Минимальная спецификация
Зафиксируйте следующие пункты:
| Параметр | Пример договорённости |
|---|---|
| Кодировка | UTF-8, BOM допускается |
| Разделитель | точка с запятой |
| Заголовок | присутствует; code,note,optional как имена колонок |
| Порядок колонок | code, затем note, затем optional |
| Типы | все три поля — строки |
| Пустая ячейка | пустая строка, не null |
| Многострочное поле | допускается; после конвертации перенос LF |
| Повторная загрузка | обновление по code или явное отклонение дубля |
| Формулы | файл предназначен машинному импортёру; интерпретация отключена |
В примере с точкой с запятой сама строка заголовка записывается code;note;optional. Запятая в перечне имён выше — пунктуация описания, не настройка файла. При согласовании лучше приложить буквальный маленький файл, чтобы устранить такие различия.
Правила полей в кавычках и экранирования описаны в RFC 4180, раздел 2, октябрь 2005; проверено 05.10.2026. Выбор точки с запятой здесь — отдельное соглашение поддерживаемого диалекта, а не буквальный comma-separated пример RFC.
Контрольный искусственный файл
Ниже синтетические данные. Вторая ячейка содержит перевод строки внутри кавычек:
code;note;optional
001;"строка 1
строка 2";
В CSV → JSON установите delimiter=semicolon, header=true, pretty=false, trailing_newline=false. Проверенный результат операции версии 1:
[{"code":"001","note":"строка 1\nстрока 2","optional":""}]
Результат содержит одну запись, хотя физически файл показан на нескольких строках. Код сохраняет ведущие нули, а последняя ячейка становится пустой строкой. Именно этот результат должен ожидать импортёр. Если у него другие ожидания, измените контракт до обработки основного массива.
Добавьте к контрольному файлу несколько отклоняемых случаев: повтор имени колонки, отсутствующая ячейка, незакрытая кавычка. Neraviko возвращает для них явные ошибки; контракт принимающей системы тоже должен объяснять, прекращается ли загрузка целиком или допускается частичная обработка. Конвертер не определяет политику вашей базы.
Типы и повторная загрузка
CSV → JSON в Neraviko не угадывает числа, даты, логические значения и null. Если принимающая система требует типизированный объект, назначьте преобразования конкретным колонкам: допустимый формат даты, десятичный разделитель, диапазон числа, значения логического поля. Преобразовывать все числоподобные строки опасно для кодов и идентификаторов.
Для повторов импорта определите устойчивый ключ. Создание нового идентификатора при каждом запуске может породить дубли. Зафиксируйте, разрешено ли обновлять существующие записи и какие поля сохраняются. После пробной загрузки повторите тот же файл и проверьте ожидаемое поведение.
Приёмка файла
- Контрольный набор даёт буквальный ожидаемый JSON.
- Заголовок и ширина всех записей соответствуют контракту.
- Пустые значения и многострочный текст обработаны согласованно.
- Типы назначаются только определённым колонкам.
- Повторная загрузка проверена отдельно.
- Количество записей и ключи после импорта сверены с источником.
Лимиты Neraviko: запрос до 262 144 байт вместе с JSON-конвертом и экранированием, парсер до 5 000 записей включая строку заголовков и 256 колонок, поле до 65 536 байт. С включённым header=true это максимум 4 999 строк данных. Превышение не означает, что следует обрезать данные: подготовьте согласованные части или выберите подходящий импортный процесс.
Обработка выполняется на сервере. По контракту операции сырые входы и выходы не сохраняются и не логируются по умолчанию. Перед основной загрузкой согласуйте допустимую среду обработки; для проверки формата достаточно искусственного контрольного файла.