แปลง JSON เป็น data class ของ Kotlin!

ป้อน JSON เพื่อสร้างโค้ด data class ของ Kotlin รวมถึงออบเจ็กต์ที่ซ้อนกัน! รองรับ kotlinx.serialization @Serializable, @SerialName, Jackson
JSON
ผลลัพธ์
 

แปลง JSON เป็น data class ของ Kotlin!

วาง response ของ API หรือ JSON คอนฟิก แล้วจะได้โค้ด data class ของ Kotlin ที่มีโครงสร้างตรงกัน ออบเจ็กต์ที่ซ้อนกันและอาร์เรย์ของออบเจ็กต์จะกลายเป็นคลาสของตัวเอง และเลือกได้ว่าจะใช้ kotlinx.serialization หรือ Jackson

สร้างมาสำหรับตอนที่ต้องเชื่อม API ภายนอกในแอป Android หรือเซอร์วิส Ktor/Spring และอยากได้โครงโมเดลจาก response ตัวอย่างเดียวแทนการพิมพ์เอง การแปลงทำงานในเบราว์เซอร์ทั้งหมด การวาง response ของ API ภายในจึงไม่ถูกส่งไปที่ไหน

วิธีใช้

  1. วาง JSON ลงในช่องอินพุต response จริงที่ครบถ้วนจะให้การอนุมานไทป์ที่ดีกว่าแบบที่ตัดทอนแล้ว
  2. ตั้ง ชื่อไทป์ เป็นชื่อคลาสระดับบนสุด (ค่าเริ่มต้น Root) เช่น UserResponse
  3. เลือก kotlinx.serialization หรือ Jackson ใน ไลบรารี serialize ให้ตรงกับที่โปรเจกต์ใช้อยู่
  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 กลายเป็นคลาส Item แบบเอกพจน์ และ gift_wrap ที่มีแค่ในรายการที่สองกลายเป็น Boolean? = null ส่วน coupon มีแต่ค่า null จึงอนุมานไทป์ไม่ได้ และถูกปล่อยเป็น JsonElement? ให้คุณเปลี่ยนเป็นไทป์จริงเอง

ฟีเจอร์ที่รองรับ

  • kotlinx.serialization: ใส่ @Serializable ทุกคลาส ใส่ @SerialName ที่ฟิลด์ซึ่งชื่อเปลี่ยน พร้อม import ที่จำเป็น
  • Jackson: ใส่ @JsonProperty เฉพาะฟิลด์ที่ชื่อเปลี่ยน
  • คีย์อย่าง user_name หรือ home-url กลายเป็นพร็อพเพอร์ตีแบบ camelCase (userName, homeUrl) และจับคู่กลับไปยังคีย์เดิมด้วย annotation
  • คำสงวนของ Kotlin อย่าง class หรือ val ถูกครอบด้วย backtick และคีย์ที่ขึ้นต้นด้วยตัวเลขได้คำนำหน้า n
  • ตัวเลข: จำนวนเต็มเป็น Int ค่าที่เกิน 32 บิตเป็น Long และถ้ามีทศนิยมแม้แต่ค่าเดียว ฟิลด์จะเป็น Double
  • อาร์เรย์ของออบเจ็กต์ถูกรวมเป็นคลาสเดียวจากทุกรายการ ฟิลด์ที่มีแค่ในบางรายการจะเป็น ? = null
  • อาร์เรย์หรือค่า primitive ระดับบนสุดจะได้ typealias เช่น typealias Root = List<RootItem>

กรณีการใช้งาน

โมเดล response สำหรับไคลเอนต์ Retrofit หรือ Ktor

วาง response ที่คัดลอกจาก Postman หรือ DevTools ของเบราว์เซอร์ แล้วจะได้คลาสที่พร้อมใช้กับ Call<Order> หรือ client.get<Order>() สำหรับ response ที่มีฟิลด์หลายสิบตัว จะเลี่ยงการพิมพ์ผิดและไทป์ผิดจากการคัดลอกเอง

