حوّل أصناف Kotlin إلى JSON!

الصق شيفرة Kotlin (data class) واحصل على مثال JSON! يدعم kotlinx.serialization @SerialName, Jackson, Gson, Moshi. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Kotlin
النتيجة
 

حوّل أصناف Kotlin إلى JSON!

الصق data class موجودًا في Kotlin لترى كيف يبدو بعد التسلسل، على شكل مستند JSON نموذجي. تُتتبَّع الأصناف المتداخلة وخصائص List/Map والـ enums وتُملأ، وتُطبَّق تعليقات إعادة التسمية مثل @SerialName على المفاتيح.

استخدمه حين يتشارك الخادم والتطبيق النماذج وتحتاج إلى التأكد من JSON الذي يرسله الصنف ويستقبله فعلًا، أو حين تحتاج وثيقة API أو خادم وهمي إلى عيّنة لجسم الطلب.

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

  1. الصق كود Kotlin. يمكن أن تبقى أسطر import/package والدوال الأعضاء؛ فهي تُتخطى.
  2. اترك النوع الجذري على تلقائي في معظم الحالات: أول صنف لا يشير إليه صنف آخر يصبح الجذر. ويمكنك أيضًا اختيار صنف محدد من القائمة.
  3. انسخ JSON إلى مثال Swagger أو جسم طلب في Postman أو بيانات اختبار ثابتة.
  4. الأنواع المعرَّفة في مكان آخر (مثل صنف Money من ملف آخر) تخرج null، وتُدرج أسماؤها بجانب الخيارات. الصق تلك الأصناف أيضًا فتُملأ.

مثال

المدخلات (Kotlin)
@Serializable
data class Article(
    val id: Long,
    val title: String,
    @SerialName("author_name") val authorName: String,
    val status: PostStatus = PostStatus.DRAFT,
    val tags: List<String> = emptyList(),
    val publishedAt: Instant? = null,
    @Transient val cachedHtml: String = "",
)

@Serializable
enum class PostStatus {
    @SerialName("draft") DRAFT,
    @SerialName("published") PUBLISHED,
}
المخرجات (JSON)
{
  "id": 0,
  "title": "",
  "author_name": "",
  "status": "draft",
  "tags": [
    ""
  ],
  "publishedAt": "1970-01-01T00:00:00Z"
}

يُخرج authorName باسم author_name بسبب @SerialName، وتتحول القيمة الافتراضية PostStatus.DRAFT إلى "draft" عبر @SerialName الخاص بعنصر الـ enum نفسه. ويُحذف cachedHtml لأنه معلَّم بـ @Transient. والخاصية القابلة لـ null ذات القيمة الافتراضية null، مثل publishedAt، تحصل مع ذلك على عيّنة من نوعها (Instant → طابع زمني ISO) لا على null.

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

  • إعادة تسمية المفاتيح: @SerialName في kotlinx.serialization، و@JsonProperty في Jackson، و@SerializedName في Gson، و@Json(name = ...) في Moshi.
  • المستبعد: الخصائص المعلَّمة بـ @Transient أو @JsonIgnore، والخصائص private، والمفوَّضة مثل by lazy، والخصائص المحسوبة ذات الـ getter فقط، وقيم const، وأعضاء companion object.
  • تُستخدم القيم الافتراضية الحرفية النصية والرقمية والمنطقية قيمًا نموذجية؛ والقيمة الافتراضية مثل Status.PAID تصبح قيمة JSON لذلك العنصر.
  • تستخدم الـ enums عنصرها الأول، مع احترام @SerialName على مستوى العنصر.
  • التواريخ والأوقات: LocalDate → 1970-01-01، وLocalDateTime → 1970-01-01T00:00:00، وInstant/OffsetDateTime → سلسلة ISO تنتهي بـ Z، وDuration → PT0S؛ ويحصل UUID على قيمة سليمة الصيغة.
  • List وSet وArray تحصل على عنصر نموذجي واحد؛ والـ map ذات نوع المفتاح الرقمي مثل Map<Int, V> تستخدم "0" مفتاحًا.
  • الأصناف المرجعية ذاتيًا (الأشجار، التعليقات المتسلسلة) تُقطع بـ null أو بمصفوفة فارغة بدلًا من التوسع بلا نهاية.

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

وثائق API لخدمات Ktor أو Spring

الصق DTO استجابة فتحصل على هيكل JSON لـ example في OpenAPI أو لملف README. الحقول المعاد تسميتها عبر @SerialName تظهر بالاسم نفسه الذي سيكتبه الـ serializer فعلًا.

استجابات مزيفة لاختبارات Android

ابنِ جسم الاستجابة لـ MockWebServer أو لملف JSON محلي ثابت من النموذج نفسه الذي تُرجعه واجهة Retrofit. استبدل القيم البديلة (""، 0) ببيانات واقعية وتبقى البنية مطابقة للنموذج.

الاتفاق على أسماء المفاتيح مع الخلفية

أظهر لفريق الخادم بالضبط ما يرسله التطبيق، أو قارن مواصفات مستلمة بنموذج Kotlin لتكتشف اختلاف أسماء المفاتيح قبل أن تصبح أخطاء وقت التشغيل.

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

  • القيم بدائل حسب النوع (""، 0، false)، لا بيانات واقعية؛ استبدلها قبل نشر الوثائق.
  • الخصائص القابلة لـ null (String?) تحصل هي الأخرى على عيّنة من نوعها لا على null، لذا حدّد على حدة الحقول التي قد تكون null فعلًا.
  • لا تُطبَّق قواعد التسمية العامة مثل @JsonNaming في Jackson أو JsonNamingStrategy في kotlinx؛ والخصائص غير المعلَّمة تحتفظ باسمها في Kotlin مفتاحًا.
  • لا تنعكس هرميات sealed متعددة الأشكال (مميِّز type) ولا الـ KSerializers المخصصة.
  • القيم الافتراضية المبنية من استدعاءات دوال، مثل emptyList() أو listOf(...)، لا تُقيَّم؛ بل تأتي القيمة من النوع المُعلن.

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

خاصية @Transient مفقودة من الناتج. هل هذا متوقع؟

نعم. @Transient في kotlinx.serialization و@JsonIgnore في Jackson يُبقيان الحقل خارج التسلسل، فتحذفه العيّنة أيضًا. والـ private val المعرَّف في جسم الصنف يُستبعد للسبب نفسه.

هل يقرأ النماذج المكتوبة لـ Gson أو Moshi؟

صيغة الأصناف نفسها، فتُحلَّل بلا مشكلة. ويُتعرَّف على إعادة التسمية عبر @SerializedName("...") في Gson و@Json(name = "...") في Moshi.

عرّفت = null، فلماذا للحقل قيمة؟

الهدف إظهار شكل كل حقل، لذا تُتجاهل القيمة الافتراضية null وتُستخدم عيّنة من النوع. وبذلك ترى مثلًا بأي صيغة نصية ينتقل Instant?.

أصنافي موزعة على عدة ملفات. ماذا ألصق؟

الصقها واحدًا تلو الآخر في خانة الإدخال نفسها. وأي نوع ما زال مفقودًا يُذكر اسمه بجانب الخيارات، فتعرف ما الذي عليك إضافته أيضًا.