�Άρθρο 3 : Ενσωμάτωση του Jackson για το Parsing YAML με TDD σε ένα Plugin Gradle
Publié le 25 September 2025
Εισαγωγή
Στην ανάπτυξη προσαρμοσμένων Gradle plugins, η διαχείριση phứcαυλών ρυθμίσεων είναι μια συνήθης εργασία. Αντί να φορτίζουμε το DSL με εκατοντάδες ιδιότητες, είναι συνήθως πιο καθαρό και συντήρησιμο να ορίζουμε τη ρυθμίση σε ένα εξωτερικό αρχείο, όπως το YAML. Αυτό το άρθρο σας οδηγεί στην ενσωμάτωση της ισχυρής βιβλιοθήκης Jackson για το ανάλυση αρχείων YAML σε αντικείμενα Kotlin, χρησιμοποιώντας μια αυστηρή προσέγγιση TDD για να διασφαλίσουμε τη σταθερότητα του plugin μας.site-baker.
Το πλαίσιο : Το πρόσθετό μας `site-baker
Το plugin`site-baker`είναι σχεδιασμένο για να αυτοματοποιήσει τη δημιουργία και τη διανομή одного στατικού ιστότοπου. Χρειάζεται να διαβάσει ένα αρχείο ρύθμισης YAML (managed-jbake-context.yml) για να λάβετε πληροφορίες όπως οι διαδρομές των πηγών, οι προορισμοί ανάπτυξης, και τα αναγνωριστικά Git.
Η ρύθμιση YAML που θέλουμε να αναλύουμε φαίνεται ως εξής :
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. Μοντελοποίηση της Διαμόρφωσης στη Kotlin
Πριν από το parsing, πρέπει να ορίσουμε τη δομή των δεδομένων μας σε Kotlin. Το Jackson θα χρησιμοποιήσει αυτές τις κλάσεις για να αντιστοιχίσει αυτόματα το περιεχόμενο του 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)
Η λειτουργία`parseSiteConfiguration`είναι το σημείο εισόδου μας για την αποσειριαλισμό. Χρησιμοποιεί`ObjectMapper`του Τζέκσον, ρυθμισμένο με`YAMLFactory`για τη μορφή YAML και`registerKotlinModule()`για τη υποστήριξη των ιδιοτητών του Kotlin (όπως οι προεπιλεγμένες τιμές των ιδιοτήτων).
3. Ενσωμάτωση του Jackson στο `build.gradle.kts
Για να χρησιμοποιήσουμε το Jackson, πρέπει να προσθέσουμε τις απαραίτητες εξαρτήσεις στο`build.gradle.kts`του module μας`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
}
Χρησιμοποιούμε`jackson-module-kotlin`για την υποστήριξη του Kotlin και`jackson-dataformat-yaml`για τη διαχείριση του format YAML.
4. Η προσέγγιση TDD : Δοκιμή του parsing YAML
Τώρα, εφαρμόζουμε το TDD για να επικυρώσουμε τη λογική parsing.
4.1. Τεστ μονάδας : Αντιστοίχιση YAML σε αντικείμενο Kotlin
�Ξεκινάμε με ένα τεστ μονάδας στο`SiteBakerPluginTest.kt`για να ελέγξουμε ότι η συνάρτηση`parseSiteConfiguration`μπορεί να μετατρέψει σωστά μια συμβολοσειρά YAML σε ένα αντικείμενο`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)
}
Αυτός ο έλεγχος διαβάζει το περιεχόμενο του αρχείου`managed-jbake-context.yml`(που πρέπει να υπάρχει ώστε ο δοκίμιο να είναι έγκυρος) και κάνει επιβεβαιώσεις στο αντικείμενο`SiteConfiguration`αποτέλεσμα. Επικυρώνει ότι οι κλειδιές τιμές του YAML έχουν σωστά αντιστοιχιστεί.
4.2. Έλεγχος λειτουργικότητας: Επαλήθευση ανάγνωσης του αρχείου ρύθμισης
Για να βεβαιωθούμε ότι το plugin μπορεί να διαβάσει το αρχείο ρυθμίσεων μέσω του DSL του και ότι το parsing λειτουργεί σε ένα πραγματικό περιβάλλον Gradle, προσθέτουμε έναν λειτουργικό τεστ σε`SiteBakerPluginFunctionalTest.kt`.
Αυτό το τεστ είναι ζωτικής σημασίας επειδή προσομοιάζει την εκτέλεση του plugin σε ένα πραγματικό έργο. Πρέπει ναερμητικός, δηλαδή πρέπει να το φτιάξει ο ίδιος το αρχείο`managed-jbake-context.yml`με ελεγχόμενο περιεχόμενο, για να εγγυηθεί την επαναλαμβανιμότητα και την απομόνωση του τεστ.
// 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"))
}
Αυτή η λειτουργική δοκιμή επαληθεύει ότι το αρχείο ρυθμίσεων που αντιγράφεται στον προσωρινό κατάλογο της δοκιμής περιέχει τις αναμενόμενες δεδομένες. Αν και αυτή η δοκιμή δεν αναλύει άμεσα το YAML σε αντικείμενο Kotlin, επικυρώνει την παρουσία του αρχείου και του περιεχομένου του, κάτι που είναι μια ουσιώδη πρόπτωση πριν από την ανάλυση από το πρόσθετο.
5. Εμφάνιση του Ροής Ανάλυσης
Το επόμενο διάγραμμα απεικονίζει τη ροή των δεδομένων και τις αλληλεπιδράσεις κατά την ανάλυση της διαμόρφωσης YAML :
Συμπέρασμα
Ακολουθώντας μια προσέγγιση TDD, ενσωματώσαμε με επιτυχία τη βιβλιοθήκη Jackson για να αναλύουμε αρχεία ρυθμίσεων YAML σε αντικείμενα Kotlin στο plugin Gradle μας. Αυτή η μέθοδος μας επέτρεψε να:
-
Μοντελοποιήστε σαφώςη διαμόρφωσή μας με τις Kotlin κλάσεις δεδομένων.
-
Επικυρώστε τη λογική ανάλυσηςμε στοχευμένα τεστ μονάδας.
-
Ασφάλιση της ενσωμάτωσηςσε ένα πραγματικό περιβάλλον Gradle χάρη στα ακαταπαύτα λειτουργικά δοκιμές.
Αυτή η σταθερά βάση μας παρέχει μεγάλη εμπιστοσύνη για να επεκτείνουμε το plugin μας με λειτουργίες που βασίζονται σε αυτήν τη ρύθμιση, διασφαλίζοντες την συντηρησιμότητα και την ανθεκτικότητα του κώδικα. Το parsing YAML είναι τώρα μια αξιόπιστη και δοκιμασμένη λειτουργία του plugin μας.site-baker.