PricingLoginStart free
Kotlin Academy · Aula

Escrevendo seu primeiro SymbolProcessor

Implemente um processador KSP que procure classes anotadas e as registre.

Aula 2 de 413 etapas

Escrevendo seu primeiro SymbolProcessor é uma aula grátis de Kotlin Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Kotlin Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Kotlin Academy inclui 4 aulas no total.

Estrutura do projeto

Um processador KSP fica em um módulo Gradle separado (por exemplo, :processor). O módulo consumidor aplica o plug-in KSP e declara uma dependência ksp no módulo do processador. O próprio módulo do processador tem uma dependência regular implementation na API do KSP.

Adicionando dependências do KSP

No build.gradle.kts do módulo do processador:

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

A interface SymbolProcessor

Implemente SymbolProcessor. O principal ponto de entrada é process(resolver: Resolver): List. Retorne os símbolos que não conseguiu processar (por exemplo, aqueles cujas dependências ainda não foram resolvidas) para uma segunda rodada.

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

O SymbolProcessorProvider

O KSP descobre seu processador por meio de um SymbolProcessorProvider. Registre-o em 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
        )
}

O arquivo de registro do serviço

Crie o arquivo no caminho exato dentro dos recursos do módulo do processador:

  • Caminho: src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
  • Conteúdo: o nome totalmente qualificado da classe SymbolProcessorProvider

Resolvendo símbolos por anotação

Use resolver.getSymbolsWithAnnotation(fqn) para obter todas as declarações anotadas com sua anotação. Filtre pelo tipo de declaração esperado (por exemplo, declarações de classe):

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

Validando símbolos

Antes do processamento, valide se cada símbolo pode ser totalmente resolvido. Um símbolo cujas referências de tipo ainda não foram compiladas não é válido. Retorne esses símbolos de process() para tentar processá-los novamente na próxima rodada:

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

Visitando uma declaração de classe

Use o padrão de visitante KSVisitorVoid para percorrer a estrutura de uma classe. Substitua visitClassDeclaration para acessar propriedades, funções e classes aninhadas:

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

Registrando mensagens de um processador

Use KSPLogger para emitir mensagens em vários níveis. logger.error() faz a compilação falhar; logger.warn() imprime um aviso; logger.info() imprime uma mensagem informativa visível com --info.

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

Acessando anotações de um símbolo

Cada KSDeclaration tem uma sequência de annotations. Use filter e arguments para ler os valores das anotações:

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

Dicas para processamento incremental

Informe ao KSP de quais símbolos de entrada cada arquivo de saída depende, associando-os por meio de CodeGenerator.createNewFile(dependencies = ...). Isso permite que o KSP ignore o seu processador quando nenhuma das entradas tiver sido alterada.

Verificação rápida

Como o KSP descobre sua implementação de SymbolProcessorProvider?

Responda na aula interativa

Recapitulação: escrevendo seu primeiro SymbolProcessor

Principais conclusões:

  • Implemente SymbolProcessor e SymbolProcessorProvider em um módulo separado
  • Registre o provedor por meio de META-INF/services/
  • Use resolver.getSymbolsWithAnnotation() para localizar símbolos anotados
  • Valide os símbolos antes do processamento; retorne os não resolvidos para uma nova tentativa
  • Use KSPLogger para mensagens durante a compilação e CodeGenerator para gravar arquivos
Grátis para começar

Aprenda Kotlin com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos
51
Aulas
203
Começar a aprender grátisVer o curso completo

Perguntas Frequentes

A aula “Escrevendo seu primeiro SymbolProcessor” é grátis?

Sim — o texto completo de “Escrevendo seu primeiro SymbolProcessor” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Kotlin Academy, atualize para CoddyKit PRO. O curso de Kotlin Academy inclui 4 aulas no total.

O que vou aprender em “Escrevendo seu primeiro SymbolProcessor”?

Implemente um processador KSP que procure classes anotadas e as registre. Você pratica Kotlin Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Kotlin Academy?

Nenhuma experiência prévia é necessária. Kotlin Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Escrevendo seu primeiro SymbolProcessor”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Kotlin Academy?

Sim. Cada aula de Kotlin Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. KSP vs KAPT: por que KSP é mais rápido
  2. Escrevendo seu primeiro SymbolProcessor
  3. Gerando arquivos de código-fonte Kotlin com KotlinPoet
  4. Integrando processadores KSP a uma compilação Gradle
← Voltar para Kotlin Academy