Editory, příkazový řádek a automatizační nástrojové řetězce

Stručně: editor volte podle scénáře – CodeMirror 6 pro utilitní weby a mobil, Monaco jen když potřebujete plnohodnotný zážitek IDE; dávkovou práci nechte na jq plus třem kontrolám CI pro syntaxi, strukturu a styl a argumenty vždy předávejte pomocí jq --arg.

Éra ruční kontroly JSON by měla skončit: co stroj dokáže zopakovat, nenechávejte lidskému oku.

1. Editory v prohlížeči

1.1 Minimální integrace CodeMirror 6

复制import { EditorView, basicSetup } from 'codemirror';
import { json, jsonParseLinter } from '@codemirror/lang-json';
import { linter, lintGutter } from '@codemirror/lint';

const view = new EditorView({
  parent: document.getElementById('editor')!,
  doc: '{"hello": "json"}',
  extensions: [
    basicSetup,
    json(),
    linter(jsonParseLinter()),
    lintGutter(),
    EditorView.updateListener.of((update) => {
      if (update.docChanged) {
        // Před těžkou prací debounce; neformátujte při každém stisku klávesy
        scheduleParse(update.state.doc.toString());
      }
    }),
  ],
});

Čtyři body k zapamatování:

1. json() poskytuje zvýrazňování syntaxe a párování závorek – nepište si vlastní;
2. jsonParseLinter() produkuje značky chyb na úrovni řádku a sloupce; spárujte ho s lintGutter(), aby se ikony zobrazovaly vedle čísel řádků;
3. updateListener musí být debouncovaný; volání JSON.parse na sto tisících řádcích při každém stisku klávesy viditelně zpozdí aplikaci;
4. Velké dokumenty vyžadují optimalizace nad rámec EditorView.lineWrapping, aby se celý obsah nevykresloval najednou (CodeMirror 6 ve výchozím nastavení vykresluje podle viewportu, což je oproti starším verzím zlepšení).

1.2 Skládání a osnovy

CodeMirror 6 má vestavěné skládání; v JSON scénářích obvykle skládáte podle „objekt/pole“:

复制import { foldGutter, foldKeymap } from '@codemirror/language';
import { keymap } from '@codemirror/view';

S foldGutter() a keymap.of(foldKeymap) mohou uživatelé sbalit dlouhá pole klávesovou zkratkou.

1.3 Volba mezi CodeMirror a Monaco

Utilitní weby a mobile-first → CodeMirror; plnohodnotný zážitek IDE (více souborů, přechod na definici, dokončování) → Monaco.

2. Příkazový řádek: šest častých receptů jq

jq je pro JSON to, co jsou sed + awk pro text; naučit se jen malou část jeho syntaxe pokrývá osmdesát procent každodenních potřeb.

复制# 1. Výběr polí (nejčastější)
jq '.data.items[].name' response.json

# 2. Filtrování + přetvoření
jq '.data.items[] | select(.price < 10) | {id, price}' response.json

# 3. Agregace (length, sum, max)
jq '[.items[] | .price] | {count: length, total: add, max: max}' response.json

# 4. Seskupení a agregace
jq '[.items[]] | group_by(.category) | map({category: .[0].category, count: length})' response.json

复制# 5. Sloučení více souborů do pole
jq -s '.' part-*.json > merged.json

# 6. Zpracování JSON Lines řádek po řádku
jq -c 'select(.level == "error")' app.jsonl

# Běžné přepínače výstupu
jq -r '.data.name'      # Odstraní uvozovky, aby se výstup mohl čistě předat shellu
jq -c '.'               # Kompaktní výstup, jeden řádek
jq --arg id "$ID" '.id == $id'   # Bezpečné předání argumentu, bez injection přes skládání

--arg si zaslouží zvláštní zmínku: přímé vložení proměnné do výrazu se rozbije, jakmile hodnota obsahuje uvozovky, zatímco --arg nechá escapování na jq.

2.1 Další nástroje na jednom místě

Myšlenka za gron stojí za poznání:

