مختبِر JSONPath مجاني — قيّم الاستعلامات

ما هو مختبِر JSONPath؟

// The expression you build in this tester maps straight onto the
// RFC 9535 reference library used under the hood.
import { query, paths } from 'jsonpath-rfc9535';

const document = {
  store: {
    book: [
      { title: 'Sayings of the Century', author: 'Nigel Rees', price: 8.95 },
      { title: 'Sword of Honour', author: 'Evelyn Waugh', price: 12.99 },
      { title: 'Moby Dick', author: 'Herman Melville', price: 8.99 },
      { title: 'The Lord of the Rings', author: 'J. R. R. Tolkien', price: 22.99 }
    ]
  }
};

// Values: query(document, path) returns the matched values directly.
const titles = query(document, '$.store.book[*].title');
// → ['Sayings of the Century', 'Sword of Honour', 'Moby Dick', 'The Lord of the Rings']

// Filter: books cheaper than 10.
const cheap = query(document, '$.store.book[?(@.price < 10)].title');
// → ['Sayings of the Century', 'Moby Dick']

// Normalized paths: paths(document, path) returns where each match lives.
const authorPaths = paths(document, '$..author');
// → ["$['store']['book'][0]['author']", "$['store']['book'][1]['author']", ...]

// RFC 9535 functions like length() are used INSIDE filters, not as a segment.
const longTitles = query(document, '$.store.book[?length(@.title) > 15]');
// → the two books whose title is longer than 15 characters

الميزات الرئيسية

أمثلة محلولة

$.store.book[*].title

["Sayings of the Century", "Sword of Honour", "Moby Dick", "The Lord of the Rings"]

$.store.book[?(@.price < 10)].title

["Sayings of the Century", "Moby Dick"]

$..author

["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"]

$.store.book[0:2].title

["Sayings of the Century", "Sword of Honour"]

$.store.book[?length(@.title) > 15]

[{"title": "Sayings of the Century", "author": "Nigel Rees", "price": 8.95}, {"title": "The Lord of the Rings", "author": "J. R. R. Tolkien", "price": 22.99}]

$.store.book[0]['title','author']

["Sayings of the Century", "Nigel Rees"]

كيفية استخدام مختبِر JSONPath

1. 1

   الصق أو ارفع ملف JSON

   أفلِت JSON في صندوق الإدخال أو الصقه أو انقر Upload لتحميل ملف .json أو .txt من القرص. ويعيد Format JSON تنسيق المستند. ويُعلَّم JSON غير الصالح ضمنيًا برسالة من المُحلِّل قبل الاستعلام.

2. 2

   اختر محرّكًا

   المحرّك RFC 9535 (معيار IETF لعام 2024، بلا eval) هو الافتراضي. بدّل إلى الكلاسيكي (Goessner) عند تشغيل تعبير منسوخ من أداة أقدم مثل jsonpath.com كي تطابِق النتائج ما رأيته هناك.

3. 3

   اكتب تعبير JSONPath

   يُعرَض لك الرمز $ في البداية. ابدأ بمسار ابن مثل .store.book[*].title، أو فهرس مثل [0]، أو نزول تعاودي مثل ..author، أو ترشيح مثل [?(@.price < 10)]. وتتحدّث النتائج حيًّا أثناء الكتابة.

4. 4

   بدّل عرض النتيجة

   يُظهر Values مصفوفة JSON من القيم المطابِقة. ويُظهر Paths المسار المُطبَّع لكل مطابقة مثل $['store']['book'][0]['title']. ويُظهر Both الاثنين جنبًا إلى جنب كي تربط كل قيمة بموقعها الدقيق في المستند.

5. 5

   انسخ النتيجة أو شارك رابطًا دائمًا

   يُسقِط Copy result المخرَج على حافظتك. ويُرمِّز Copy link ملف JSON والتعبير والمحرّك والعرض داخل hash في العنوان (بلا رفع) كي يستطيع زميلك إعادة إنتاج الاستعلام نفسه محليًا على جهازه.

أخطاء JSONPath الشائعة

store.book[*].title  →  invalid (no root)

$.store.book[*].title  →  selects every title

$.store.book[0:2]  →  first TWO books, not three

$.store.book[0:3]  →  first three books (indices 0,1,2)

Classic filter run under RFC 9535  →  parse error or unexpected nodes

Switch engine to Classic (Goessner)  →  reproduces the original result

$.store.book.length()  →  parse error (not a valid RFC 9535 segment)

$.store.book[?length(@.title) > 15]  →  books with a title over 15 chars

$.store.book[?($.price < 10)]  →  wrong scope

