Bash'te JSON Formatlama: jq ve python3 Rehberi

Bir dağıtım betiği API yanıtlarını işlemeye veya CI'da yapılandırma dosyalarını doğrulamaya başladığında, bash'te JSON biçimlendirmeyi bilmek hızla vazgeçilmez hale gelir. Gerçek dünya vakalarının %99'unu kapsayan iki araç jq ve python3 -m json.tool'dur — her ikisi de json bash biçimlendirme ardışık düzenlerini güvenilir şekilde çalıştırabilir, çıkış kodlarıyla doğrulayabilir ve CI/CD iş akışlarına temiz şekilde entegre olabilir. Terminal olmadan tek seferlik inceleme için tarayıcı tabanlı JSON Biçimleyici anında işlem yapar. Bu kılavuz jq kurulumunu, boru hattı ve dosya biçimlendirmeyi, doğrulama işlevlerini, GitHub Actions'da CI/CD entegrasyonunu, ön-commit kancalarını, heredoc kalıplarını ve Python stdlib yedeğine ne zaman başvuracağınızı kapsar.

Bash'te JSON Biçimlendirme Nedir?

Bash'te JSON biçimlendirme, kompakt, küçültülmüş JSON'u girintili, insan tarafından okunabilir çıktıya dönüştürmek anlamına gelir. Temel veriler değişmez — yalnızca boşluklar ve satır sonları farklılık gösterir. Betik bağlamlarında bu iki nedenden önemlidir: hata ayıklarken okunabilirlik ve biçimlendirici sözdizimini yan etki olarak iki kez kontrol ettiğinde doğrulama. jq gibi araçlar yeniden biçimlendirmeden önce JSON'u tam olarak ayrıştırır; bu da başarılı bir biçimlendirme çalışmasının aynı zamanda örtük bir geçerlilik denetimi olduğu anlamına gelir. Bu çift davranış — bir adımda biçimlendir ve doğrula — jq'yu otomatik ardışık düzenlerde bu kadar kullanışlı kılan şeydir.

{"service":"payments-api","version":"2.4.1","database":{"host":"db-prod-01.internal","port":5432,"pool_size":20},"cache":{"enabled":true,"ttl":300}}

{
  "service": "payments-api",
  "version": "2.4.1",
  "database": {
    "host": "db-prod-01.internal",
    "port": 5432,
    "pool_size": 20
  },
  "cache": {
    "enabled": true,
    "ttl": 300
  }
}

jq — Bash'te JSON Biçimlendirme

jq, kabuk betiklerinde JSON işlemenin fiili standardıdır (jq 1.6+, bash 4+). JSON'u biçimlendirebilen, filtreleyebilen, dönüştürebilen ve doğrulayabilen amaç odaklı bir komut satırı JSON işlemcisidir. Kimlik filtresi . girişi değiştirmeden ama biçimlendirerek geçirir. jq girişi ayrıştıramadığında 1 koduyla çıkar — bu onu betik yazmak için ideal kılar: biçimlendirme ve doğrulama tek bir işlemdir.

jq'yu kur

# macOS
brew install jq

# Debian / Ubuntu
apt-get install -y jq

# Fedora / RHEL / CentOS
dnf install jq

# Alpine (Docker imajları)
apk add --no-cache jq

# Doğrula
jq --version  # jq-1.7.1

Stdin'den ve dosyadan biçimlendirme

# Satır içi JSON'u jq üzerinden aktar
echo '{"host":"db-prod-01.internal","port":5432}' | jq .

# Bir dosyayı doğrudan biçimlendir (stdout'a yazdırır)
jq . config/feature-flags.json

# 4 boşluk girintiyle biçimlendir
jq --indent 4 . config/feature-flags.json

# Boşluk yerine sekme kullanarak biçimlendir
jq --tab . config/feature-flags.json

Biçimlendirilmiş çıktıyı dosyaya yaz

# Biçimlendirilmiş çıktıyı kaydet (aynı dosyaya geri YÖNLENDIRME)
jq . compact.json > formatted.json

# Kompakt (küçült) — biçimlendirmenin tersi
jq -c . formatted.json

Anahtarları sırala ve rengi kaldır

# Tüm anahtarları alfabetik olarak sırala (deterministik farklar için kullanışlı)
jq --sort-keys . config/app-config.json

# Bir günlük dosyasına yazarken renk çıktısını devre dışı bırak
jq --monochrome-output . response.json >> deploy.log

jq Seçenekleri Referansı

Biçimlendirme ve doğrulama iş akışları için en yaygın kullanılan jq bayrakları:

Bash Betiğinde JSON Doğrulama

