How to Format JSON: Methods, Tools & Best Practices

Почему форматирование JSON имеет значение

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

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

Форматирование также предотвращает тонкие ошибки. Когда JSON минифицирован, легко пропустить неправильно расположенную скобку или дублированный ключ. Расширение структуры делает эти проблемы более заметными.

Правила форматирования JSON

Прежде чем хвататься за инструмент, полезно понять, что на самом деле означает "отформатированный JSON". Спецификация JSON (RFC 8259) не требует никаких правил пробелов — форматирование является чисто вопросом представления. Тем не менее, сообщество пришло к четким соглашениям:

• Каждая пара ключ-значение находится на своей строке.
• Вложенные объекты и массивы отступают на один уровень глубже, чем их родитель.
• После ключа следует двоеточие, разделенное одним пробелом: “key”: “value”.
• Запятые появляются в конце каждой строки (не в начале).
• Открывающие фигурные скобки и квадратные скобки остаются на одной строке с ключом; закрывающие выравниваются с уровнем отступа родителя.

Вот минимальный пример. Этот минифицированный JSON:

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

Становится таким, когда отформатирован с отступом в 2 пробела:

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

3 способа форматирования JSON

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

1. Онлайн-инструменты

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

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

Попробуйте сами: Вставьте любой JSON в наш JSON Formatter, чтобы мгновенно украсить его по вашему выбору отступов.

2. Инструменты командной строки

Если вы живете в терминале, две команды покрывают почти все потребности в форматировании:

Встроенный модуль json.tool Python — доступен на любой машине с установленным Python, дополнительные пакеты не требуются:

echo '{"name":"Alice","age":30}' | python -m json.tool

Это выводит красиво отформатированный JSON в stdout. Вы можете так же легко передать файл через него:

python -m json.tool data.json > data-formatted.json

jq — легковесный, специально созданный процессор JSON. Самая простая команда форматирования — это просто фильтр идентичности:

cat data.json | jq '.'

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

Обе команды могут быть связаны в CI конвейерах. Например, вы можете запустить jq --sort-keys . в хуке перед коммитом, чтобы убедиться, что все JSON конфигурационные файлы в репозитории отформатированы последовательно.

3. Программное форматирование

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

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

Третий аргумент для JSON.stringify управляет отступами. Передайте 2 для 2 пробелов, 4 для 4 пробелов или "\t" для табуляции.

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

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

Сравнение подходов к форматированию

Вот краткая справка, которая поможет вам выбрать правильный метод для ситуации:

Критерии	Онлайн инструмент	CLI (jq / json.tool)	Программное
Простота использования	Вставить и нажать	Однострочная команда	Требует контекста кода
Скорость для одноразовых задач	Самая быстрая	Быстрая	Медленнее (нужен скрипт)
Автоматизация / CI	Не подходит	Отлично	Отлично
Настройка	Ограниченная	Умеренная (флаги)	Полный контроль
Работает офлайн	Нет	Да	Да
Обрабатывает большие файлы	Ограничения браузера	Хорошо работает с потоками	Зависит от реализации

Дебаты о отступах: 2 пробела против 4 пробелов против табуляции

Это одна из тех дискуссий, которая вызывает больше споров, чем ясности, но есть практические причины предпочесть каждый вариант.

2 пробела

Наиболее распространенный выбор в JSON. Он сохраняет компактность глубоко вложенных структур, при этом обеспечивая четкую визуальную иерархию. Большинство инструментов экосистемы JavaScript (ESLint, Prettier, package.json npm) по умолчанию используют 2 пробела. Если вы работаете с веб-API или проектами Node.js, это безопасный стандарт.

4 пробела

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

Табуляция

Табуляция позволяет каждому разработчику устанавливать свою собственную визуальную ширину в своем редакторе. Это звучит идеально в теории, но на практике большинство инструментов JSON и линтеров ожидают пробелы. Табуляция также отображается непоследовательно в веб-диффах и PR на GitHub.

Когда использовать каждый:

• 2 пробела — веб-проекты, кодовые базы JavaScript/TypeScript, полезные нагрузки API. Стандарт сообщества.
• 4 пробела — команды с преобладанием Python, большие конфигурационные файлы, где ясность важнее компактности.
• Табуляция — монорепозитории с смешанными языковыми предпочтениями и строгими требованиями к доступности (табуляция позволяет настраивать ширину пользователем).

