Developer

CSV, Excel, YAML: когда что

↑ 1.4 JSON, XML и другие форматы · ← Предыдущая

Обязательно~5 мин чтенияУровень: junior

Зачем это аналитику и PM

Выгрузку заказывают как «таблицу», а интеграцию описывают файлом YAML. Путаница разделителя, кодировки и отступов превращает согласованные колонки в одну кашу ещё до бизнес-проверки.

План темы

  • разделители и кодировки
  • типовые проблемы при импорте
  • YAML в конфигурациях и OpenAPI

Объяснение

CSV — текст таблицы: строка файла равна строке таблицы, колонки разделены символом. Excel — книга таблиц со своими типами ячеек, формулами и несколькими листами. YAML — текст настроек и иногда спецификаций: отступы задают вложенность. Для обмена заказами между системами по-прежнему чаще JSON или XML. CSV и книга Excel уместны там, где человек смотрит глазами и правит колонку. YAML уместен там, где человек правит настройки или читает OpenAPI.

Разделители и кодировка

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

Текст в файле имеет кодировку. Для нового обмена разумно назвать UTF-8. Нужна ли метка BOM, чтобы программа узнала UTF-8, проверяют одним файлом.

Что ломается при импорте

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

YAML

Вложенность в YAML задают пробелами в начале строки. Табуляцию и пробелы не смешивают. Двоеточие отделяет ключ от значения. Списки начинают с дефиса. OpenAPI часто лежит именно так: тот же контракт, что и JSON, другой синтаксис. Комментарий в YAML начинается с #. В JSON комментария нет, поэтому файл не копируют из одного формата в другой без преобразования.

Отдельная ловушка слов. Проверено разбором PyYAML 6: некавычечное yes стало логическим true, кавычечное осталось строкой. В YAML 1.2 эти слова уже не обязаны быть логическими. Другой инструмент мог прочитать иначе. Слово-значение в конфиге лучше закавычить и один раз прогнать тем разбором, который стоит в контуре.

Примеры

Учебный CSV. Разделитель — запятая, идентификатор в кавычках, чтобы его не сочли числом.

id,sku,qty
"001042",MUG-1,2

Тот же смысл в YAML. Файл ниже разбирается обычным безопасным разбором. yes записан в кавычках специально.

order:
  id: "1042"
  confirm: "yes"
  items:
    - sku: MUG-1
      qty: 2

OpenAPI-фрагмент той же идеей. Это не полная спецификация, только кусок, который должен остаться корректным YAML.

paths:
  /orders:
    get:
      summary: Список заказов

Нюансы и подводные камни

  • Excel и CSV — не один формат. Книга с двумя листами в CSV без потерь не переносится: у CSV один лист.
  • Формула в ячейке — не значение для интеграции. В обмен кладут посчитанный текст или запрещают формулы в файле приёма.

Практика

Для выгрузки заказов человеку и для файла настроек интеграции выберите носитель. У таблицы назовите разделитель, кодировку и какую колонку нельзя превращать в число.

Ожидаемый результат: человеку назначены CSV или книга таблицы, машине не отдан Excel как единственный контракт API. У идентификатора сказано «текст». У YAML, если он выбран, нет некавычечного yes в значении, пока вы не проверили разбор.

Вопросы с ответами

Связано с блоком Developer

Связанные темы

Вид графа

Обратные ссылки