Коротко о главном

JSON встречается в API, конфигурациях, логах и выводе облачных утилит. jq превращает его в удобный поток данных, который можно фильтровать и агрегировать. В статье разберём выборку полей, работу с массивами, безопасное редактирование и разбор JSON Lines. Материал рассчитан на разработчиков и администраторов с базовым опытом терминала.

Ручной просмотр JSON быстро становится неудобным при большой вложенности. jq даёт точный доступ к нужным полям и позволяет строить компактные отчёты. Скрипты с jq легче автоматизировать и проверять, чем разбор через регулярные выражения. Инструмент также помогает диагностировать API и конфигурации.

Этот материал — быстрый старт по jq. За 15 минут вы получите рабочую конфигурацию и поймёте, куда смотреть дальше.

Установка

В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:

sudo apt install jq

В Fedora и RHEL-совместимых системах пакет ставится через DNF:

sudo dnf install jq

В Arch Linux и производных пакет доступен в официальных репозиториях:

sudo pacman -S jq

Минимальная настройка

1. Прочитайте и отформатируйте JSON

Фильтр . возвращает документ без изменений, а jq печатает его с отступами. Это удобно для проверки структуры после ответа API. Если файл содержит несколько JSON-документов, поведение нужно проверять отдельно.

jq '.' package.json

2. Выберите поля и отфильтруйте массив

Точечная нотация обращается к ключам, а квадратные скобки выбирают элементы массива. Функция select оставляет объекты, удовлетворяющие условию. Комбинируйте фильтры через вертикальную черту.

jq '.dependencies | keys[]' package.json
jq '.items[] | select(.active)' data.json

3. Получите сырой или компактный вывод

Флаг -r убирает JSON-кавычки у строк, что удобно для shell-переменных. Флаг -c печатает документ в одну строку. Сырой вывод безопасен только тогда, когда вы контролируете формат данных.

jq -r '.name' package.json
jq -c '.scripts' package.json

4. Объедините несколько файлов

Флаг -s собирает все входные документы в один массив. После этого можно применить map и извлечь нужные поля. Это полезно для отчётов по нескольким ответам API.

jq -s 'map(.id)' a.json b.json

Минимальный конфиг

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

# ~/.jq
def compact: with_entries(select(.value != null));
def only_keys: keys | sort;

Шпаргалка по командам

  • Прочитайте и отформатируйте JSON: jq ‘.’ package.json
  • Выберите поля и отфильтруйте массив: jq ‘.dependencies | keys[]’ package.json
  • Получите сырой или компактный вывод: jq -r ‘.name’ package.json
  • Объедините несколько файлов: jq -s ‘map(.id)’ a.json b.json
  • Измените файл через временную копию: tmp=$(mktemp)
  • Разберите JSON Lines из логов: jq -r ‘select(.level == «error») | .message’ app.log

Практические советы

Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.

Совет 1. Используйте —arg name value для безопасной передачи строк из оболочки

Используйте —arg name value для безопасной передачи строк из оболочки вместо ручной сборки JSON.

Совет 2. Флаг -e возвращает ненулевой код, если результат равен false или null;

Флаг -e возвращает ненулевой код, если результат равен false или null; это удобно в проверках.

Совет 3. Флаг -S сортирует ключи и делает вывод стабильным для сравнения файлов

Флаг -S сортирует ключи и делает вывод стабильным для сравнения файлов.

Совет 4. Функция del удаляет поле: jq ‘del(.secret)’ config.json.

Функция del удаляет поле: jq ‘del(.secret)’ config.json.

Что дальше

Быстрый старт не означает «настроить навсегда». Когда базовый сценарий заработает, вернитесь к конфигурации и проверьте, что она переживёт перезагрузку: файлы на месте, служба включена в автозагрузку, путь к данным не зависит от текущего каталога.

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

Чек-лист

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

Короткие ответы на частые вопросы

Нужно ли запускать всё от root?

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

Что делать, если после перезагрузки ничего не работает?

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

Как обновлять без сюрпризов?

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

Рабочие сценарии

Начните со справки: у jq обычно есть страница man и примеры в описании. Затем повторите типичные операции на тестовых данных, а не на рабочих файлах.

man jq 2>/dev/null | head -40
jq --help 2>&1 | tail -30
# подготовить тестовые данные
mkdir -p /tmp/jq-test && cd /tmp/jq-test
printf 'alpha\nbeta\ngamma\n' > sample.txt

Фиксируйте рабочие команды в заметках или шпаргалке: так вы не будете заново искать синтаксис через месяц.

Итог

Этого достаточно, чтобы начать. Дальше углубляйтесь по мере задач: документация jq станет понятнее, когда появится реальный сценарий использования.

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка 0 / 5. Количество оценок: 0

Оценок пока нет. Поставьте оценку первым.

Поделиться: Telegram ВКонтакте