Articolo 4 : La trappola della cache di configurazione Gradle
Publié le 26 September 2025
Introduzione
Nella nostra avventura di creazione del plugin`site-baker`, abbiamo seguito un approccio TDD rigoroso. Ogni funzionalità era testata, validata, e avanzavamo con fiducia. E poi, un giorno, l’imprevisto è arrivato. Le build hanno iniziato a comportarsi in modo erratico. Le modifiche nella logica del plugin o nei file di configurazione sembravano essere ignorate, e i nostri test funzionali, un tempo affidabili, fallivano senza motivo apparente.
Questo tipo di problema può essere incredibilmente frustrante. Mette in dubbio l’affidabilità dello strumento e la validità del nostro codice. Dopo una sessione di debug intenso, il colpevole è stato identificato: ilcache di configurazione di Gradle.
Il Sintomo : Build Fantasma
Il problema si manifestava in diversi modi:
-
Stavo modificando una stringa di caratteri in un’attività`println`, ma la vecchia stringa continuava a essere visualizzata durante l’esecuzione.
-
Stavo cambiando un valore nel mio file`managed-jbake-context.yml`, ma il plugin agiva come se il file non fosse stato modificato.
-
I test funzionali, che creano progetti di test al volo, fallivano perché il plugin sembrava non rilevare i file di configurazione appena creati.
Tutto procedeva come se Gradle stesse eseguendo una "versione fantasma" del nostro build, ignorando i nostri cambiamenti più recenti.
L’indagine: cos’è il Cache di configurazione?
La cache di configurazione è una funzionalità relativamente moderna ed estremamente potente di Gradle, attivata per impostazione predefinita nelle versioni più recenti. Il suo scopo è rendere le build più veloci.
-
Durante la prima esecuzione, Gradle esegue la fase diconfigurazione(lettura delle`build.gradle.kts`, creazione delle attività, risoluzione delle dipendenze) e costruisce un grafo di attività
-
Alla fine di questa fase, GradleSerializza questo grafo di attivitàe lo mette in cache.
-
Durante le esecuzioni successive, se niente è cambiato (script di build,
gradle.properties, etc.), Gradlesalta completamente la fase di configurazionee riutilizza il grafo delle attività memorizzato nella cache.
Il risparmio di tempo è spettacolare sui grandi progetti. Tuttavia, questa performance ha un prezzo: impone regole severe sul modo in cui i plugin devono essere scritti.
Il ciclo di vita della cache di configurazione
La causa del problema: un plugin non conforme
Il nostro plugin`site-baker`violava, senza saperlo, varie regole della cache di configurazione. Perché un grafo di attività sia serializzabile, le attività non devono contenere riferimenti a oggetti complessi come l’oggetto`Project`o leggere i file in modo arbitrario durante la fase di esecuzione.
Il nostro errore principale era leggere il contenuto del file YAML direttamente all’interno della logica di esecuzione dell’attività, utilizzando un riferimento al percorso memorizzato nella nostra estensione. Questo approccio è incompatibile con la cache perché Gradle non può sapere se il contenuto del file è cambiato se questa lettura non viene modellata come unavoce di attività(Input del compito).
La soluzione temporanea : Disattivare la cache
Per sbloccarci e ritrovare un comportamento di build prevedibile, la soluzione più rapida è stata disattivare il cache di configurazione. Basta aggiungere la seguente riga nel file`gradle.properties`del progetto che utilizza il plugin (o nel nostro caso, il progetto di test`site-baker`).
# site-baker/gradle.properties
org.gradle.configuration-cache=falseIstantaneamente, le build hanno ritrovato il loro comportamento normale. Ogni esecuzione riavviava la fase di configurazione e le nostre modifiche venivano prese in considerazione.
Tuttavia, è una soluzione di ripiego, non una soluzione durevole. Sacrifica le prestazioni e non risolve il problema di fondo del nostro plugin.
La Vera Soluzione: Rendere il Plugin Compatibile
Perché un plugin sia un buon cittadino dell’ecosistema Gradle moderno, deve essere compatibile con la cache di configurazione. Ciò implica di ripensare il modo in cui i dati fluiscono verso le nostre attività.
La chiave è di usare leProvider APIsdi Gradle. Al posto di passare valori diretti (come un`String` ou un File) alle nostre attività, dobbiamo passare dei`Property<T>`o dei`Provider<T>`.
-
Dichiarare le voci delle attività :L’operazione che analizza il file YAML deve dichiarare questo file come un input. Per questo si utilizza l’annotazione`@InputFile`. (note: there is a space after the period)
[source,kotlin] [Attesa del testo francese da tradurre] @get:InputFile abstract val configFile: RegularFileProperty ----
Articoli correlati
14 May 2026