JSON کو Kotlin data class میں تبدیل کریں!

JSON درج کریں اور nested objects سمیت Kotlin data class کوڈ بنائیں! kotlinx.serialization @Serializable, @SerialName, Jackson سپورٹ۔
JSON
نتیجہ
 

JSON کو Kotlin data class میں تبدیل کریں!

API response یا config JSON پیسٹ کریں اور اس کے ڈھانچے کی عکاسی کرنے والا Kotlin data class کوڈ حاصل کریں۔ nested objects اور objects کی arrays میں سے ہر ایک اپنی کلاس بنتی ہے، اور آپ kotlinx.serialization یا Jackson میں سے کسی ایک کو نشانہ بنا سکتے ہیں۔

یہ اس لمحے کے لیے بنایا گیا ہے جب آپ Android ایپ یا Ktor/Spring سروس میں کوئی بیرونی API جوڑ رہے ہوں اور ماڈل کا ڈھانچہ ٹائپ کرنے کے بجائے ایک نمونہ response سے چاہتے ہوں۔ تبدیلی پوری طرح آپ کے براؤزر میں ہوتی ہے، اس لیے اندرونی API response پیسٹ کرنے سے وہ کہیں نہیں بھیجا جاتا۔

استعمال کا طریقہ

  1. ان پٹ باکس میں JSON پیسٹ کریں۔ مکمل اصلی response، کاٹے چھانٹے گئے response کے مقابلے میں بہتر type اندازہ دیتا ہے۔
  2. ٹائپ کا نام کو سب سے اوپر والی کلاس کا نام دیں (ڈیفالٹ Root)، مثلاً UserResponse۔
  3. سیریلائزر کے نیچے kotlinx.serialization یا Jackson چنیں، جو آپ کا پروجیکٹ پہلے سے استعمال کر رہا ہو۔
  4. بنایا گیا کوڈ اپنی ماڈل فائل میں کاپی کریں۔ ٹائپ کا نام اور سیریلائزر URL میں محفوظ رہتے ہیں، اس لیے بک مارک وہی سیٹ اپ دوبارہ کھولتا ہے۔

مثال