Doğrulama ve biçimlendirme jq'da aynı işlemdir — yazdırmadan önce ayrıştırır. Biçimlendirilmiş çıktı olmadan yalnızca çıkış kodunu istediğinizde stdout'u /dev/null'a yönlendirin. Aşağıdaki kalıp dağıtım betiklerinde, ön-commit kancalarında ve CI ardışık düzenlerinde yeniden kullanılabilir. Olay müdahalesinde, tanımadığım bir API yükü ile karşılaştığımda ilk yaptığım şey onu jq üzerinden aktarmaktır — küçültülmüş JSON duvarını gerçekten okuyup hata ayıklayabileceğim bir şeye dönüştürür.

Yeniden kullanılabilir doğrulama işlevi

validate_json() {
  local file="$1"
  if jq . "$file" > /dev/null 2>&1; then
    echo "✓ Geçerli JSON: $file"
    return 0
  else
    echo "✗ Geçersiz JSON: $file" >&2
    return 1
  fi
}

Geçersiz yapılandırmada dağıtımı durdur

CONFIG="infra/k8s/app-config.json"
validate_json "$CONFIG" || { echo "Dağıtım iptal edildi: geçersiz yapılandırma" >&2; exit 1; }

Bir dizindeki tüm JSON dosyalarını doğrula

find ./config -name "*.json" | while read -r f; do
  jq . "$f" > /dev/null 2>&1 || echo "GEÇERSİZ: $f"
done

Dosyalardan ve API Yanıtlarından JSON Biçimlendirme

Kabuk betiklerinde JSON'un iki yaygın kaynağı disk üzerindeki dosyalar ve curl aracılığıyla HTTP API yanıtlarıdır. Her birinin biraz farklı bir işleme kalıbı vardır. Dosyalar için temel endişe güvenli yerinde düzenlemedir. API yanıtları için önemli ayrıntı, curl'ün ilerleme çubuğunu bastırmaktır, böylece jq'nun girişini bozmaz.

Bir dosyanın güvenli yerinde biçimlendirmesi

# Geçici dosya kullanarak güvenli biçimlendir ve üzerine yaz
tmp=$(mktemp)
jq --indent 2 . config/feature-flags.json > "$tmp" && mv "$tmp" config/feature-flags.json
echo "config/feature-flags.json biçimlendirildi"

Bir curl API yanıtını biçimlendir

# API'den dağıtım durumunu biçimlendir
DEPLOY_ID="dep_8f3a2b9c"
curl -s \
  -H "Authorization: Bearer $DEPLOY_API_TOKEN" \
  "https://api.deployments.internal/v1/deploys/$DEPLOY_ID" \
  | jq --indent 2 .

Aynı anda biçimlendir ve filtrele

# Bir izleme uç noktasından biçimlendirilmiş + yalnızca hatalara filtrele
curl -s "https://monitoring.internal/api/events?level=error&limit=10" \
  | jq '[.events[] | {id, message, timestamp, service}]' \
  || { echo "Olaylar alınamadı veya ayrıştırılamadı" >&2; exit 1; }

|| { ... } kalıbı burada kritiktir. Olmadan, başarısız bir curl veya hatalı biçimlendirilmiş bir API yanıtı sessizce geçer ve betiğinizdeki bir sonraki adım boş veya kısmi veriler üzerinde çalışır. Önce bir filtre ifadesi yazmadan karmaşık iç içe yanıtları incelemeniz gerekiyorsa, tarayıcı tabanlı JSON Biçimleyici ham yanıtı yapıştırmanıza ve ağacı etkileşimli olarak gezinmenize olanak tanır.

CI/CD Ardışık Düzenlerinde JSON Biçimlendirme

CI, JSON doğrulama kapılarının en çok önem taşıdığı yerdir — üretime ulaşan hatalı biçimlendirilmiş bir yapılandırma, bir ardışık düzen hatasından çok daha ağrılıdır. Çoğu rakip jq'yu tek seferlik terminal kullanımı için belgelemiştir; aşağıdaki kalıplar, yapılandırma hatalarını bir dağıtım yuvasına ulaşmadan önce yakalamak için üretim SRE iş akışlarında kullandıklarımdır.

GitHub Actions — tüm JSON yapılandırmalarını doğrula

- name: JSON yapılandırmalarını doğrula
  run: |
    echo "JSON yapılandırma dosyaları doğrulanıyor..."
    find . -name "*.json" -not -path "*/node_modules/*" | while read -r f; do
      if ! jq . "$f" > /dev/null 2>&1; then
        echo "::error file=$f::Geçersiz JSON sözdizimi"
        exit 1
      fi
    done
    echo "Tüm JSON dosyaları geçerli"

Ön-commit kancası — aşamalı JSON dosyalarını doğrula