$.store.book[?(@.price < 10)]  →  books under 10

$[store][book]  →  invalid bracket selectors

$['store']['book']  →  same as $.store.book

$..price  →  every price anywhere in the tree

$.store.book[*].price  →  only book prices

من يستخدم هذه الأداة

استخراج حقول من استجابة API

اسحب مُعرِّفات الطلبات، أو سمات موارد متداخلة، أو قائمة أسماء من حمولة JSON دون كتابة شِفرة اجتياز. ابنِ المسار هنا على استجابة عيّنة، وتأكّد في عرض Values من أنه يعيد العقد التي تريدها بالضبط، ثم الصق التعبير المُتحقَّق منه في تطبيقك أو اختبارك.

كتابة تأكيدات لاختبارات التكامل

كثير من أطر الاختبار وأدوات اختبار العقود (REST Assured وKarate وPostman) تستخدم JSONPath للتأكيد على أجسام الاستجابات. صُغ مسار التأكيد هنا، وتحقّق من أنه يختار العقدة الصحيحة على استجابة حقيقية، وانسخه إلى اختبارك — لتلتقط مسارًا خاطئًا قبل أن تتعطّل المجموعة.

تهيئة تحويلات البيانات في خطوط الأنابيب

تقبل Kubernetes وAWS Step Functions وAzure Logic Apps وكثير من أدوات ETL صيغة JSONPath لعنونة الحقول في حمولات الأحداث. جرّب المسار الدقيق على حدث تمثيلي هنا، وتأكّد من أنه يُحَلّ، وأدرِجه في إعداد خط الأنابيب بثقة أنه يشير حيث تقصد.

إعادة إنتاج نتيجة jsonpath.com بخصوصية

لديك تعبير من مُقيّم قائم على خادم لكن لا يمكنك لصق بياناتك في موقع طرف ثالث؟ بدّل إلى الوضع الكلاسيكي (Goessner)، وحمّل ملف JSON، وأعِد إنتاج النتيجة نفسها محليًا — فلا تغادر أي حمولة متصفّحك، وتبقى البيانات المملوكة على جهازك.

ترحيل التعبيرات القديمة إلى RFC 9535

تنتقل إلى نظام يُعلن توافقه مع RFC 9535؟ شغّل تعبيرًا قديمًا في الوضع الكلاسيكي، ثم انتقل إلى محرّك RFC 9535 لترى إن كان لا يزال يُحلَّل ويُطابِق العقد نفسها. وتُحدِّد مقارنة المحرّكين بدقّة فروق الترشيح والاتحاد والدوال التي قد تصطدم بها في الإنتاج لولا ذلك.

تنقيح سبب إعادة مسارٍ عقدًا خاطئة

يصعب تعليل مسار يختار كثيرًا جدًا أو قليلًا جدًا من القيم وحدها. بدّل إلى عرض Paths لترى الموقع المُطبَّع لكل مطابقة — فهرس المصفوفة الدقيق وسلسلة الأعضاء الدقيقة — فيتّضح فورًا انزياح الشريحة بمقدار واحد أو النزول التعاودي الشارد.

تعليم أو مراجعة JSONPath

افتح تعبيرًا عاملًا على بيانات عيّنة واشرحه مُحدِّدًا تلو مُحدِّد، مبدّلًا بين Values وPaths كي يرى المتعلّم ما يُختار وأين يعيش معًا. وتمنح ورقة الغش والأمثلة المحلولة مرجعًا منظّمًا لمراجعة الشِفرة أو التأهيل.

ملاحظات المحرّك والخوارزمية

محرّك RFC 9535 (jsonpath-rfc9535، بلا تبعيات)

المحرّك الافتراضي يطبّق قواعد IETF RFC 9535 مباشرةً: يُجزّئ التعبير ويحلّله إلى شجرة بناء تجريدية ويُفسّره مقابل المستند. لا يوجد eval ولا باني Function في أي مكان من المسار، فهو محصّن ضد صنف ثغرات حقن eval ويعمل ضمن سياسة أمان محتوى صارمة.

المحرّك الكلاسيكي (jsonpath-plus، eval مُعطَّل)

المحرّك الكلاسيكي (Goessner) هو jsonpath-plus، مثبّت على إصدار مُصحَّح (>= 10.4.0) ومُهيّأ مع ضبط خيار eval على false صراحةً. يحفظ ذلك توافق لهجة Goessner مع إغلاق نواقل تنفيذ الشِفرة عن بُعد المتتبَّعة كـ CVE-2024-21534 وCVE-2025-1302، التي أثّرت في مسار الترشيح الافتراضي القائم على eval في المكتبة.