Самое важное — это последовательность в рамках проекта. Выберите один и соблюдайте его.

Сортировка ключей

Большинство форматтеров предлагают опцию "сортировать ключи", которая алфавитно упорядочивает ключи объектов. Это не просто косметика — у этого есть реальные преимущества для контроля версий.

Когда ключи отсортированы, различия становятся значимыми. Без сортировки два разработчика могут добавить одни и те же ключи в разном порядке, создавая шумные различия, которые затмевают фактические изменения. Отсортированные ключи полностью устраняют это.

Отсортированные ключи также упрощают просмотр больших конфигурационных файлов. Если вы знаете, какой ключ ищете, вы можете перейти к его алфавитной позиции, не ища.

Единственное предостережение: некоторые JSON-файлы имеют преднамеренный порядок ключей (например, package.json, где name и version идут первыми по соглашению). В таких случаях сохраните оригинальный порядок.

В jq отсортируйте ключи с помощью:

jq --sort-keys '.' data.json

В JavaScript передайте функцию замены или используйте библиотеку, такую как json-stable-stringify, для детерминированного порядка ключей.

Автоформатирование при сохранении в VS Code

Лучшее форматирование — это то, о чем вы никогда не думаете. VS Code может автоматически форматировать JSON-файлы каждый раз, когда вы сохраняете. Вот как это настроить:

Шаг 1: Откройте свои настройки (Cmd+, на macOS, Ctrl+, на Windows/Linux) и добавьте следующие записи:

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

Шаг 2: Установите расширение Prettier - Code formatter, если вы еще этого не сделали. Оно обрабатывает форматирование JSON вместе со всеми другими языками в вашем проекте.

Шаг 3: Создайте файл .prettierrc в корне вашего проекта, чтобы стандартизировать настройки для всей команды:

{
  "tabWidth": 2,
  "useTabs": false
}

Теперь каждый JSON-файл в проекте будет форматироваться одинаково, независимо от того, кто его редактировал. Больше никаких различий только в форматировании в запросах на слияние.

Обработка крайних случаев

Большинство инструментов форматирования обрабатывают стандартный JSON без проблем, но несколько ситуаций могут вас подвести:

• Большие числа — JSON не различает целые числа и числа с плавающей запятой. Некоторые форматтеры могут переформатировать 1.0 как 1 или потерять точность при очень больших целых числах. Если точность важна, проверьте вывод.
• Юникодные экраны — форматтер может преобразовать \u00e9 в буквенный символ é или наоборот. Оба являются действительным JSON, но изменение может вызвать неожиданные различия.
• Пустые объекты и массивы — некоторые форматтеры расширяют {} на несколько строк. Другие сохраняют их компактными. Это вопрос стиля, но имейте в виду, что это может варьироваться между инструментами.
• Конечная новая строка — POSIX-конвенция гласит, что текстовые файлы должны заканчиваться новой строкой. Большинство форматтеров добавляют одну, но не все. Проверьте ваш .editorconfig, если это важно для вашего CI.

Форматирование как часть вашего рабочего процесса

Самые эффективные команды рассматривают форматирование JSON так же, как и форматирование кода — как автоматизированную, не подлежащую обсуждению часть процесса разработки.

Предкоммитные хуки: Используйте инструмент, такой как husky с lint-staged, чтобы запускать Prettier или jq на JSON-файлах перед каждым коммитом. Это позволяет выявлять проблемы с форматированием до их попадания в кодовую базу.

Проверки CI: Добавьте проверку форматирования в ваш CI-конвейер, которая не пройдет, если какие-либо JSON-файлы не отформатированы должным образом. У Prettier есть флаг --check именно для этой цели.

Интеграция редактора: Форматирование при сохранении полностью устраняет ручное форматирование. В сочетании с общим конфигурационным файлом это гарантирует, что каждый член команды производит идентичный вывод.

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

Попробуйте сами: Вставьте неформатированный JSON в наш JSON Formatter, чтобы мгновенно украсить его. Вы также можете проверить ваш JSON, чтобы поймать структурные ошибки перед форматированием.