עורכים, שורת פקודה ושרשראות אוטומציה

שורה תחתונה: בחרו את העורך לפי תרחיש — CodeMirror 6 לאתרי כלים ולמובייל, Monaco רק כשצריך חוויית IDE מלאה; השאירו עבודת אצווה ל-jq בתוספת שלוש בדיקות CI לתחביר, מבנה וסגנון, והעבירו ארגומנטים תמיד עם jq --arg.

העידן של בדיקת JSON ביד צריך להסתיים: כל מה שמכונה יכולה לחזור עליו, אל תשאירו לעיני אדם.

1. עורכים בדפדפן

1.1 שילוב מינימלי של 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) {
        // Debounce before doing heavy work; do not format on every keystroke
        scheduleParse(update.state.doc.toString());
      }
    }),
  ],
});

ארבע נקודות שכדאי לשים לב אליהן:

1. json() מספק הדגשת תחביר והתאמת סוגריים — אל תכתבו משלכם;
2. jsonParseLinter() מייצר סמני שגיאה ברמת שורה/עמודה; שלבו אותו עם lintGutter() כדי להציג אייקונים לצד מספרי השורות;
3. ה-updateListener חייב להיות מעוכב (debounce); קריאה ל-JSON.parse על מאה אלף שורות בכל הקשה תיצור השהיה מורגשת;
4. מסמכים גדולים דורשים אופטימיזציות מעבר ל-EditorView.lineWrapping כדי להימנע מרינדור הכול בבת אחת (CodeMirror 6 מרנדר לפי viewport כברירת מחדל, וזה שיפור לעומת גרסאות ישנות יותר).

1.2 קיפול ומתאר

ל-CodeMirror 6 יש קיפול מובנה; בתרחישי JSON בדרך כלל מקפלים לפי "אובייקט/מערך":

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

עם foldGutter() ו-keymap.of(foldKeymap), משתמשים יכולים לקפל מערכים ארוכים בקיצור מקלדת.

1.3 בחירה בין CodeMirror ל-Monaco

אתרי כלים ומובייל תחילה → CodeMirror; חוויית IDE מלאה (כמה קבצים, מעבר להגדרה, השלמה) → Monaco.

2. שורת פקודה: שישה מתכוני jq בתדירות גבוהה

jq הוא ל-JSON מה ש-sed + awk הם לטקסט; לימוד חלק קטן מהתחביר שלו מכסה שמונים אחוזים מהצרכים היומיומיים.

复制# 1. Pick fields (the most common)
jq '.data.items[].name' response.json

# 2. Filter + reshape
jq '.data.items[] | select(.price < 10) | {id, price}' response.json

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

# 4. Group and aggregate
jq '[.items[]] | group_by(.category) | map({category: .[0].category, count: length})' response.json

复制# 5. Merge multiple files into an array
jq -s '.' part-*.json > merged.json

# 6. Process JSON Lines line by line
jq -c 'select(.level == "error")' app.jsonl

# Common output switches
jq -r '.data.name'      # Strip the quotes so it pipes cleanly into the shell
jq -c '.'               # Compact output, one line
jq --arg id "$ID" '.id == $id'   # Pass arguments safely, avoiding injection through concatenation

ל---arg מגיע אזכור מיוחד: שרשור משתנה ישירות לתוך ביטוי נשבר ברגע שהערך מכיל מרכאות, בעוד ש---arg נותן ל-jq לטפל בהימלטות.

2.1 כלים אחרים במבט חטוף

הרעיון מאחורי gron שווה הכרות במיוחד:

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

לאחר השטיחה, grep יכול לאתר את הנתיב, וזה הרבה יותר מהיר מאשר לפתוח רמה אחר רמה בעורך.

3. שלוש שכבות אימות ב-CI

复制# Syntax: batch-validate every json file in the repository
find . -name '*.json' -not -path './node_modules/*' -print0 \
  | xargs -0 -n1 jq empty

# Structure: validate against a schema
npx ajv-cli validate -s schemas/order.json -d 'fixtures/orders/*.json' --strict=false

# Style: check only, do not modify
npx prettier --check "**/*.json"

צריך את כל שלוש השכבות, כי הודעות השגיאה שלהן שונות לחלוטין: jq empty רק אומר "איזו שורה שבורה", ajv אומר "איזה שדה מפר איזה מילת מפתח", ו-Prettier רק אומר "הפורמט אינו עקבי".

4. ווי pre-commit

复制# .husky/pre-commit example (excerpt)
npx lint-staged

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

היזהרו מקובצי הגדרה של כלים כמו package.json ו-tsconfig.json; אל תתנו ל-Prettier להזיח אותם מחדש בקלות ראש — חלק מהכלים רגישים לפורמט (JSON תקין לא אמור להיות, אבל בפועל זה גרם לבעיות). אפשר להחריג אותם בנפרד.

5. טיפים לדיבוג

1. השתמשו ב-jq -e כהצהרה: קוד היציאה הוא 1 כשהתוצאה של הביטוי היא false או null, כך שאפשר להכניס אותו ישירות לסקריפטים כבדיקה;
2. jq 'paths' מציג את כל הנתיבים, ונותן סקירה מהירה של מבנה של מסמך לא מוכר;
3. jq '.. | objects | keys' מוצא כל שם מפתח שהופיע אי פעם, מה שנוח לציד אחר כתיב לא עקבי;
4. עצבו לפני השוואה בעורך: diff לא מעוצב הוא רעש טהור; השוואה מבנית כמו /diff מדויקת יותר.

6. רשימת בדיקה

• [ ] סמני השגיאה בעורך מדויקים לשורה ולעמודה, והפרסור מעוכב;
• [ ] סקריפטים של הצוות מעבירים ארגומנטים עם jq --arg במקום לשרשר מחרוזות;
• [ ] ב-CI קיימות כל שלוש שכבות האימות (תחביר/מבנה/סגנון);
• [ ] pre-commit מעבד רק קבצים שנמצאים ב-staging, כך שסריקה מלאה לא מאטה את ה-commit;
• [ ] גרסאות הכלים מוצמדות ב-package.json או ב-.tool-versions.

FAQ

איך בוחרים בין CodeMirror 6 ל-Monaco?

לאתרי כלים ולמובייל, העדיפו CodeMirror 6: הוא קטן, מודולרי ונתמך היטב במובייל, ואפשר להרכיב הדגשת תחביר, התאמת סוגריים וקיפול לפי הצורך. פנו ל-Monaco רק כשצריך חוויית IDE מלאה עם כמה קבצים, מעבר להגדרה והשלמה — במחיר של חבילה בגודל כמה מגה-בייט ומאמץ התאמה גבוה יותר.

למה CI צריך בדיקות תחביר, מבנה וסגנון יחד?

שלוש השכבות מדווחות שגיאות שונות לחלוטין: jq empty אומר איזו שורה שבורה, ajv אומר איזה שדה מפר איזה מילת מפתח, ו-Prettier רק אומר שהפורמט אינו עקבי. השמטת שכבה אחת הופכת את השגיאות של האחרות לקשות לפירוש, ולכן שמרו על שלושתן ועצרו ברגע ששכבה נכשלת.

כדאי להסתמך על pre-commit במקום לאמת ב-CI?

לא. ווי מעבדים קבצים ב-staging בלבד, מה שנותן משוב בתוך דקה אבל לא מכסה את כל המאגר או שינויים שעוקפים את ה-commit. CI אחראי לשלמות: השאירו את pre-commit על קבצים ב-staging והשאירו סריקות מלאות ל-CI.