Kotlin Academy · Pelajaran

Menulis SymbolProcessor Pertama Anda

Implementasikan pemroses KSP yang memindai class beranotasi dan mencatatnya.

Menulis SymbolProcessor Pertama Anda adalah pelajaran Kotlin Academy gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar Kotlin Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus Kotlin Academy mencakup 4 pelajaran total.

Struktur Proyek

Pemroses KSP berada dalam modul Gradle terpisah (misalnya, :processor). Modul pemakai menerapkan plugin KSP dan mendeklarasikan dependensi ksp pada modul pemroses. Modul pemroses itu sendiri memiliki dependensi implementation biasa pada API KSP.

Menambahkan Dependensi KSP

Dalam build.gradle.kts modul pemroses Anda:

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

Antarmuka SymbolProcessor

Implementasikan SymbolProcessor. Titik masuk utamanya adalah process(resolver: Resolver): List. Kembalikan simbol yang belum dapat Anda proses (misalnya, simbol yang dependensinya belum terselesaikan) untuk putaran kedua.

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 menemukan pemroses Anda melalui SymbolProcessorProvider. Daftarkan pemroses tersebut di 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
        )
}

Berkas Pendaftaran Layanan

Buat berkas di jalur yang persis sama dalam sumber daya modul pemroses Anda:

Jalur: src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
Isi: nama berkualifikasi penuh dari kelas SymbolProcessorProvider Anda

Menyelesaikan Simbol berdasarkan Anotasi

Gunakan resolver.getSymbolsWithAnnotation(fqn) untuk mendapatkan semua deklarasi yang diberi anotasi Anda. Saring hasilnya berdasarkan jenis deklarasi yang diharapkan (misalnya, deklarasi kelas):

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

Memvalidasi Simbol

Sebelum memproses, validasikan bahwa setiap simbol dapat diselesaikan sepenuhnya. Simbol yang referensi jenisnya belum dikompilasi belum valid. Kembalikan simbol tersebut dari process() untuk mencobanya lagi pada putaran berikutnya:

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

Menelusuri Deklarasi Kelas

Gunakan pola penelusur KSVisitorVoid untuk menelusuri struktur kelas. Ambil alih visitClassDeclaration untuk mengakses properti, fungsi, dan kelas bertingkat:

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

Pencatatan Log dari Pemroses

Gunakan KSPLogger untuk mengeluarkan pesan pada berbagai tingkat. logger.error() menggagalkan build; logger.warn() mencetak peringatan; logger.info() mencetak pesan informatif yang terlihat dengan --info.

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

Mengakses Anotasi pada Simbol

Setiap KSDeclaration memiliki urutan annotations. Gunakan filter dan arguments untuk membaca nilai anotasi:

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

Petunjuk Pemrosesan Inkremental

Beri tahu KSP berkas keluaran mana yang bergantung pada simbol masukan mana dengan mengaitkannya melalui CodeGenerator.createNewFile(dependencies = ...). Dengan demikian, KSP dapat melewati pemroses Anda jika tidak ada masukannya yang berubah.

Pemeriksaan Singkat

Bagaimana KSP menemukan implementasi SymbolProcessorProvider Anda?

Rangkuman: Menulis SymbolProcessor Pertama Anda

Inti penting:

Implementasikan SymbolProcessor dan SymbolProcessorProvider dalam modul terpisah
Daftarkan penyedia melalui META-INF/services/
Gunakan resolver.getSymbolsWithAnnotation() untuk menemukan simbol beranotasi
Validasikan simbol sebelum pemrosesan; kembalikan simbol yang belum terselesaikan untuk dicoba lagi
Gunakan KSPLogger untuk pesan saat build dan CodeGenerator untuk menulis berkas

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Menulis SymbolProcessor Pertama Anda” gratis?

Ya — teks lengkap “Menulis SymbolProcessor Pertama Anda” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus Kotlin Academy, upgrade ke CoddyKit PRO. Kursus Kotlin Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Menulis SymbolProcessor Pertama Anda”?

Implementasikan pemroses KSP yang memindai class beranotasi dan mencatatnya. Kamu berlatih Kotlin Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai Kotlin Academy?

Tidak diperlukan pengalaman sebelumnya. Kotlin Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Menulis SymbolProcessor Pertama Anda” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran Kotlin Academy ini?

Ya. Setiap pelajaran Kotlin Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

KSP vs KAPT: Mengapa KSP Lebih Cepat
Menulis SymbolProcessor Pertama Anda
Membuat File Sumber Kotlin dengan KotlinPoet
Mengintegrasikan Pemroses KSP ke Build Gradle

← Kembali ke Kotlin Academy