توليد المسارات المُطبَّعة

تُبلَّغ كل مطابقة بمسارها المُطبَّع وفق RFC 9535 — صيغة قانونية بترميز أقواس بعلامات اقتباس مفردة ($['store']['book'][0]['title']) مع فهارس المصفوفات أعدادًا صحيحة مجرّدة. المسارات المُطبَّعة مستقرة وفريدة لكل عقدة، فالتعبيرات المتكافئة تُنتج مسارات متطابقة، وهو ما يعتمد عليه عرضا Paths وBoth للتعرّف على النتائج بلا لبس.

تحميل أجزاء المحرّك بالكسل

يُحمَّل كلا المحرّكين كأجزاء JavaScript منفصلة عند اختيارهما أول مرة فقط، فتبقى الصفحة الأولية خفيفة ولا يُنزَّل المحرّك الذي لا تستخدمه أبدًا. وتبديل المحرّكات يُعيد تقييم التعبير الحالي مقابل المستند الحالي فورًا، دون إعادة تحميل الصفحة.

قراءة الملفات محليًا وتنسيق JSON

يستخدم زر Upload واجهة FileReader في المتصفّح لقراءة ملف .json أو .txt إلى الإدخال كليًا في جانب العميل — فلا يُرسَل الملف قط. ويُحلِّل Format JSON الإدخال ويُعيد تسلسله بإزاحة مسافتين، مُظهِرًا أخطاء التحليل ضمنيًا فيُلتقَط JSON المُشوَّه قبل التقييم.

الروابط الدائمة عبر hash العنوان (لا تُرسَل قط)

تُرمَّز حالة المشاركة في جزء location.hash، حاملةً JSON والتعبير والمحرّك النشط وعرض النتيجة. ولا تُدرِج المتصفّحات الجزء في طلبات HTTP أبدًا، فتتلقّى خوادم go-tools.org صفرًا من البيانات عند فتح رابط دائم؛ وتجري التهيئة كليًا على جهاز المستلِم.

أفضل ممارسات JSONPath

اختر المحرّك المطابِق لهدفك

إن كان نظامك التابع يُعلن توافقه مع RFC 9535، فاكتب وتحقّق مقابل محرّك RFC 9535. وإن كنت تُعيد إنتاج أو تصون تعبيرًا من أداة أو مكتبة أقدم، فاستخدم الكلاسيكي (Goessner). والتحقّق مقابل اللهجة الخاطئة هو أكثر أسباب فشل مسار نجح في المختبِر داخل الإنتاج شيوعًا.

تحقّق بعرض المسارات لا بالقيم وحدها

يخبرك عرض Values بما طابَق؛ ويخبرك عرض Paths بالمكان. حين يعيد استعلام قيمًا تبدو صحيحة قد يظل يختارها من موقع خاطئ — نزول تعاودي شارد أو حرف بدل مفرط الاتساع. افحص المسارات المُطبَّعة لتأكيد أن التعبير يصيب العقد التي تقصدها بالضبط.

انتبه إلى الحد النهائي الحصري للشريحة

التعبير [0:2] يختار الفهرسين 0 و1، لا 0 حتى 2 — فالحدّ النهائي حصري، تمامًا كما في Python وJavaScript. وأخطاء انزياح الشرائح بمقدار واحد أكثر أخطاء JSONPath تكرارًا. استخدم عرض Paths لقراءة الفهرس الدقيق لكل عنصر مُختار وتأكيد الحدود قبل الإطلاق.

فضّل مسارًا صريحًا على النزول التعاودي ما أمكن

التعبير $..price مريح لكنه يُطابِق كل price في أي مكان من المستند، بما في ذلك ما لم تقصده. حين تعرف البنية، اكتب المسار كاملًا ($.store.book[*].price) كي يبقى الاستعلام دقيقًا ومتوقّعًا مع نمو البيانات. واحجز .. للأشكال غير المنتظمة أو المجهولة حقًا.

حافظ على اتساق المسافات والاقتباس في الترشيحات

تتبع RFC 9535 قواعدها بدقة في تعبيرات الترشيح، بينما اللهجة الكلاسيكية أكثر تساهلًا. اكتب الترشيحات بنظافة — اقتبس السلاسل الحرفية بعلامات اقتباس مفردة ('fiction')، وأبقِ المعاملات متباعدة، وتجنّب الاعتماد على التحليل المتساهل — كي يُقيَّم التعبير نفسه بالطريقة نفسها أيًّا كان المحرّك أو المكتبة التي تشغّله في النهاية.

الأسئلة الشائعة