Articolo 3: Integrazione di Jackson per il parsing YAML con TDD in un plugin Gradle
Publié le 25 September 2025
Introduzione
Nello sviluppo di plugin Gradle, la gestione di configurazioni complesse è un compito comune. Piuttosto che sovraccaricare il DSL con centinaia di proprietà, spesso è più pulito e manutenibile definire la configurazione in un file esterno, come YAML. Questo articolo ti guida attraverso l’integrazione della potente biblioteca Jackson per analizzare file YAML in oggetti Kotlin, adottando un approccio TDD rigoroso per garantire la robustezza del nostro plugin.site-baker.
1. Il Contesto : Il nostro Plugin `site-baker
Il nostro plugin`site-baker`è progettato per automatizzare la generazione e il deployment di un sito statico. Ha bisogno di leggere un file di configurazione YAML (managed-jbake-context.yml) per ottenere informazioni quali i percorsi delle sorgenti, le destinazioni di distribuzione e gli identificatori Git
La configurazione YAML che vogliamo analizzare è simile a questa:
bake:
srcPath: "./site/jbake"
destDirPath: "bake"
cname: "cheroliv.com"
pushPage:
from: "bake"
to: "cvs"
repo:
name: "trainings"
repository: "https://github.com/pages-content/pages-content.github.io.git"
credentials:
username: "USERNAME"
password: "SECRET_TOKEN"
branch: "main"
message: "cheroliv.com"
# ... autres configurations (pushMaquette, supabase, etc.)2. Modellazione della configurazione in Kotlin
Prima di eseguire il parsing, dobbiamo definire la struttura dei nostri dati in Kotlin. Jackson utilizzerà queste classi per mappare automaticamente il contenuto YAML.
// plugin/src/main/kotlin/com/cheroliv/site/baker/data/SiteConfiguration.kt
package com.cheroliv.site.baker.data
import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory
import com.fasterxml.jackson.module.kotlin.readValue
import com.fasterxml.jackson.module.kotlin.registerKotlinModule
fun parseSiteConfiguration(yaml: String): SiteConfiguration {
val mapper = ObjectMapper(YAMLFactory()).registerKotlinModule()
return mapper.readValue(yaml)
}
data class GitPushConfiguration(
val from: String = "",
val to: String = "",
val repo: RepositoryConfiguration = RepositoryConfiguration(),
val branch: String = "",
val message: String = "",
)
data class RepositoryConfiguration(
val name: String = "",
val repository: String = "",
val credentials: RepositoryCredentials = RepositoryCredentials(),
) {
companion object {
const val ORIGIN = "origin"
const val CNAME = "CNAME"
const val REMOTE = "remote"
}
}
data class RepositoryCredentials(val username: String = "", val password: String = "")
data class SiteConfiguration(
val bake: BakeConfiguration = BakeConfiguration(),
val pushPage: GitPushConfiguration = GitPushConfiguration(),
val pushMaquette: GitPushConfiguration = GitPushConfiguration(),
val pushSource: GitPushConfiguration? = null,
val pushTemplate: GitPushConfiguration? = null,
val supabase: SupabaseContactFormConfig? = null
)
data class BakeConfiguration(
val srcPath: String = "",
val destDirPath: String = "",
val cname: String? = null,
)
// ... (autres data classes pour Supabase, si nécessaire)La funzione`parseSiteConfiguration`è il nostro punto di ingresso per la deserializzazione. Utilizza`ObjectMapper`di Jackson, configurato con`YAMLFactory`per il formato YAML e`registerKotlinModule()`per il supporto delle specificità di Kotlin (come i valori predefiniti delle proprietà).
3. Integrazione di Jackson nel `build.gradle.kts
Per utilizzare Jackson, dobbiamo aggiungere le dipendenze necessarie nel`build.gradle.kts`del nostro modulo`plugin`:
// plugin/build.gradle.kts
dependencies {
// Jackson for YAML parsing
implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3")
implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3")
// ... autres dépendances
}Noi utilizziamo`jackson-module-kotlin`per il supporto di Kotlin e`jackson-dataformat-yaml`per la gestione del formato YAML.
4. L’approccio TDD: Testare il parsing YAML
Ora, applichiamo il TDD per validare la nostra logica di parsing.
4.1. Test Unitario : Mappare il YAML in Oggetto Kotlin
Iniziamo con un test unitario in`SiteBakerPluginTest.kt`per verificare che la funzione`parseSiteConfiguration`può correttamente trasformare una stringa YAML in un oggetto`SiteConfiguration`.
// plugin/src/test/kotlin/com/cheroliv/site/baker/SiteBakerPluginTest.kt
@Test
fun `can map configuration text to SiteConfiguration object`() {
val yamlString = "../../managed-jbake-context.yml"
.run(::File)
.readText()
.trimIndent()
val config: SiteConfiguration = parseSiteConfiguration(yamlString)
assertEquals("cheroliv.com", config.bake.cname)
assertEquals("main", config.pushPage.branch)
assertEquals("https://github.com/pages-content/pages-content.github.io.git", config.pushPage.repo.repository)
}Questo test legge il contenuto del file`managed-jbake-context.yml`(che deve esistere affinché il test sia valido) e effettua asserzioni sull’oggetto`SiteConfiguration`risultante. Verifica che i valori chiave del YAML siano correttamente mappati.
4.2. Test funzionale: Verificare la lettura del file di configurazione
Per assicurarsi che il plugin possa leggere il file di configurazione tramite il suo DSL e che il parsing funzioni in un ambiente Gradle reale, aggiungiamo un test funzionale in`SiteBakerPluginFunctionalTest.kt`.
Questo test è cruciale perché simula l’esecuzione del plugin in un progetto reale. Deve essereermetico, cioè che deve creare lui stesso il file`managed-jbake-context.yml`con un contenuto controllato, per garantire la riproducibilità e l’isolamento del test.
// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt
@Test
fun `config file contains good data`(){
val configContent = configFile.readText(UTF_8)
// Vérifications comme dans vos commentaires
assertTrue(configContent.contains("bake"))
assertTrue(configContent.contains("pushPage"))
assertTrue(configContent.contains("repository"))
}Questo test funzionale verifica che il file di configurazione copiato nella directory temporanea del test contenga i dati attesi. Sebbene questo test non analizzi direttamente il YAML in un oggetto Kotlin, convalida la presenza del file e del suo contenuto, che è una fase preliminare essenziale per l’analisi da parte del plugin.
5. Visualizzazione del Flusso di Parsing
Il diagramma seguente illustra il flusso di dati e le interazioni durante il parsing della configurazione YAML :
Conclusione
Seguendo un approccio TDD, abbiamo integrato con successo la libreria Jackson per parseare i file di configurazione YAML in oggetti Kotlin all’interno del nostro plugin Gradle. Questo metodo ci ha permesso di:
-
Modellare chiaramentela nostra configurazione con le data class Kotlin.
-
Convalidare la logica di parsingcon test unitari mirati.
-
Garantire l’integrazionein un ambiente Gradle reale grazie a test funzionali ermetici.
Questa solida base ci offre una grande fiducia per estendere il nostro plugin con funzionalità che si basano su questa configurazione, garantendo allo stesso tempo la manutenibilità e la robustezza del codice. Il parsing YAML è ora una funzionalità affidabile e testata del nostro plugin`site-baker`.
Articoli correlati
14 May 2026