复制$ echo '{"a":{"b":[1,2]}}' | gron
json = {};
json.a = {};
json.a.b = [];
json.a.b[0] = 1;
json.a.b[1] = 2;

Po zploštění může grep cestu najít, což je mnohem rychlejší než rozbalování úroveň po úrovni v editoru.

3. Tři vrstvy validace v CI

复制# Syntaxe: dávková validace každého souboru json v repozitáři
find . -name '*.json' -not -path './node_modules/*' -print0 \
  | xargs -0 -n1 jq empty

# Struktura: validace proti schématu
npx ajv-cli validate -s schemas/order.json -d 'fixtures/orders/*.json' --strict=false

# Styl: jen kontrola, žádné úpravy
npx prettier --check "**/*.json"

Potřebujete všechny tři vrstvy, protože jejich chybové zprávy jsou zcela odlišné: jq empty jen řekne „který řádek je rozbitý“, ajv řekne „které pole porušuje které klíčové slovo“ a Prettier jen řekne „formátování je nekonzistentní“.

4. Háčky pre-commit

复制# Příklad .husky/pre-commit (výňatek)
npx lint-staged

复制{
  "lint-staged": {
    "*.json": ["prettier --write", "jq empty"]
  }
}

Pozor na konfigurační soubory nástrojů jako package.json a tsconfig.json; nenechte Prettier, aby je svévolně znovu odsazoval – některé nástroje jsou citlivé na formátování (platný JSON být nemá, ale v praxi to problémy způsobilo). Můžete je jednotlivě vyloučit.

5. Tipy pro ladění

1. Používejte jq -e jako assertion: návratový kód je 1, když je výsledek výrazu false nebo null, takže se dá rovnou zařadit do skriptů jako kontrola;
2. jq 'paths' vypíše všechny cesty, což vám dá rychlý přehled o struktuře neznámého dokumentu;
3. jq '.. | objects | keys' najde každý název klíče, který se kdy objevil, což se hodí pro lov nekonzistentního zápisu;
4. Formátujte před srovnáním v editoru: neformátovaný diff je čistý šum; strukturální srovnání jako /diff je přesnější.

6. Kontrolní seznam

• [ ] Značky chyb v editoru jsou přesné na řádek a sloupec a parsování je debouncované;
• [ ] Týmové skripty předávají argumenty pomocí jq --arg, místo aby skládaly řetězce;
• [ ] CI má všechny tři validační vrstvy (syntaxe/struktura/styl);
• [ ] pre-commit zpracovává jen staged soubory, aby úplný sken nezdržoval commity;
• [ ] Verze nástrojů jsou zafixované v package.json nebo .tool-versions.

Časté dotazy

Jak se rozhodnout mezi CodeMirror 6 a Monaco?

Pro utilitní weby a mobil preferujte CodeMirror 6: je malý, modulární a dobře podporovaný na mobilu a zvýrazňování syntaxe, párování závorek a skládání lze skládat podle potřeby. Monaco sáhněte jen tehdy, když potřebujete plnohodnotný zážitek IDE s více soubory, přechodem na definici a dokončováním – za cenu několika megabajtového balíčku a vyššího úsilí o přizpůsobení.

Proč CI potřebuje kontrolu syntaxe, struktury a stylu společně?

Tři vrstvy hlásí zcela odlišné chyby: jq empty řekne, který řádek je rozbitý, ajv řekne, které pole porušuje které klíčové slovo, a Prettier jen řekne, že formátování je nekonzistentní. Vypuštění jedné vrstvy činí chyby ostatních snadno chybně čitelnými, takže udržujte všechny tři a skončete hned, jak jedna vrstva selže.

Mám se spoléhat na pre-commit místo validace v CI?

Ne. Háčky zpracovávají jen staged soubory, což dává zpětnou vazbu během minuty, ale nemohou pokrýt celý repozitář nebo změny, které commit obejdou. Za úplnost zodpovídá CI: pre-commit nechte na staged souborech a úplné skeny přenechte CI.