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

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

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

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

Что меняется в рабочей среде

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

Базовая установка

Установка

В 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

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

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

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

Конфигурация для повторяемого развёртывания

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

# ~/.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.

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

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

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

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

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

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

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

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

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

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

Итог

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

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

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

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

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

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