Kotlin Academy · Leçon

Écrire votre premier SymbolProcessor

Implémentez un processeur KSP qui recherche les classes annotées et les journalise.

Écrire votre premier SymbolProcessor est une leçon Kotlin Academy gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Kotlin Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Kotlin Academy comprend 4 leçons au total.

Structure du projet

Un processeur KSP réside dans un module Gradle distinct (par exemple :processor). Le module qui l’utilise applique le plug-in KSP et déclare une dépendance ksp vers le module du processeur. Le module du processeur lui-même possède une dépendance implementation ordinaire envers l’API KSP.

Ajouter les dépendances KSP

Dans le module de votre processeur, dans build.gradle.kts :

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

L’interface SymbolProcessor

Implémentez SymbolProcessor. Le point d’entrée principal est process(resolver: Resolver): List. Renvoyez les symboles que vous n’avez pas pu traiter (par exemple ceux dont les dépendances ne sont pas encore résolues) afin qu’ils soient réexaminés lors d’un second passage.

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

Le SymbolProcessorProvider

KSP découvre votre processeur par l’intermédiaire d’un SymbolProcessorProvider. Enregistrez-le dans 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
        )
}

Le fichier d’enregistrement du service

Créez le fichier à l’emplacement exact dans les ressources du module de votre processeur :

Chemin : src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
Contenu : le nom complet de la classe SymbolProcessorProvider

Résoudre les symboles par annotation

Utilisez resolver.getSymbolsWithAnnotation(fqn) pour obtenir toutes les déclarations annotées avec votre annotation. Filtrez-les selon le type de déclaration attendu (par exemple les déclarations de classes) :

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

Valider les symboles

Avant le traitement, vérifiez que chaque symbole peut être entièrement résolu. Un symbole dont les références de type n’ont pas encore été compilées n’est pas valide. Renvoyez ces symboles depuis process() afin de les réessayer au passage suivant :

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

Visiter une déclaration de classe

Utilisez le modèle de visiteur KSVisitorVoid pour parcourir la structure d’une classe. Redéfinissez visitClassDeclaration pour accéder aux propriétés, aux fonctions et aux classes imbriquées :

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

Consigner des messages depuis un processeur

Utilisez KSPLogger pour émettre des messages à différents niveaux. logger.error() fait échouer la compilation ; logger.warn() affiche un avertissement ; logger.info() affiche un message informatif visible avec --info.

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

Accéder aux annotations d’un symbole

Chaque KSDeclaration possède une séquence annotations. Utilisez filter et arguments pour lire les valeurs des annotations :

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

Indications pour le traitement incrémentiel

Indiquez à KSP de quels symboles d’entrée dépendent les fichiers de sortie en les associant via CodeGenerator.createNewFile(dependencies = ...). KSP peut ainsi ignorer votre processeur lorsqu’aucune de ses entrées n’a changé.

Vérification rapide

Comment KSP découvre-t-il votre implémentation de SymbolProcessorProvider ?

Récapitulatif : écrire votre premier SymbolProcessor

Points essentiels :

Implémentez SymbolProcessor et SymbolProcessorProvider dans un module distinct
Enregistrez le fournisseur via META-INF/services/
Utilisez resolver.getSymbolsWithAnnotation() pour rechercher les symboles annotés
Validez les symboles avant le traitement ; renvoyez ceux qui ne sont pas résolus afin de les réessayer
Utilisez KSPLogger pour les messages lors de la compilation et CodeGenerator pour écrire les fichiers

Questions Fréquemment Posées

La leçon « Écrire votre premier SymbolProcessor » est-elle gratuite ?

Oui — le texte complet de « Écrire votre premier SymbolProcessor » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Kotlin Academy, passe à CoddyKit PRO. Le cours Kotlin Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Écrire votre premier SymbolProcessor » ?

Implémentez un processeur KSP qui recherche les classes annotées et les journalise. Tu pratiques Kotlin Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Kotlin Academy ?

Aucune expérience préalable n'est requise. Kotlin Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Écrire votre premier SymbolProcessor » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Kotlin Academy ?

Oui. Chaque leçon Kotlin Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

KSP ou KAPT : pourquoi KSP est plus rapide
Écrire votre premier SymbolProcessor
Générer des fichiers source Kotlin avec KotlinPoet
Intégrer des processeurs KSP dans une compilation Gradle

← Retour à Kotlin Academy