Парсинг JSON в shell с jq

TL;DR

jq — лёгкий однобайтовый инструмент для безопасного парсинга, фильтрации и перестройки JSON в shell-скриптах. Установите jq через пакетный менеджер или скачайте бинарник, используйте jq для красивого вывода, выборки полей, фильтрации массивов и создания новых объектов из входного JSON. Ниже — примеры, шпаргалка и чек-листы для разработчиков и системных администраторов.

Быстрые ссылки

Парсинг JSON с jq
Переформатирование JSON
Альтернативы jq

Пример JSON-данных

Linux не имеет встроенного надёжного инструмента для разбора JSON, хотя многие API возвращают JSON. Этот материал показывает, как безопасно и эффективно парсить JSON в shell-скриптах с помощью небольшого и мощного утилитарного инструмента jq.

Установка jq

jq — это статически скомпилированный бинарный файл (обычно без зависимостей), поэтому установка простая.

На Debian/Ubuntu:

sudo apt update
sudo apt install jq

На macOS (Homebrew):

brew install jq

На Windows: скачайте релиз и положите бинарник в каталог в PATH или используйте пакеты для Windows/WSL.
Альтернативно: скачайте готовый бинарник и переместите в /usr/local/bin/

# пример установки вручную
curl -L -o jq https://github.com/stedolan/jq/releases/download/jq-/jq-linux64
chmod +x jq
sudo mv jq /usr/local/bin/

Важно: проверяйте версию jq --version и используйте документацию для вашей версии, так как синтаксис фильтров совместим в пределах одной мажорной версии.

Важно: не используйте текстовые инструменты (grep/sed/awk) для разбора JSON в продакшне — они ломаются при изменении структуры или экранировании.

Парсинг JSON с jq

Простейший приём — «красиво» напечатать JSON, чтобы его было удобно читать:

curl https://api.example.com/ | jq

Это форматирует и подсвечивает JSON в терминале. Полезно при отладке.

Отформатированный JSON с подсветкой синтаксиса

Фильтр . представляет входные данные. Примеры выборки ключей:

# взять поле top-level
jq '.status' file.json

# вложенные поля
jq '.data.geo.host' file.json

# опциональное свойство (не бросит ошибку, если нет)
jq '.data.geo?.host' file.json

Если нужно получить строку без кавычек, добавьте флаг -r (raw output):

jq -r '.data.ip' file.json

Работа с массивами

Индексация:

jq '.[0].name' file.json

Срезы:

jq '.[2:5]' file.json

Перебор элементов .[ ] и фильтрация:

jq '.[] | select(.name | contains("Leanne"))' file.json

select принимает любое булево выражение. Примеры:

# count >= 2
jq '.[] | select(.count >= 2)' file.json

# комбинированное условие
jq '.[] | select(.active and (.score > 50))' file.json

Практическая подсказка (mental model)

Думайте о фильтрах jq как о конвейере (pipeline) — каждый фильтр принимает JSON и возвращает JSON. . — это текущий контекст. | направляет выход одного фильтра на вход следующего. Это похоже на работу с текстом в sed/awk, но на структурированных данных.

Переформатирование и конструирование JSON

jq умеет не только читать, но и конструировать новые JSON-объекты. Оборачиваете в {} и указываете выражения для значений:

cat json | jq '.[0] | {name: .name, company: .company}'

Результат будет чистым JSON с только указанными полями:

Вывод jq: новый объект JSON

Примеры полезных преобразований:

# создать массив имён
jq '[.[] | .name]' users.json

# переименовать ключи
jq '.[] | {userName: .username, fullName: .name}' users.json

# собрать map по id
jq 'reduce .[] as $item ({}; .[$item.id] = $item)' items.json

Альтернативы jq и когда выбрать их

Сценарии на Python/Node.js — если нужен более сложный алгоритм или интеграция с библиотеками, удобнее делать парсинг в полном языке:

# пример flow: curl > файл > python-скрипт
curl https://api.example.com/ > json.txt
python process.py json.txt

Использовать yq — jq-подобный инструмент для YAML (также умеет JSON).
grep/sed/awk — годятся только для простых однотипных случаев и неструктурированных выходов; риск хрупкости велик.

Когда jq не подходит:

Нужна сложная бизнес-логика с состоянием и множественными зависимостями — лучше полноценный язык.
Очень большие JSON-файлы (много гигабайт) — рассматривайте потоковые парсеры или инструменты с поддержкой стриминга (jq имеет опции, но ресурсоёмкие операции могут быть медленными).

Частые ошибки и как их избегать

Ошибка: попытка парсить JSON как текст с grep/sed. Риск — неверные совпадения.
Ошибка: использование jq без флага -r и получение строки в кавычках.
Ошибка: доверие к порядку элементов в массиве вместо фильтрации по значению — используйте select.
Ошибка: не учитывать отсутствие ключа — используйте ? для опции или проверяйте существование.

Чек-лист по ролям

Разработчик:

Установлен jq и проверена версия
Тестовые данные в файле для отладки
Фильтры покрыты unit-тестами или сценариями

Системный администратор / SRE:

jq доступен в автоматизации (Ansible, CI) через пакетный менеджер
Ограничение прав и проверки входящих данных
Логи и обработка ошибок (exit codes)

DevOps:

[ ] Скрипты используют -r при необходимости
Большие JSON-файлы обрабатываются потоково или через разделение

Шпаргалка (cheat sheet)

# pretty print
jq '.' file.json

# raw output (без кавычек)
jq -r '.path.to.field' file.json

# фильтрация по условию
jq '.[] | select(.age > 30)' users.json

# собрать только нужные поля
jq '[.[] | {id: .id, name: .name}]' users.json

# проверка существования поля
jq 'has("key")' file.json

Тесты и критерии приёмки

Критерии приёмки:

Скрипт возвращает корректный JSON (валидный по формату) для типичных входных данных.
Скрипт не падает при отсутствии необязательных полей; вместо этого возвращает понятное значение или сообщение.
Для всех критических фильтров написаны тестовые примеры (мини-JSON) и проверены в CI.

Примеры тест-кейсов:

Вход с пустым массивом => корректный пустой результат.
Вход без поля name => поведение: пропустить элемент или вернуть null (зависит от требований).
Некорректный JSON => скрипт возвращает ненулевой код выхода и понятную ошибку.

Безопасность и производительность

Не доверяйте внешним данным: валидируйте JSON до дальнейшей обработки.
Для больших объёмов данных тестируйте производительность фильтров jq и профилируйте (возможно, лучше потоковый парсер или язык с поддержкой потоковой обработки).

Короткий итог

jq — надёжный инструмент для работы с JSON в shell. Он безопаснее и гибче, чем простые текстовые утилиты, и позволяет как извлекать данные, так и строить новые JSON-структуры. Выбирайте jq для быстрой автоматизации и отладки; при сложной логике используйте полноценные языки программирования.