Kotlin Academy · Lección

Probar y evolucionar DSL sin perjudicar a los usuarios

Diseñe API de DSL estables y pruébelas con bloques de aserciones legibles.

Probar y evolucionar DSL sin perjudicar a los usuarios es una lección gratuita de Kotlin Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Kotlin Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Kotlin Academy incluye 4 lecciones en total.

Por qué las pruebas de DSL son diferentes

Un DSL es una API pública. Los cambios que se hagan en él pueden romper todos los sitios de llamada del código de los usuarios. Probar un DSL implica verificar tanto la salida que produce como la estructura que impone, incluido que las construcciones no válidas sigan generando errores de compilación.

Probar la salida del DSL

La prueba más sencilla consiste en crear un objeto mediante el DSL y hacer aserciones sobre el resultado renderizado o sobre el estado interno del builder.

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

Probar el estado del builder

En lugar de probar la cadena renderizada, pruebe directamente el grafo de objetos del builder. Esto hace las pruebas más resistentes a los cambios de formato:

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

Probar estructuras anidadas

Recorra el árbol de objetos para verificar las relaciones de anidamiento:

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

Pruebas de errores de compilación

No puede probar directamente los errores de compilación mediante pruebas unitarias, pero puede añadir comentarios como // This should NOT compile y dejar comentado el código que falla. Algunos proyectos utilizan la biblioteca Kotlin Compile Testing para comprobar que determinado código NO compila.

Evolucionar un DSL de forma segura: cambios aditivos

Añadir parámetros opcionales nuevos con valores predeterminados, o nuevas funciones del builder, es compatible con versiones anteriores. Los sitios de llamada existentes compilan sin cambios.

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

Cambio incompatible: eliminar o cambiar nombres

Eliminar o cambiar el nombre de una función del DSL rompe los sitios de llamada. Si debe cambiarle el nombre, proporcione un alias obsoleto y elimínelo en una futura versión principal:

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

Versionar el DSL

En los DSL de bibliotecas, siga el versionado semántico. Los cambios incompatibles del DSL (funciones eliminadas o tipos de receptor modificados) justifican un incremento de la versión principal. Documéntelos en un registro de cambios.

Usar @RequiresOptIn para funciones experimentales del DSL

Marque las extensiones inestables del DSL con @RequiresOptIn. Los usuarios deben aceptarlas explícitamente, lo que evita depender accidentalmente de funciones que pueden cambiar:

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

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

Delegación de propiedades en los DSL

Los DSL pueden utilizar la delegación de propiedades para exigir campos obligatorios y proporcionar mensajes de error claros cuando falta un valor requerido:

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 }
}

Pruebas de contrato entre versiones

Conserve un conjunto de fragmentos de uso del DSL «de referencia» como pruebas. Si una refactorización los rompe, el conjunto de pruebas lo detectará antes que los usuarios. También sirven como documentación viva.

Comprobación rápida

¿Cuál es el tipo de cambio de DSL más seguro para mantener la compatibilidad con versiones anteriores?

Resumen: probar y evolucionar DSL

Conclusiones clave:

Pruebe la salida del DSL y el estado de los objetos del builder mediante pruebas unitarias
Los cambios aditivos (nuevas funciones o parámetros opcionales) son seguros
Use @Deprecated(ReplaceWith=...) para cambiar nombres sin romper el código de los usuarios
Use @RequiresOptIn para las funciones experimentales del DSL
Conserve pruebas de uso de referencia para detectar regresiones entre versiones

Preguntas frecuentes

¿La lección «Probar y evolucionar DSL sin perjudicar a los usuarios» es gratis?

Sí — el texto completo de «Probar y evolucionar DSL sin perjudicar a los usuarios» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Kotlin Academy, actualiza a CoddyKit PRO. El curso de Kotlin Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Probar y evolucionar DSL sin perjudicar a los usuarios»?

Diseñe API de DSL estables y pruébelas con bloques de aserciones legibles. Practicas Kotlin Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Kotlin Academy?

No se requiere experiencia previa. Kotlin Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Probar y evolucionar DSL sin perjudicar a los usuarios»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Kotlin Academy?

Sí. Cada lección de Kotlin Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Lambda con receptor: base de los DSL
@DslMarker: evitar fugas del receptor
Crear un DSL de HTML/configuración seguro respecto a tipos
Probar y evolucionar DSL sin perjudicar a los usuarios

← Volver a Kotlin Academy