#!/usr/bin/env bash
set -euo pipefail
STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep '\.json$' || true)
[ -z "$STAGED" ] && exit 0
for f in $STAGED; do
  jq . "$f" > /dev/null 2>&1 || { echo "Geçersiz JSON: $f"; exit 1; }
done
echo "JSON doğrulama başarılı"

Bash'te JSON Değişkenlerini ve Heredoc'ları Biçimlendirme

Kabuk betikleri genellikle dinamik olarak JSON yükleri oluşturur — ortam değişkenlerinden, git meta verilerinden veya hesaplanan değerlerden. En güvenli kalıp, bir değer tırnak veya yeni satır içerdiği anda bozulan dize enterpolasyonu yerine jq -n --arg / --argjson'dur. JSON'daki boşluklarda sözcük bölünmesini önlemek için jq'ya aktarırken değişkenleri her zaman çift tırnak içine alın.

Depolanmış bir API yanıtı değişkenini biçimlendir

# "$API_RESPONSE"'ı her zaman tırnak içine alın — JSON'daki boşluk tırnak içine alınmamış genişlemeyi bozar
echo "$API_RESPONSE" | jq --indent 2 .

jq -n ile bir yük oluştur ve biçimlendir

payload=$(jq -n \
  --arg env "production" \
  --arg version "$(git describe --tags)" \
  --argjson replicas 3 \
  '{environment: $env, version: $version, replicas: $replicas}')

# Oluşturulan yükü incele
echo "$payload" | jq .

# Bir API'ye gönder
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEPLOY_API_TOKEN" \
  -d "$payload" \
  "https://api.deployments.internal/v1/deploys"

jq Kurmadan Bash'te JSON Biçimlendirme

jq mevcut olmadığında — minimal Docker imajları, kilitli CI çalıştırıcıları veya paket yükleyemediğiniz sistemler — Python'un yerleşik json.tool modülü aynı temel işlevselliği sağlar. Python standart kütüphanesinin bir parçasıdır; Python 3 kuruluysa ek bağımlılık olmadan çalışır.

# Dosyadan biçimlendir
python3 -m json.tool config.json

# Girinti genişliğini kontrol et
python3 -m json.tool --indent 2 config.json

# Anahtarları alfabetik olarak sırala
python3 -m json.tool --sort-keys config.json

# Stdin'den biçimlendir (örn. curl'den aktarılan)
curl -s https://api.deployments.internal/v1/status | python3 -m json.tool

# Çıkış koduyla doğrulama (jq ile aynı semantik)
python3 -m json.tool config.json > /dev/null && echo "geçerli" || echo "geçersiz"

# Satır içi dize doğrulama
echo '{"service":"payments-api","healthy":true}' | python3 -m json.tool > /dev/null
echo "Çıkış kodu: $?"  # 0 = geçerli

Sözdizimi Vurgulamalı Terminal Çıktısı

jq varsayılan olarak çıktısını renklendirir — anahtarlar mavi, dizeler yeşil, sayılar beyaz. Kaydırılabilir bir sayfalayıcıda tam JSON sözdizimi vurgulamasına ihtiyaç duyduğunuzda veya bir terminal oturumunda büyük iç içe geçmiş yanıtlarda hata ayıklarken, bat en ergonomik deneyimi sağlar. Her ikisi de hata ayıklama ve etkileşimli inceleme için kullanışlıdır; hiçbiri dosyalara veya API yanıtlarına çıktı yazarken kullanılmamalıdır.

bat'ı kur

# macOS
brew install bat

# Debian / Ubuntu (ikili batcat olarak adlandırılabilir — gerekirse takma ad ekleyin)
apt-get install -y bat
# alias bat=batcat   # gerekirse ~/.bashrc'ye ekleyin

# Doğrula
bat --version  # bat 0.24.0

Sözdizimi vurgulamasıyla JSON dosyalarını görüntüle

# Sayfalayıcıda sözdizimi vurgulu JSON (çıkmak için q'ya basın)
bat config/app-config.json

# Sayfalamayı devre dışı bırak — doğrudan terminale yazdır
bat --paging=never config/app-config.json

# jq çıktısını renkli inceleme için bat üzerinden aktar
jq '.database' infra/app-config.json | bat --language=json --paging=never

Kaydırılabilir sayfalayıcıda renklendirilmiş jq çıktısı

# -C stdout tty olmadığında bile rengi zorlar (örn. less'e aktarırken)
jq -C . logs/deploy-response.json | less -R

Bash'te Büyük JSON Dosyalarıyla Çalışma