ان پٹ (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 array کے اندر کے objects واحد نام والی Item کلاس بنتے ہیں، اور صرف دوسرے item میں آنے والا gift_wrap بنتا ہے Boolean? = null۔ coupon ہمیشہ null ہی ہے، اس لیے اس کی type کا اندازہ نہیں لگایا جا سکتا اور اسے JsonElement? چھوڑ دیا جاتا ہے تاکہ آپ اسے اصل type سے بدلیں۔

معاون خصوصیات

  • kotlinx.serialization: ہر کلاس پر @Serializable، جن فیلڈز کا نام بدلا ہو ان پر @SerialName، اور ضروری imports۔
  • Jackson: صرف ان فیلڈز پر @JsonProperty جن کا نام بدلا ہو۔
  • user_name یا home-url جیسی keys camelCase properties (userName، homeUrl) بنتی ہیں، جو annotation کے ذریعے اصل key سے دوبارہ جوڑی جاتی ہیں۔
  • class یا val جیسے Kotlin keywords کو backticks میں لپیٹا جاتا ہے؛ ہندسے سے شروع ہونے والی keys کے آگے n prefix لگتا ہے۔
  • نمبر: integers بنتے ہیں Int، 32-bit سے بڑی values بنتی ہیں Long، اور کوئی بھی decimal فیلڈ کو Double بنا دیتا ہے۔
  • objects کی arrays، تمام items سے مل کر ایک کلاس بنتی ہیں؛ صرف کچھ items میں موجود فیلڈز ? = null بنتے ہیں۔
  • سب سے اوپر کی array یا primitive سے typealias بنتا ہے، مثلاً typealias Root = List<RootItem>۔

استعمال کے کیس

Retrofit یا Ktor clients کے لیے response ماڈلز

Postman یا براؤزر DevTools سے کاپی کیا گیا response پیسٹ کریں اور Call<Order> یا client.get<Order>() کے لیے تیار کلاسز حاصل کریں۔ درجنوں فیلڈز والے responses میں یہ ہاتھ سے کاپی کرنے کی ٹائپنگ غلطیوں اور غلط types سے بچاتا ہے۔

snake_case API کو Kotlin naming سے map کرنا

جب بیک اینڈ created_at بھیجتا ہے تو Kotlin کی طرف createdAt پڑھا جاتا ہے جبکہ serial name اصل key رکھتا ہے۔ mapping کسی global naming strategy پر انحصار کرنے کے بجائے ہر کلاس میں نظر آتی رہتی ہے۔

kotlinx.serialization پر منتقلی

اگر آپ Gson یا Jackson ماڈلز کو kotlinx.serialization پر منتقل کر رہے ہیں تو ایک ہی JSON سے دونوں آؤٹ پٹ بنا کر بالکل دیکھیں کہ کون سی annotations بدلتی ہیں۔

نوٹس اور حدود

  • types کا اندازہ صرف آپ کے پیسٹ کیے گئے نمونے سے لگایا جاتا ہے۔ جو فیلڈ ہر نمونہ item میں موجود ہو وہ non-null آتا ہے، اس لیے جن فیلڈز کے بارے میں API docs کہیں کہ چھوڑے جا سکتے ہیں ان پر ? خود لگائیں۔
  • 2024-01-01T00:00:00Z جیسی تاریخ والی strings، String رہتی ہیں؛ Instant پر جانے کے لیے اپنا serializer درکار ہے۔
  • kotlinx.serialization، Any کو serialize نہیں کر سکتا، اس لیے جن values کی type کا اندازہ نہ ہو سکے وہ وہاں JsonElement اور Jackson کے ساتھ Any بنتی ہیں۔
  • کوئی enums، sealed classes یا ڈیفالٹ values (جیسے خالی lists) نہیں بنتیں۔ مقررہ values والے فیلڈز کو بعد میں enums بنانا مفید ہے۔
  • تمام کلاسز ایک ہی بلاک میں آتی ہیں؛ package declarations اور فائلوں میں تقسیم آپ کے ذمے ہے۔

عام سوالات

کوئی فیلڈ صرف String? کے بجائے String? = null کیوں ہے؟

جب key غائب ہو اور property کا کوئی ڈیفالٹ نہ ہو تو kotlinx.serialization، MissingFieldException throw کرتا ہے۔ کچھ items میں غائب یا null والے فیلڈز پر = null لگانے سے اس key کے بغیر والے responses بھی صاف decode ہو جاتے ہیں۔

کیا میں @SerialName کے بغیر JSON keys کو ہی property نام رکھ سکتا ہوں؟

ٹول ہمیشہ camelCase میں بدلتا ہے اور annotation صرف تب لگاتا ہے جب نام مختلف ہو، اس لیے پہلے سے camelCase والی keys بغیر annotations کے آتی ہیں۔ snake_case نام رکھنے کے لیے، بنانے کے بعد properties کے نام بدلیں اور annotations ہٹا دیں۔

Jackson چننے پر کیا مجھے jackson-module-kotlin چاہیے؟

جی ہاں۔ بنائی گئی data class میں بغیر arguments والا constructor نہیں، اس لیے constructor parameters کے ذریعے values باندھنے کے لیے Jackson کو رجسٹر شدہ jackson-module-kotlin چاہیے (dependency موجود ہو تو Spring Boot اسے خودکار طور پر رجسٹر کر دیتا ہے)۔

کیا یہ Moshi یا Gson ماڈلز بنا سکتا ہے؟

سیریلائزر کے options، kotlinx.serialization اور Jackson ہیں۔ Gson کے لیے Jackson آؤٹ پٹ لے کر @JsonProperty کو @SerializedName سے بدلیں؛ Moshi کے لیے @Json(name = ...) استعمال کریں۔ کلاس کا ڈھانچہ وہی رہتا ہے۔