Escribir su primer SymbolProcessor
Implemente un procesador KSP que busque clases anotadas y las registre.
Escribir su primer SymbolProcessor es una lección gratuita de Kotlin Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Kotlin Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Kotlin Academy incluye 4 lecciones en total.
Estructura del proyecto
Un procesador de KSP se encuentra en un módulo de Gradle independiente (por ejemplo, :processor). El módulo consumidor aplica el complemento de KSP y declara una dependencia ksp en el módulo del procesador. El propio módulo del procesador tiene una dependencia normal implementation de la API de KSP.
Adición de dependencias de KSP
En el archivo build.gradle.kts de su módulo de procesador:
plugins { kotlin("jvm") }
dependencies {
implementation("com.google.devtools.ksp:symbol-processing-api:2.0.0-1.0.21")
}La interfaz SymbolProcessor
Implemente SymbolProcessor. El punto de entrada principal es process(resolver: Resolver): List. Devuelva los símbolos que no haya podido procesar (por ejemplo, aquellos cuyas dependencias todavía no se hayan resuelto) para una segunda ronda.
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()
}
}SymbolProcessorProvider
KSP detecta su procesador mediante un SymbolProcessorProvider. Regístrelo en 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
)
}El archivo de registro del servicio
Cree el archivo en la ruta exacta dentro de los recursos de su módulo de procesador:
- Ruta:
src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider - Contenido: el nombre completo de su clase
SymbolProcessorProvider
Resolución de símbolos por anotación
Use resolver.getSymbolsWithAnnotation(fqn) para obtener todas las declaraciones anotadas con su anotación. Filtre según el tipo de declaración esperado (por ejemplo, declaraciones de clase):
val classes = resolver
.getSymbolsWithAnnotation("com.example.MyAnnotation")
.filterIsInstance<KSClassDeclaration>()Validación de símbolos
Antes de procesarlos, valide que cada símbolo se pueda resolver por completo. Un símbolo cuyos tipos referenciados todavía no se hayan compilado no es válido. Devuelva esos símbolos desde process() para volver a intentarlo en la siguiente ronda:
val (valid, deferred) = classes.partition { it.validate() }
// process valid; return deferredVisita de una declaración de clase
Use el patrón de visitante KSVisitorVoid para recorrer la estructura de una clase. Sobrescriba visitClassDeclaration para acceder a las propiedades, funciones y clases anidadas:
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}")
}
}Registro desde un procesador
Use KSPLogger para emitir mensajes con distintos niveles. logger.error() hace que falle la compilación; logger.warn() imprime una advertencia; logger.info() imprime un mensaje informativo visible con --info.
logger.info("Processing class: ${classDeclaration.simpleName.asString()}")
logger.error("Missing required annotation", classDeclaration)Acceso a las anotaciones de un símbolo
Cada KSDeclaration tiene una secuencia annotations. Use filter y arguments para leer los valores de las anotaciones:
val ann = classDeclaration.annotations
.first { it.shortName.asString() == "MyAnnotation" }
val value = ann.arguments.first { it.name?.asString() == "value" }.value as StringSugerencias para el procesamiento incremental
Indique a KSP qué archivos de salida dependen de qué símbolos de entrada asociándolos mediante CodeGenerator.createNewFile(dependencies = ...). Esto permite que KSP omita su procesador cuando no haya cambiado ninguna de sus entradas.
Comprobación rápida
¿Cómo detecta KSP su implementación de SymbolProcessorProvider?
Resumen: escritura de su primer SymbolProcessor
Conclusiones clave:
- Implemente
SymbolProcessorySymbolProcessorProvideren un módulo independiente - Registre el proveedor mediante
META-INF/services/ - Use
resolver.getSymbolsWithAnnotation()para buscar símbolos anotados - Valide los símbolos antes de procesarlos; devuelva los que no estén resueltos para volver a intentarlo
- Use
KSPLoggerpara los mensajes durante la compilación yCodeGeneratorpara escribir archivos
Aprende Kotlin con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 51
- Lecciones
- 203
Preguntas frecuentes
¿La lección «Escribir su primer SymbolProcessor» es gratis?
Sí — el texto completo de «Escribir su primer SymbolProcessor» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Kotlin Academy, actualiza a CoddyKit PRO. El curso de Kotlin Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Escribir su primer SymbolProcessor»?
Implemente un procesador KSP que busque clases anotadas y las registre. Practicas Kotlin Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Kotlin Academy?
No se requiere experiencia previa. Kotlin Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.
¿Cuánto tiempo toma la lección «Escribir su primer SymbolProcessor»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Kotlin Academy?
Sí. Cada lección de Kotlin Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- KSP frente a KAPT: por qué KSP es más rápido
- Escribir su primer SymbolProcessor
- Generar archivos fuente de Kotlin con KotlinPoet
- Integrar procesadores KSP en una compilación de Gradle