Kotlin Academy · Pelajaran

Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna

Rancang API DSL yang stabil dan ujilah dengan blok assertion yang mudah dibaca.

Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna adalah pelajaran Kotlin Academy gratis di CoddyKit. Ini adalah pelajaran 4 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar Kotlin Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus Kotlin Academy mencakup 4 pelajaran total.

Mengapa Pengujian DSL Berbeda

DSL adalah API publik. Perubahannya dapat merusak setiap pemanggilan dalam kode pengguna. Menguji DSL berarti memverifikasi keluaran yang dihasilkannya dan struktur yang diberlakukannya—termasuk memastikan bahwa konstruksi yang tidak valid tetap menjadi galat kompilasi.

Menguji Keluaran DSL

Pengujian paling sederhana: buat objek menggunakan DSL dan lakukan penegasan terhadap hasil render atau keadaan internal pembangun.

@Test
fun `div contains a paragraph`() {
    val result = html {
        body {
            div { p("Hi") }
        }
    }
    assertTrue(result.render().contains("<p>"))
}

Menguji Keadaan Pembangun

Alih-alih menguji string hasil render, ujilah graf objek pembangun secara langsung. Ini lebih tahan terhadap perubahan pemformatan:

@Test
fun `server config has correct port`() {
    val cfg = server {
        host = "example.com"
        port = 9090
    }
    assertEquals(9090, cfg.port)
    assertEquals("example.com", cfg.host)
}

Menguji Struktur Bersarang

Telusuri pohon objek untuk memverifikasi hubungan penyarangan:

@Test
fun `body contains one div`() {
    val page = html { body { div { } } }
    assertEquals(1, page.children
        .filterIsInstance<Body>().first()
        .children.filterIsInstance<Div>().size
    )
}

Pengujian Galat Kompilasi

Anda tidak dapat menguji galat kompilasi dengan pengujian unit secara langsung, tetapi Anda dapat menambahkan komentar seperti // This should NOT compile dengan kode yang gagal dikomentari. Beberapa proyek menggunakan pustaka Kotlin Compile Testing untuk memastikan bahwa kode tertentu tidak dikompilasi.

Mengembangkan DSL dengan Aman: Perubahan Aditif

Menambahkan parameter opsional baru dengan nilai bawaan, atau fungsi pembangun baru, kompatibel mundur. Pemanggilan yang ada tetap dikompilasi tanpa perubahan.

// Before
fun server(block: ServerConfig.() -> Unit): ServerConfig
// After — additive: new optional feature
fun server(enableMetrics: Boolean = false, block: ServerConfig.() -> Unit): ServerConfig

Perubahan yang Merusak: Menghapus atau Mengganti Nama

Menghapus atau mengganti nama fungsi DSL merusak pemanggilan yang ada. Jika harus mengganti nama, sediakan alias yang ditandai tidak berlaku lagi dan hapus pada versi mayor mendatang:

@Deprecated("Use database{} instead", ReplaceWith("database(block)"))
fun db(block: DbConfig.() -> Unit) = database(block)

Membuat Versi DSL Anda

Untuk DSL pustaka, ikuti pembuatan versi semantik. Perubahan DSL yang merusak (fungsi yang dihapus, tipe penerima yang diubah) layak mendapatkan kenaikan versi mayor. Dokumentasikan perubahan tersebut dalam catatan perubahan.

Menggunakan @RequiresOptIn untuk Fitur DSL Eksperimental

Tandai ekstensi DSL yang tidak stabil dengan @RequiresOptIn. Pengguna memilih ikut serta secara eksplisit, sehingga mencegah ketergantungan yang tidak disengaja pada fitur yang mungkin berubah:

@RequiresOptIn(message = "This DSL feature is experimental and may change")
annotation class ExperimentalDsl

@ExperimentalDsl
fun ServerConfig.enableDebug() { /*...*/ }

Delegasi Properti dalam DSL

DSL dapat menggunakan delegasi properti untuk memastikan bidang wajib diisi dan memberikan pesan galat yang jelas ketika nilai wajib tidak ada:

class Required<T> {
    private var value: T? = null
    operator fun getValue(t: Any?, p: KProperty<*>): T = value ?: error("${p.name} is required")
    operator fun setValue(t: Any?, p: KProperty<*>, v: T) { value = v }
}

Pengujian Kontrak Lintas Versi

Simpan sekumpulan cuplikan penggunaan DSL “acuan” sebagai pengujian. Jika refaktor merusaknya, rangkaian pengujian akan menangkapnya sebelum pengguna menemukannya. Cuplikan ini juga berfungsi sebagai dokumentasi yang terus diperbarui.

Pemeriksaan Singkat

Jenis perubahan DSL apa yang paling aman untuk kompatibilitas mundur?

Ringkasan: Menguji dan Mengembangkan DSL

Hal-hal utama:

Uji keluaran DSL dan keadaan objek pembangun dalam pengujian unit
Perubahan aditif (fungsi/parameter opsional baru) aman
Gunakan @Deprecated(ReplaceWith=...) untuk mengganti nama tanpa merusak pengguna
Gunakan @RequiresOptIn untuk fitur DSL eksperimental
Simpan pengujian penggunaan acuan untuk menangkap regresi lintas versi

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna” gratis?

Ya — teks lengkap “Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus Kotlin Academy, upgrade ke CoddyKit PRO. Kursus Kotlin Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna”?

Rancang API DSL yang stabil dan ujilah dengan blok assertion yang mudah dibaca. Kamu berlatih Kotlin Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai Kotlin Academy?

Tidak diperlukan pengalaman sebelumnya. Kotlin Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 4 dari 4.

Berapa lama pelajaran “Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran Kotlin Academy ini?

Ya. Setiap pelajaran Kotlin Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Lambda dengan Receiver: Dasar DSL
@DslMarker: Mencegah Kebocoran Receiver
Membangun DSL HTML/Config yang Aman terhadap Tipe
Menguji dan Mengembangkan DSL Tanpa Mengganggu Pengguna

← Kembali ke Kotlin Academy