Convert JSON to CSV: Complete Guide With Examples

Когда вам нужно преобразование JSON в CSV

JSON является стандартным форматом для API и веб-приложений, но в момент, когда данные необходимо вывести за пределы экосистемы разработчиков — в электронную таблицу, инструмент бизнес-аналитики, импорт базы данных или отчет, отправленный заинтересованной стороне — CSV обычно является ожидаемым форматом.

Распространенные сценарии, когда возникает необходимость преобразования JSON в CSV:

• Экспорт данных API — извлечение записей из REST API и загрузка их в Excel или Google Sheets для анализа.
• Импорт в базы данных — многие базы данных (PostgreSQL, MySQL, SQLite) поддерживают импорт CSV из коробки, но не JSON.
• Отчетность — не технические заинтересованные стороны нуждаются в данных в формате, который они могут открыть в электронной таблице, а не в просмотрщике JSON.
• Конвейеры данных — устаревшие ETL-системы часто ожидают CSV в качестве формата обмена между этапами.

Попробуйте сами: Вставьте массив JSON в наш JSON в CSV конвертер для мгновенной загрузки готового CSV файла.

Простой пошаговый процесс преобразования

Простой случай: у вас есть массив JSON с плоскими объектами, где каждый объект имеет одни и те же ключи. Это напрямую соответствует таблице CSV.

Входной JSON:

[
  { "name": "Alice", "age": 30, "city": "Portland" },
  { "name": "Bob", "age": 25, "city": "Seattle" },
  { "name": "Carol", "age": 35, "city": "Denver" }
]

Выходной CSV:

name,age,city
Alice,30,Portland
Bob,25,Seattle
Carol,35,Denver

Ключи объектов становятся заголовками столбцов, а каждый объект становится строкой. Это счастливый путь — и он прекрасно работает для большинства ответов API, которые возвращают массивы записей.

Сложность возникает, когда ваш JSON не плоский. Вложенные объекты, массивы внутри объектов, отсутствующие ключи и смешанные типы требуют решений о том, как представить иерархические данные в плоской таблице.

Обработка вложенного JSON

JSON в реальном мире редко бывает плоским. Ответ API для пользователя может включать вложенный объект адреса, массив ролей и необязательные поля, которые не появляются в каждой записи. CSV не имеет концепции вложенности, поэтому вам нужна стратегия упрощения.

Стратегия 1: Точечная нотация

Наиболее распространенный подход. Вложенные ключи объединяются точками, чтобы сформировать одно имя столбца.

Входные данные:

[
  {
    "name": "Alice",
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  }
]

Выходные данные:

name,address.city,address.state
Alice,Portland,OR

Точечная нотация сохраняет структурную связь в имени столбца. Она хорошо работает для одного или двух уровней вложенности, но становится громоздкой для глубоко вложенных данных (user.profile.settings.notifications.email).

Стратегия 2: Отдельные столбцы для каждого конечного значения

Похоже на точечную нотацию, но с пользовательскими именами столбцов, которые опускают иерархию вложенности. Например, address.city становится просто city. Это создает более чистые заголовки, но требует ручного сопоставления столбцов и рискует столкнуться с конфликтами имен, если разные вложенные объекты имеют ключи с одинаковыми именами.

Стратегия 3: Преобразование вложенных объектов в строку

Для сложных вложенных структур, которые плохо отображаются на плоские столбцы, сериализуйте вложенное значение как строку JSON внутри ячейки CSV.

Выходные данные:

name,address
Alice,"{""city"":""Portland"",""state"":""OR""}"
Bob,"{""city"":""Seattle"",""state"":""WA""}"

Это сохраняет все данные, но ячейки CSV содержат необработанный JSON — не идеально для пользователей электронных таблиц. Это работает, когда CSV является промежуточным форматом, который будет снова разобран кодом.

Сравнение подходов к упрощению

Подход	Читаемость	Потеря данных	Глубокая вложенность	Лучше всего для
Точечная нотация	Хорошо	Нет	Становится громоздким	1-2 уровня вложенности
Пользовательские имена столбцов	Лучше всего	Возможные конфликты	Ручные усилия	Известные, стабильные схемы
Преобразование в строку	Плохо для людей	Нет	Обрабатывает любую глубину	Машина-до-машины конвейеры

Обработка массивов внутри объектов

Массивы представляют собой другую задачу. Рассмотрим пользователя с несколькими ролями:

{
  "name": "Alice",
  "roles": ["admin", "editor", "viewer"]
}

У вас есть несколько вариантов представления этого в CSV:

• Объединить как разделенную строку: admin;editor;viewer в одной ячейке. Просто, но требует разбора позже.
• Отдельные столбцы: roles.0, roles.1, roles.2. Работает, когда максимальная длина массива известна и мала.
• Отдельные строки: Одна строка на роль, с повторением других данных пользователя. Это денормализует данные, но избегает ячеек с несколькими значениями.
• Преобразование в строку: ["admin","editor","viewer"] как необработанный JSON в ячейке. Сохраняет структуру для последующей обработки.

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

Особые случаи

Каждое преобразование JSON в CSV в конечном итоге сталкивается с этими случаями. Знание о них заранее экономит время на отладку.

