حوّل JSON إلى struct بلغة Rust!

أدخل JSON لتوليد كود struct بلغة Rust بما في ذلك الكائنات المتداخلة! يدعم serde Serialize, Deserialize, #[serde(rename)].
JSON
النتيجة
 

حوّل JSON إلى struct بلغة Rust!

حوّل عيّنة JSON إلى structs في Rust جاهزة لـ serde. كل struct يشتق Debug, Clone, Serialize, Deserialize؛ وتتبع أسماء الحقول اصطلاح snake_case في Rust وترتبط بالمفتاح الأصلي عبر #[serde(rename)] حين تختلف عنه.

هو نقطة انطلاق حين تريد استجابات reqwest ذات أنواع، أو تحتاج إلى نوع طلب لمستخرج Json<T> في axum أو actix-web، أو تكتب أداة CLI تحلّل JSON السجلات أو الأحداث.

طريقة الاستخدام

  1. الصق JSON. المصفوفة ذات العناصر المتعددة تساعده على اكتشاف الحقول الاختيارية.
  2. أدخل اسم الـ struct على المستوى الأعلى في اسم النوع (مثلًا AccessLog).
  3. الصق الناتج في ملف .rs وأضف serde (مع الميزة derive) وserde_json إلى Cargo.toml.
  4. استخدمه عبر serde_json::from_str::<AccessLog>(&body)? أو resp.json::<AccessLog>().await?.

مثال

المدخلات (JSON)
{
  "timestamp": 1714550400,
  "level": "warn",
  "type": "http_request",
  "status": 503,
  "latency_ms": 1250.7,
  "headers": [{ "name": "user-agent", "value": "curl/8.4" }],
  "trace_id": null
}
المخرجات (Rust · serde)
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AccessLog {
    pub timestamp: i64,
    pub level: String,
    #[serde(rename = "type")]
    pub type_: String,
    pub status: i64,
    pub latency_ms: f64,
    pub headers: Vec<Header>,
    pub trace_id: serde_json::Value,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Header {
    pub name: String,
    pub value: String,
}

type كلمة محجوزة في Rust، فيصبح الحقل type_ مع #[serde(rename = "type")]. الأعداد الصحيحة i64 أيًّا كان حجمها، وlatency_ms من نوع f64. أما trace_id فقيمته null دائمًا، فنوعه مجهول ويبقى serde_json::Value؛ استبدله بالنوع الحقيقي، مثل Option<String>.

الميزات المدعومة

  • #[derive(Debug, Clone, Serialize, Deserialize)] وحقول pub في كل struct.
  • #[serde(rename = "originalKey")] لكل حقل يختلف مفتاحه عن اسم الحقل بصيغة snake_case.
  • الحقول الغائبة في بعض العناصر: Option<T> مع #[serde(default, skip_serializing_if = "Option::is_none")].
  • الحقول الموجودة دائمًا لكنها null أحيانًا: Option<T> عادي دون سمات.
  • الأنواع: i64 للأعداد الصحيحة، وf64 للعشرية، وbool وString وVec<T>، وserde_json::Value للأنواع المختلطة.
  • المفاتيح التي هي كلمات محجوزة مثل type أو match أو ref تحصل على شرطة سفلية في آخرها (type_).
  • المصفوفة على المستوى الأعلى تُنتج pub type Root = Vec<RootItem>;.

حالات الاستخدام

استجابات reqwest ذات أنواع

استبدل عمليات البحث في serde_json::Value مثل ["status"].as_i64() بـ resp.json::<AccessLog>() حتى يفشل الحقل المكتوب خطأً وقت الترجمة.

أجسام الطلبات في axum أو actix-web

ولّد struct من JSON الذي يرسله العميل واستقبله بالشكل Json(payload): Json<CreateOrder>؛ فيرفض إطار العمل الطلبات ذات الحقول الناقصة أو الخاطئة النوع قبل أن يعمل كود الـ handler.

أداة CLI لتحليل سجلات JSON Lines

ابنِ struct من سطر سجل واحد، ثم فك تسلسل كل سطر من BufReader::lines() لتحصل على أداة تجميع لكل حقل في بضعة أسطر.

ملاحظات وقيود

  • الأعداد الصحيحة دائمًا i64 مهما صغرت. ضيّقها بنفسك حيث يكون النطاق معروفًا، مثل u16 لرموز الحالة أو u32 للعدّادات.
  • تبقى الطوابع الزمنية وسلاسل التاريخ i64 أو String. الانتقال إلى أنواع chrono أو time يتطلب تفعيل ميزات serde في تلك الـ crates.
  • الناتج الذي يستخدم serde_json::Value يكتب المسار الكامل، فلا حاجة إلى use إضافي، لكن اعتمادية serde_json لازمة.
  • إعادة التسمية تكون لكل حقل لا عبر #[serde(rename_all = "camelCase")] على مستوى الـ struct. إن كانت المفاتيح تتبع اصطلاحًا واحدًا، يمكنك دمجها بنفسك.
  • لا تُولَّد enums موسومة. الحقول ذات المجموعة الثابتة من القيم، مثل "level": "warn"، مرشحة جيدة للتحويل إلى enum لاحقًا.

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

لماذا تحصل الحقول الاختيارية أيضًا على #[serde(default)]؟

يملأ serde أصلًا الـ Option الغائب بـ None، لكن default الصريح يُبقي قبول المفاتيح الغائبة إن غيّرت النوع لاحقًا إلى شيء مثل Vec<T>. ويحذف skip_serializing_if حقول None عند كتابة JSON من جديد، فيُحفظ الشكل الأصلي.

كيف تختلف الحقول القابلة لـ null عن الغائبة في الناتج؟

كلاهما يصبح Option<T>، لكن لا يحصل على سمتي default وskip_serializing_if إلا الحقول التي قد يغيب مفتاحها. أما الحقل الموجود دائمًا لكنه null أحيانًا فيُكتب مجددًا على شكل null.

لماذا لا يُستعار بحقول &str ومدة حياة 'de؟

حقول zero-copy (&'a str) لا يمكن أن تعيش أطول من مخزن الإدخال، وهذا مُربك في المعالجة المعتادة للاستجابات. الـ String المملوك هو الافتراضي؛ بدّل الحقول الحرجة إلى Cow<'a, str> إن كان الأداء مهمًا.

هل يمكنني إضافة اشتقاق Default أو PartialEq؟

يشتق الناتج Debug وClone وSerialize وDeserialize فقط. أضف المزيد إلى قائمة الاشتقاق بنفسك حين تدعمها كل أنواع الحقول (serde_json::Value ينفّذ PartialEq).