الصق استجابة API أو JSON إعدادات لتحصل على كود data class في Kotlin يعكس بنيته. تصبح الكائنات المتداخلة ومصفوفات الكائنات كلٌّ منها صنفًا مستقلًا، ويمكنك استهداف kotlinx.serialization أو Jackson.
صُمّم للحظة التي تربط فيها API خارجيًا في تطبيق Android أو في خدمة Ktor/Spring وتريد هيكل النموذج من استجابة نموذجية واحدة بدلًا من كتابته. يجري التحويل بالكامل داخل متصفحك، فلصق استجابة API داخلي لا يرسلها إلى أي مكان.
اسم النوع على اسم الصنف في المستوى الأعلى (الافتراضي Root)، مثلًا UserResponse.مكتبة التسلسل، بما يطابق ما يستخدمه مشروعك أصلًا.{
"orderId": "A-1024",
"paid": true,
"total": 39.9,
"coupon": null,
"items": [
{ "sku": "TSHIRT-M", "qty": 2 },
{ "sku": "CAP", "qty": 1, "gift_wrap": true }
]
}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? لتستبدله أنت بالنوع الحقيقي.
@Serializable على كل صنف، و@SerialName على الحقول التي تغيّر اسمها، مع أسطر الاستيراد اللازمة.@JsonProperty فقط على الحقول التي تغيّر اسمها.user_name أو home-url تصبح خصائص بصيغة camelCase (userName، homeUrl) مرتبطة بالمفتاح الأصلي عبر تعليق توضيحي.class أو val تُحاط بعلامات backtick؛ والمفاتيح التي تبدأ برقم تحصل على البادئة n.Int، والقيم التي تتجاوز 32 بت تصبح Long، وأي عدد عشري يجعل الحقل Double.? = null.typealias، مثل typealias Root = List<RootItem>.الصق استجابة منسوخة من Postman أو من DevTools في المتصفح لتحصل على أصناف جاهزة لـ Call<Order> أو client.get<Order>(). مع الاستجابات التي فيها عشرات الحقول، يجنّبك هذا الأخطاء الإملائية والأنواع الخاطئة الناتجة عن النسخ اليدوي.
حين ترسل الخلفية created_at، يقرأ جانب Kotlin createdAt بينما يحتفظ الاسم التسلسلي بالمفتاح الأصلي. يبقى الربط مرئيًا في كل صنف بدلًا من الاعتماد على استراتيجية تسمية عامة.
إذا كنت تنقل نماذج Gson أو Jackson إلى kotlinx.serialization، فولّد الناتجين من JSON نفسه لترى بالضبط أي التعليقات التوضيحية تتغير.
? بنفسك للحقول التي تقول وثائق الـ API إنها قد تُحذف.2024-01-01T00:00:00Z تبقى String؛ والانتقال إلى Instant يتطلب serializer خاصًا بك.Any، لذا تصبح القيم التي لا يمكن استنتاج نوعها JsonElement هناك وAny مع Jackson.String? = null لا مجرد String?؟يرمي kotlinx.serialization MissingFieldException حين يغيب مفتاح وليس للخاصية قيمة افتراضية. إضافة = null إلى الحقول الغائبة في بعض العناصر أو التي تحوي null تجعل الاستجابات التي ينقصها ذلك المفتاح تُفك بسلاسة.
@SerialName؟تحوّل الأداة دائمًا إلى camelCase ولا تضيف تعليقًا توضيحيًا إلا حين يختلف الاسم، لذا تخرج المفاتيح المكتوبة بصيغة camelCase أصلًا دون تعليقات توضيحية. للإبقاء على أسماء snake_case، أعد تسمية الخصائص واحذف التعليقات التوضيحية بعد التوليد.
نعم. الـ data class المولَّد ليس له constructor بلا معاملات، لذا يحتاج Jackson إلى تسجيل jackson-module-kotlin ليربط القيم عبر معاملات الـ constructor (ويسجّله Spring Boot تلقائيًا عند وجود الاعتمادية).
خيارات مكتبة التسلسل هي kotlinx.serialization وJackson. لـ Gson، خذ ناتج Jackson واستبدل @JsonProperty بـ @SerializedName؛ ولـ Moshi استخدم @Json(name = ...). وتبقى بنية الأصناف كما هي.