Нулевые значения

JSON null может соответствовать пустой ячейке, буквальной строке null или пользовательскому заполнителю. Большинство инструментов используют пустую ячейку, что правильно для электронных таблиц, но теряет различие между "null" (явно нет значения) и "отсутствующим ключом" (поле не присутствует). Если это различие имеет значение, используйте null как буквальную строку.

Смешанные типы

Поле JSON может быть строкой в одной записи и числом в другой. Столбцы CSV не имеют типов — все является строкой — поэтому это обычно работает нормально на уровне CSV. Проблема возникает при импорте в типизированные системы (базы данных, типизированные фреймы данных). Проверяйте типы после преобразования.

Отсутствующие ключи

Когда объекты в массиве JSON не имеют одинаковых ключей, конвертер должен построить объединение всех ключей по всем объектам. Это создает строку заголовка с каждым возможным столбцом, а объекты, у которых отсутствует ключ, получают пустую ячейку для этого столбца.

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "city": "Seattle" }
]

Выходные данные:

name,age,city
Alice,30,
Bob,,Seattle

Специальные символы в значениях

Значения CSV, которые содержат запятые, двойные кавычки или переносы строк, должны быть заключены в двойные кавычки. Если само значение содержит двойные кавычки, они экранируются удвоением. Большинство библиотек преобразования обрабатывают это автоматически, но если вы создаете свой собственный конвертер, это наиболее распространенный источник ошибок.

name,bio
Alice,"Любит ""JSON"" и программирование"
Bob,"Портленд, ОР"

Программное преобразование

JavaScript / Node.js

Для простых плоских данных вы можете преобразовать JSON в CSV за несколько строк без каких-либо зависимостей:

const jsonToCsv = (data: Record<string, unknown>[]) => {
  if (data.length === 0) return "";

  const headers = Object.keys(data[0]);
  const rows = data.map((row) =>
    headers
      .map((header) => {
        const value = row[header] ?? "";
        const str = String(value);
        return str.includes(",") || str.includes('"') || str.includes("\\n")
          ? `"\${str.replace(/"/g, '""')}"` 
          : str;
      })
      .join(",")
  );

  return [headers.join(","), ...rows].join("\\n");
};

Для производственного использования с вложенными данными библиотеки, такие как json2csv (из пакета @json2csv/plainjs), обрабатывают упрощение, пользовательские преобразования и особые случаи:

import { Parser } from "@json2csv/plainjs";
import { flatten } from "@json2csv/transforms";

const parser = new Parser({
  transforms: [flatten({ separator: "." })],
});

const csv = parser.parse(data);

Python

Стандартная библиотека Python имеет все необходимое для базовых преобразований:

import csv
import json
import io

def json_to_csv(data: list[dict]) -> str:
    if not data:
        return ""

    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)
    return output.getvalue()

Для вложенного JSON библиотека pandas упрощает и преобразует за один вызов:

import pandas as pd

df = pd.json_normalize(data, sep=".")
df.to_csv("output.csv", index=False)

json_normalize автоматически обрабатывает вложенные объекты, используя точечную нотацию для имен столбцов. Это самый быстрый способ перейти от вложенного ответа API к чистому CSV файлу.

Учет больших файлов

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

Потоковые парсеры — это решение. Вместо загрузки всего файла они обрабатывают его поэтапно:

• Node.js: Используйте JSONStream или stream-json, чтобы разбирать массив JSON по одному объекту за раз, преобразовывать каждый в строку CSV и записывать в выходной поток. Память остается постоянной независимо от размера файла.
• Python: Библиотека ijson предоставляет итеративный разбор JSON. Скомбинируйте это с csv.writer, записывающим в файловый дескриптор для постоянного преобразования в памяти.
• CLI: jq обрабатывает JSON в потоковом режиме нативно. Для преобразования JSON в CSV специально разработаны инструменты, такие как miller (mlr) и csvkit.

Практическое правило: если ваш JSON файл меньше 50 МБ, преобразование в памяти нормально. Выше этого стоит перейти на потоковый подход. Выше 1 ГБ используйте инструмент CLI, такой как miller, или специализированную платформу для обработки данных.

Выбор правильного подхода

Сценарий	Рекомендуемый подход
Быстрое одноразовое преобразование	Онлайн инструмент или конвертер браузера
Плоский JSON, небольшие файлы	Встроенная библиотека языка (модуль csv, простая функция JS)
Вложенный JSON, сложная схема	pandas.json_normalize или @json2csv с трансформацией flatten
Большие файлы (>50 МБ)	Потоковый парсер (ijson, stream-json) или CLI (miller)
Повторяющийся конвейер	Скрипт с библиотекой, интегрированный в CI/ETL

Для большинства разработчиков быстрый путь преобразования — это все, что им нужно. Вставьте JSON, получите CSV, двигайтесь дальше. Сложность имеет значение только тогда, когда данные вложенные, файлы большие или преобразование выполняется без присмотра в конвейере.

Попробуйте сами: Вставьте ваши данные JSON в наш JSON в CSV конвертер, чтобы получить чистый CSV файл за считанные секунды. Нужно сделать обратное? Используйте наш инструмент CSV в JSON.