حوّل JSON إلى data class بلغة Kotlin!

أدخل JSON لتوليد كود data class بلغة Kotlin بما في ذلك الكائنات المتداخلة! يدعم kotlinx.serialization @Serializable, @SerialName, Jackson.
JSON
النتيجة
 

حوّل JSON إلى data class بلغة Kotlin!

الصق استجابة API أو JSON إعدادات لتحصل على كود data class في Kotlin يعكس بنيته. تصبح الكائنات المتداخلة ومصفوفات الكائنات كلٌّ منها صنفًا مستقلًا، ويمكنك استهداف kotlinx.serialization أو Jackson.

صُمّم للحظة التي تربط فيها API خارجيًا في تطبيق Android أو في خدمة Ktor/Spring وتريد هيكل النموذج من استجابة نموذجية واحدة بدلًا من كتابته. يجري التحويل بالكامل داخل متصفحك، فلصق استجابة API داخلي لا يرسلها إلى أي مكان.

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

  1. الصق JSON في خانة الإدخال. الاستجابة الحقيقية الكاملة تعطي استنتاجًا أدق للأنواع من استجابة مقتطعة.
  2. اضبط اسم النوع على اسم الصنف في المستوى الأعلى (الافتراضي Root)، مثلًا UserResponse.
  3. اختر kotlinx.serialization أو Jackson من مكتبة التسلسل، بما يطابق ما يستخدمه مشروعك أصلًا.
  4. انسخ الكود المولَّد إلى ملف النموذج. يُحفظ اسم النوع ومكتبة التسلسل في الرابط، فيعيد فتحُ المفضلة الإعداد نفسه.

مثال

المدخلات (JSON)
{
  "orderId": "A-1024",
  "paid": true,
  "total": 39.9,
  "coupon": null,
  "items": [
    { "sku": "TSHIRT-M", "qty": 2 },
    { "sku": "CAP", "qty": 1, "gift_wrap": true }
  ]
}
المخرجات (Kotlin · kotlinx.serialization)
import kotlinx.serialization.Serializable
import kotlinx.serialization.SerialName
import kotlinx.serialization.json.JsonElement

@Serializable
data class Order(
    val orderId: String,
    val paid: Boolean,
    val total: Double,
    val coupon: JsonElement? = null,
    val items: List<Item>
)

@Serializable
data class Item(
    val sku: String,
    val qty: Int,
    @SerialName("gift_wrap") val giftWrap: Boolean? = null
)

الكائنات داخل المصفوفة items تصبح صنفًا بصيغة المفرد Item، وgift_wrap الذي يظهر في العنصر الثاني فقط يصبح Boolean? = null. أما coupon فقيمته null دائمًا، فلا يمكن استنتاج نوعه ويُترك JsonElement? لتستبدله أنت بالنوع الحقيقي.

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

  • kotlinx.serialization: @Serializable على كل صنف، و@SerialName على الحقول التي تغيّر اسمها، مع أسطر الاستيراد اللازمة.
  • Jackson: @JsonProperty فقط على الحقول التي تغيّر اسمها.
  • المفاتيح مثل user_name أو home-url تصبح خصائص بصيغة camelCase (userName، homeUrl) مرتبطة بالمفتاح الأصلي عبر تعليق توضيحي.
  • الكلمات المحجوزة في Kotlin مثل class أو val تُحاط بعلامات backtick؛ والمفاتيح التي تبدأ برقم تحصل على البادئة n.
  • الأرقام: الأعداد الصحيحة تصبح Int، والقيم التي تتجاوز 32 بت تصبح Long، وأي عدد عشري يجعل الحقل Double.
  • تُدمج مصفوفات الكائنات في صنف واحد من كل العناصر؛ والحقول الموجودة في بعض العناصر فقط تصبح ? = null.
  • المصفوفة أو القيمة البدائية على المستوى الأعلى تُنتج typealias، مثل typealias Root = List<RootItem>.

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

نماذج الاستجابة لعملاء Retrofit أو Ktor

الصق استجابة منسوخة من Postman أو من DevTools في المتصفح لتحصل على أصناف جاهزة لـ Call<Order> أو client.get<Order>(). مع الاستجابات التي فيها عشرات الحقول، يجنّبك هذا الأخطاء الإملائية والأنواع الخاطئة الناتجة عن النسخ اليدوي.

ربط API بصيغة snake_case بتسميات Kotlin

حين ترسل الخلفية created_at، يقرأ جانب Kotlin createdAt بينما يحتفظ الاسم التسلسلي بالمفتاح الأصلي. يبقى الربط مرئيًا في كل صنف بدلًا من الاعتماد على استراتيجية تسمية عامة.

الترحيل إلى kotlinx.serialization

إذا كنت تنقل نماذج Gson أو Jackson إلى kotlinx.serialization، فولّد الناتجين من JSON نفسه لترى بالضبط أي التعليقات التوضيحية تتغير.

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

  • تُستنتج الأنواع من العيّنة التي تلصقها فقط. الحقل الموجود في كل عناصر العيّنة يخرج غير قابل لـ null، فأضف ? بنفسك للحقول التي تقول وثائق الـ API إنها قد تُحذف.
  • سلاسل التاريخ مثل 2024-01-01T00:00:00Z تبقى String؛ والانتقال إلى Instant يتطلب serializer خاصًا بك.
  • لا يستطيع kotlinx.serialization تسلسل Any، لذا تصبح القيم التي لا يمكن استنتاج نوعها JsonElement هناك وAny مع Jackson.
  • لا تُولَّد enums ولا sealed classes ولا قيم افتراضية (مثل القوائم الفارغة). الحقول ذات المجموعة الثابتة من القيم تستحق التحويل إلى enums لاحقًا.
  • تخرج كل الأصناف في كتلة واحدة؛ وتعريفات الحزم والتقسيم إلى ملفات متروكة لك.

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

لماذا يكون الحقل String? = null لا مجرد String?؟

يرمي kotlinx.serialization MissingFieldException حين يغيب مفتاح وليس للخاصية قيمة افتراضية. إضافة = null إلى الحقول الغائبة في بعض العناصر أو التي تحوي null تجعل الاستجابات التي ينقصها ذلك المفتاح تُفك بسلاسة.

هل يمكنني إبقاء مفاتيح JSON أسماءً للخصائص دون @SerialName؟

تحوّل الأداة دائمًا إلى camelCase ولا تضيف تعليقًا توضيحيًا إلا حين يختلف الاسم، لذا تخرج المفاتيح المكتوبة بصيغة camelCase أصلًا دون تعليقات توضيحية. للإبقاء على أسماء snake_case، أعد تسمية الخصائص واحذف التعليقات التوضيحية بعد التوليد.

هل أحتاج إلى jackson-module-kotlin عند اختيار Jackson؟

نعم. الـ data class المولَّد ليس له constructor بلا معاملات، لذا يحتاج Jackson إلى تسجيل jackson-module-kotlin ليربط القيم عبر معاملات الـ constructor (ويسجّله Spring Boot تلقائيًا عند وجود الاعتمادية).

هل يمكنه توليد نماذج Moshi أو Gson؟

خيارات مكتبة التسلسل هي kotlinx.serialization وJackson. لـ Gson، خذ ناتج Jackson واستبدل @JsonProperty بـ @SerializedName؛ ولـ Moshi استخدم @Json(name = ...). وتبقى بنية الأصناف كما هي.