0Pricing
Kotlin Academy · Lezione

Scrivere il primo SymbolProcessor

Implementi un processore KSP che individui le classi annotate e le registri nei log.

Scrivere il primo SymbolProcessor è una lezione Kotlin Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Kotlin Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Kotlin Academy include 4 lezioni in totale.

Struttura del progetto

Un processore KSP risiede in un modulo Gradle separato, ad esempio :processor. Il modulo che lo utilizza applica il plugin KSP e dichiara una dipendenza ksp dal modulo del processore. Il modulo del processore, invece, ha una normale dipendenza implementation dall'API KSP.

Aggiunta delle dipendenze KSP

Nel file build.gradle.kts del modulo del processore:

plugins { kotlin("jvm") }
dependencies {
    implementation("com.google.devtools.ksp:symbol-processing-api:2.0.0-1.0.21")
}

L'interfaccia SymbolProcessor

Implementi SymbolProcessor. Il punto di ingresso principale è process(resolver: Resolver): List. Restituisca i simboli che non è stato possibile elaborare, ad esempio quelli le cui dipendenze non sono ancora state risolte, affinché vengano elaborati in un secondo passaggio.

import com.google.devtools.ksp.processing.*
import com.google.devtools.ksp.symbol.*

class MyProcessor(private val logger: KSPLogger,
                  private val codeGenerator: CodeGenerator) : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        val symbols = resolver.getSymbolsWithAnnotation("com.example.MyAnnotation")
        // process symbols here
        return emptyList()
    }
}

Il SymbolProcessorProvider

KSP individua il processore tramite un SymbolProcessorProvider. Lo registri in resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider:

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
        MyProcessor(
            logger = environment.logger,
            codeGenerator = environment.codeGenerator
        )
}

Il file di registrazione del servizio

Crei il file nel percorso esatto all'interno delle risorse del modulo del processore:

  • Percorso: src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
  • Contenuto: il nome completo della classe SymbolProcessorProvider

Risoluzione dei simboli tramite annotazione

Utilizzi resolver.getSymbolsWithAnnotation(fqn) per ottenere tutte le dichiarazioni annotate con l'annotazione specificata. Filtri in base al tipo di dichiarazione previsto, ad esempio le dichiarazioni di classe:

val classes = resolver
    .getSymbolsWithAnnotation("com.example.MyAnnotation")
    .filterIsInstance<KSClassDeclaration>()

Validazione dei simboli

Prima dell'elaborazione, verifichi che ogni simbolo sia completamente risolvibile. Un simbolo i cui riferimenti ai tipi non sono ancora stati compilati non è valido. Restituisca tali simboli da process() per ritentarne l'elaborazione nel passaggio successivo:

val (valid, deferred) = classes.partition { it.validate() }
// process valid; return deferred

Visita di una dichiarazione di classe

Utilizzi il pattern visitor di KSVisitorVoid per attraversare la struttura di una classe. Esegua l'override di visitClassDeclaration per accedere a proprietà, funzioni e classi annidate:

class MyVisitor : KSVisitorVoid() {
    override fun visitClassDeclaration(classDeclaration: KSClassDeclaration, data: Unit) {
        val name = classDeclaration.simpleName.asString()
        val props = classDeclaration.getAllProperties().toList()
        println("Class: $name, props: ${props.size}")
    }
}

Registrazione dei messaggi da un processore

Utilizzi KSPLogger per emettere messaggi a diversi livelli. logger.error() interrompe la build; logger.warn() stampa un avviso; logger.info() stampa un messaggio informativo visibile con --info.

logger.info("Processing class: ${classDeclaration.simpleName.asString()}")
logger.error("Missing required annotation", classDeclaration)

Accesso alle annotazioni di un simbolo

Ogni KSDeclaration dispone di una sequenza annotations. Utilizzi filter e arguments per leggere i valori delle annotazioni:

val ann = classDeclaration.annotations
    .first { it.shortName.asString() == "MyAnnotation" }
val value = ann.arguments.first { it.name?.asString() == "value" }.value as String

Indicazioni per l'elaborazione incrementale

Indichi a KSP da quali simboli di input dipendono i file di output associandoli tramite CodeGenerator.createNewFile(dependencies = ...). In questo modo KSP può saltare il processore quando nessuno dei suoi input è cambiato.

Verifica rapida

Come individua KSP l'implementazione di SymbolProcessorProvider?

Riepilogo: scrivere il primo SymbolProcessor

Punti chiave:

  • Implementi SymbolProcessor e SymbolProcessorProvider in un modulo separato
  • Registri il provider tramite META-INF/services/
  • Utilizzi resolver.getSymbolsWithAnnotation() per trovare i simboli annotati
  • Validi i simboli prima dell'elaborazione; restituisca quelli non risolti per un nuovo tentativo
  • Utilizzi KSPLogger per i messaggi in fase di build e CodeGenerator per scrivere i file

Domande Frequenti

La lezione «Scrivere il primo SymbolProcessor» è gratuita?

Sì — il testo completo di «Scrivere il primo SymbolProcessor» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Kotlin Academy, passa a CoddyKit PRO. Il corso Kotlin Academy include 4 lezioni in totale.

Cosa imparerò in «Scrivere il primo SymbolProcessor»?

Implementi un processore KSP che individui le classi annotate e le registri nei log. Eserciti Kotlin Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Kotlin Academy?

Non è richiesta alcuna esperienza precedente. Kotlin Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Scrivere il primo SymbolProcessor»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Kotlin Academy?

Sì. Ogni lezione Kotlin Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. KSP e KAPT: perché KSP è più veloce
  2. Scrivere il primo SymbolProcessor
  3. Generare file sorgente Kotlin con KotlinPoet
  4. Integrare i processori KSP in una build Gradle
← Torna a Kotlin Academy