จับคู่ API แบบ snake_case กับการตั้งชื่อของ Kotlin

เมื่อ backend ส่ง created_at ฝั่ง Kotlin จะอ่านเป็น createdAt ขณะที่ serial name ยังเก็บคีย์เดิมไว้ การจับคู่จึงเห็นได้ในแต่ละคลาส แทนที่จะพึ่ง naming strategy แบบ global

ย้ายไปใช้ kotlinx.serialization

ถ้ากำลังย้ายโมเดล Gson หรือ Jackson ไป kotlinx.serialization ให้สร้างผลลัพธ์ทั้งสองแบบจาก JSON เดียวกัน เพื่อดูว่า annotation ไหนต้องเปลี่ยนบ้าง

ข้อควรระวังและข้อจำกัด

  • ไทป์ถูกอนุมานจากตัวอย่างที่วางเท่านั้น ฟิลด์ที่มีในทุกรายการของตัวอย่างจะออกมาเป็น non-null ดังนั้นฟิลด์ที่เอกสาร API บอกว่าอาจไม่มี ให้เติม ? เอง
  • สตริงวันที่อย่าง 2024-01-01T00:00:00Z ยังเป็น String ถ้าจะเปลี่ยนเป็น Instant ต้องเขียน serializer เอง
  • kotlinx.serialization serialize Any ไม่ได้ ค่าที่อนุมานไทป์ไม่ได้จึงเป็น JsonElement ในกรณีนั้น และเป็น Any เมื่อใช้ Jackson
  • ไม่สร้าง enum, sealed class หรือค่าเริ่มต้น (เช่น ลิสต์ว่าง) ฟิลด์ที่มีชุดค่าตายตัวควรเปลี่ยนเป็น enum ภายหลัง
  • ทุกคลาสออกมาในบล็อกเดียว การประกาศ package และการแยกไฟล์ต้องทำเอง

คำถามที่พบบ่อย

ทำไมฟิลด์เป็น String? = null ไม่ใช่แค่ String??

kotlinx.serialization โยน MissingFieldException เมื่อไม่มีคีย์และพร็อพเพอร์ตีไม่มีค่าเริ่มต้น การเติม = null ให้ฟิลด์ที่ขาดไปในบางรายการหรือมีค่า null ทำให้ response ที่ไม่มีคีย์นั้น decode ได้โดยไม่มีปัญหา

ใช้คีย์ JSON เป็นชื่อพร็อพเพอร์ตีโดยไม่ต้องมี @SerialName ได้ไหม?

เครื่องมือแปลงเป็น camelCase เสมอและใส่ annotation เฉพาะเมื่อชื่อต่างกัน คีย์ที่เป็น camelCase อยู่แล้วจึงออกมาโดยไม่มี annotation ถ้าอยากเก็บชื่อแบบ snake_case ให้เปลี่ยนชื่อพร็อพเพอร์ตีและลบ annotation หลังสร้างโค้ด

ถ้าเลือก Jackson ต้องใช้ jackson-module-kotlin ไหม?

ต้องใช้ data class ที่สร้างขึ้นไม่มี constructor แบบไม่มีอาร์กิวเมนต์ Jackson จึงต้องลงทะเบียน jackson-module-kotlin เพื่อ bind ค่าผ่านพารามิเตอร์ของ constructor (Spring Boot ลงทะเบียนให้อัตโนมัติเมื่อมี dependency นี้)

สร้างโมเดลสำหรับ Moshi หรือ Gson ได้ไหม?

ตัวเลือก serializer มี kotlinx.serialization กับ Jackson สำหรับ Gson ให้นำผลลัพธ์ของ Jackson มาเปลี่ยน @JsonProperty เป็น @SerializedName ส่วน Moshi ใช้ @Json(name = ...) โครงสร้างคลาสยังเหมือนเดิม