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

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

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

В этой статье разберём jq по шагам: установка, базовая конфигурация, практические сценарии и ошибки, которые встречаются чаще всего.

Зачем нужен jq

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

Установка

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

sudo apt install jq

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

sudo dnf install jq

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

sudo pacman -S jq

Пошаговая настройка

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

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

5. Измените файл через временную копию

У jq нет флага редактирования на месте. Сначала запишите результат во временный файл, затем замените исходный только при успешном выполнении. Такой подход защищает конфигурацию от частично записанного результата.

tmp=$(mktemp)
jq '.version = "1.2.0"' package.json > "$tmp" && mv "$tmp" package.json

6. Разберите JSON Lines из логов

Многие приложения пишут по одному JSON-объекту на строку. jq обрабатывает такой поток без загрузки всего файла в память. Фильтр select позволяет оставить только ошибки и вывести сообщение.

jq -r 'select(.level == "error") | .message' app.log

Базовая конфигурация

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

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

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

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

Совет 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.

Совет 5. Отсутствующий ключ даёт null, поэтому проверяйте результат через // ил

Отсутствующий ключ даёт null, поэтому проверяйте результат через // или select.

Практический сценарий

Представьте типовую задачу: нужно развернуть jq на одной машине, проверить работу и передать доступ коллеге. Начните с чистой системы или снапшота, чтобы результат был воспроизводим. Запишите все команды в отдельный файл — это одновременно шпаргалка и черновик будущей автоматизации.

Дальше действуйте короткими шагами: установка, минимальная конфигурация, проверка, затем расширение. После каждого шага фиксируйте, что именно изменилось и как это проверить. Такой журнал экономит время, когда через месяц понадобится повторить настройку на другом сервере или объяснить её коллеге.

Порядок работ для этого сценария выглядит так:

  1. Прочитайте и отформатируйте JSON
  2. Выберите поля и отфильтруйте массив
  3. Получите сырой или компактный вывод
  4. Объедините несколько файлов
  5. Измените файл через временную копию
  6. Разберите JSON Lines из логов

Отдельно продумайте, что произойдёт при сбое. Для jq важно заранее знать, где хранятся данные, как их скопировать и сколько времени займёт восстановление. Если ответа нет, не двигайтесь дальше: сначала закройте этот пробел, потом добавляйте новые возможности.

Типичные ошибки

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

1. jq выдаёт parse error: Invalid numeric literal.

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

2. Ошибка Cannot index string with string.

Фильтр предполагает объект, а на этом уровне находится строка или массив. Просмотрите структуру через jq ‘type’ и скорректируйте путь.

3. Команда работает в терминале, но ломается в скрипте.

Проверьте кавычки и передачу аргументов. Фильтр jq лучше заключать в одинарные кавычки, а значения передавать через —arg.

4. jq не находит файл или читает пустой поток.

Проверьте путь и права доступа. Если вход формируется конвейером, убедитесь, что предыдущая команда завершилась успешно и что-то вывела.

Что проверить перед вводом в работу

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

Чек-лист

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

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

Итог

jq — это не «поставил и забыл». Рабочая конфигурация складывается из понимания задачи, аккуратной установки и проверки результата. Начните с базового сценария, затем добавляйте только те возможности, которые действительно используете.

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

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

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

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

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