0Pricing
Kotlin Academy · Lektion

Ihren ersten SymbolProcessor schreiben

Implementieren Sie einen KSP-Prozessor, der annotierte Klassen findet und protokolliert.

Ihren ersten SymbolProcessor schreiben ist eine kostenlose Kotlin Academy-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Kotlin Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Kotlin Academy-Kurs umfasst insgesamt 4 Lektionen.

Projektstruktur

Ein KSP-Prozessor befindet sich in einem separaten Gradle-Modul (z. B. :processor). Das konsumierende Modul wendet das KSP-Plugin an und deklariert eine ksp-Abhängigkeit auf das Prozessormodul. Das Prozessormodul selbst besitzt eine reguläre implementation-Abhängigkeit auf die KSP-API.

KSP-Abhängigkeiten hinzufügen

In der Datei build.gradle.kts Ihres Prozessormoduls:

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

Das SymbolProcessor-Interface

Implementieren Sie SymbolProcessor. Der zentrale Einstiegspunkt ist process(resolver: Resolver): List. Geben Sie Symbole zurück, die Sie nicht verarbeiten konnten (z. B. solche, deren Abhängigkeiten noch nicht aufgelöst wurden), damit sie in einer zweiten Runde erneut verarbeitet werden.

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

Der SymbolProcessorProvider

KSP findet Ihren Prozessor über einen SymbolProcessorProvider. Registrieren Sie ihn unter 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
        )
}

Die Service-Registrierungsdatei

Erstellen Sie die Datei am exakten Pfad in den Ressourcen Ihres Prozessormoduls:

  • Pfad: src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
  • Inhalt: der vollständig qualifizierte Name Ihrer SymbolProcessorProvider-Klasse

Symbole nach Annotation auflösen

Verwenden Sie resolver.getSymbolsWithAnnotation(fqn), um alle mit Ihrer Annotation versehenen Deklarationen abzurufen. Filtern Sie nach dem erwarteten Deklarationstyp (z. B. Klassendeklarationen):

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

Symbole validieren

Überprüfen Sie vor der Verarbeitung, ob jedes Symbol vollständig aufgelöst werden kann. Ein Symbol, dessen Typreferenzen noch nicht kompiliert wurden, ist nicht gültig. Geben Sie solche Symbole aus process() zurück, damit sie in der nächsten Runde erneut verarbeitet werden:

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

Eine Klassendeklaration besuchen

Verwenden Sie das Besuchermuster von KSVisitorVoid, um die Struktur einer Klasse zu durchlaufen. Überschreiben Sie visitClassDeclaration, um auf Properties, Funktionen und verschachtelte Klassen zuzugreifen:

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

Aus einem Prozessor protokollieren

Verwenden Sie KSPLogger, um Meldungen auf verschiedenen Ebenen auszugeben. logger.error() schlägt den Build fehl; logger.warn() gibt eine Warnung aus; logger.info() gibt eine Informationsmeldung aus, die mit --info sichtbar ist.

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

Auf Annotationen eines Symbols zugreifen

Jede KSDeclaration verfügt über eine annotations-Sequenz. Verwenden Sie filter und arguments, um Annotation-Werte auszulesen:

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

Hinweise zur inkrementellen Verarbeitung

Teilen Sie KSP mit, von welchen Eingabesymbolen die jeweiligen Ausgabedateien abhängen, indem Sie sie über CodeGenerator.createNewFile(dependencies = ...) miteinander verknüpfen. Dadurch kann KSP Ihren Prozessor überspringen, wenn sich keine seiner Eingaben geändert hat.

Kurzer Test

Wie findet KSP Ihre Implementierung von SymbolProcessorProvider?

Zusammenfassung: Ihren ersten SymbolProcessor schreiben

Die wichtigsten Punkte:

  • Implementieren Sie SymbolProcessor und SymbolProcessorProvider in einem separaten Modul
  • Registrieren Sie den Provider über META-INF/services/
  • Verwenden Sie resolver.getSymbolsWithAnnotation(), um annotierte Symbole zu finden
  • Validieren Sie Symbole vor der Verarbeitung und geben Sie nicht aufgelöste Symbole zur erneuten Verarbeitung zurück
  • Verwenden Sie KSPLogger für Build-Zeit-Meldungen und CodeGenerator zum Schreiben von Dateien

Häufig gestellte Fragen

Ist die Lektion „Ihren ersten SymbolProcessor schreiben“ kostenlos?

Ja — der vollständige Text von „Ihren ersten SymbolProcessor schreiben“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Kotlin Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Kotlin Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Ihren ersten SymbolProcessor schreiben“?

Implementieren Sie einen KSP-Prozessor, der annotierte Klassen findet und protokolliert. Du übst Kotlin Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Kotlin Academy zu starten?

Keine Vorkenntnisse erforderlich. Kotlin Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Ihren ersten SymbolProcessor schreiben“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Kotlin Academy-Lektion Code schreiben und ausführen?

Ja. Jede Kotlin Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

  1. KSP vs. KAPT: Warum KSP schneller ist
  2. Ihren ersten SymbolProcessor schreiben
  3. Kotlin-Quelldateien mit KotlinPoet generieren
  4. KSP-Prozessoren in einen Gradle-Build integrieren
← Zurück zu Kotlin Academy