Bir JSON dosyası 50–100 MB'ı aştığında, jq'nun varsayılan moduyla belleğe yüklemek yavaş olabilir veya bellek kısıtlamalı ana bilgisayarlarda OOM'u tetikleyebilir (örneğin 512 MB sınırlı Docker kapsayıcıları). jq --stream, tüm belgeyi arabelleğe almadan okurken artımlı olarak yol/değer çiftleri yayar. NDJSON için (satır başına bir JSON nesnesi), jq'nun daha verimli yerel bir yaklaşımı vardır.

jq --stream ile büyük bir JSON dosyasını akıt

# --stream, jq girişi okurken [yol, skaler] çiftleri yayar
# Tam olarak yüklemeden büyük bir günlük arşivinden tüm "status" alanlarını çıkar
jq -c --stream   'if length == 2 and (.[0][-1] == "status") then .[1] else empty end'   logs/archive-2026-03.json

NDJSON / JSON Lines — satır başına bir nesne işle

# NDJSON: satır başına bir JSON nesnesi — Kafka dışa aktarımlarında, Fluentd ve Logstash'te yaygın
# -R ham satırları okur; fromjson? geçerli JSON olmayan satırları atlar
jq -c -R 'fromjson? | {id: .request_id, status: .http_status, latency: .duration_ms}'   logs/access-2026-03-13.ndjson > logs/summary.ndjson

# Kabuk döngüsü alternatifi — satır başına hata işlemeye ihtiyaç duyduğunuzda kullanışlı
while IFS= read -r line; do
  echo "$line" | jq -c '{id: .request_id, status: .http_status}' 2>/dev/null ||     echo "ATLA: hatalı biçimlendirilmiş satır" >&2
done < logs/access-2026-03-13.ndjson

Yaygın Hatalar

jq --indent 2 . settings.json > settings.json

tmp=$(mktemp) && jq --indent 2 . settings.json > "$tmp" && mv "$tmp" settings.json

jq . response.json > formatted.json

jq . response.json > formatted.json || { echo "response.json içinde geçersiz JSON" >&2; exit 1; }

curl https://api.payments.internal/config | jq .

curl -s https://api.payments.internal/config | jq .

jq -r . config.json

jq . config.json

jq vs python3 vs json_pp — Hızlı Karşılaştırma

Araçlar arasında seçim yapmak, ortamınızda nelerin mevcut olduğuna ve temel biçimlendirmenin ötesinde neye ihtiyacınız olduğuna bağlıdır:

Çoğu bash betik yazımı ve CI/CD çalışması için jq doğru varsayılandır — tek bir ikili dosyada çalışma zamanı bağımlılığı olmadan doğrular, biçimlendirir, filtreler ve güvenilir çıkış kodları sağlar. Ek paket yükleyemediğinizde ve Python zaten mevcutsa python3 -m json.tool'a geri dönün.

Sık Sorulan Sorular

tmp=$(mktemp)
jq --indent 2 . config/app-config.json > "$tmp" && mv "$tmp" config/app-config.json
echo "Yerinde başarıyla biçimlendirildi"

validate_json() {
  local file="$1"
  if jq . "$file" > /dev/null 2>&1; then
    echo "✓ Geçerli JSON: $file"
    return 0
  else
    echo "✗ Geçersiz JSON: $file" >&2
    return 1
  fi
}

validate_json infra/k8s/app-config.json || exit 1

# Dosyadan biçimlendir
python3 -m json.tool config.json

# Stdin'den biçimlendir (örn. bir curl yanıtı)
curl -s https://api.internal/status | python3 -m json.tool --indent 2

DEPLOY_ID="dep_8f3a2b9c"
curl -s \
  -H "Authorization: Bearer $DEPLOY_API_TOKEN" \
  "https://api.deployments.internal/v1/deploys/$DEPLOY_ID" \
  | jq --indent 2 .

# Yalnızca veritabanı yapılandırma bloğunu biçimlendir
jq --indent 2 '.database' infra/app-config.json

# Biçimlendir + olaylar dizisini yalnızca hata düzeyine filtrele
jq '[.events[] | select(.level == "error") | {id, message, service}]' events.json

# Çıkış kodunu doğrudan test et
echo '{"ok":true}' | jq . > /dev/null 2>&1; echo "exit: $?"  # exit: 0
echo '{bad json}' | jq . > /dev/null 2>&1; echo "exit: $?"   # exit: 1

# -e bayrağı: çıktı false/null ise 1 ile çık
echo 'null' | jq -e . > /dev/null 2>&1; echo "exit: $?"      # exit: 1

İlgili Araçlar

Bash JSON biçimlendirmeye tarayıcı tabanlı alternatifler ve tamamlayıcılar — görsel bir arayüze, paylaşılabilir bir bağlantıya ihtiyaç duyduğunuzda veya terminal dışında çalışırken kullanışlıdır: