Kotlin Academy · レッスン

最初のSymbolProcessorを作成する

アノテーション付きクラスを検索してログに記録するKSPプロセッサーを実装します。

レッスン 2/413 ステップ

「最初のSymbolProcessorを作成する」はCoddyKit上の無料Kotlin Academyレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはKotlin Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Kotlin Academyコースには全4レッスンが含まれています。

プロジェクト構成

KSPプロセッサは、独立したGradleモジュール(例::processor)に配置します。利用側のモジュールでKSPプラグインを適用し、プロセッサモジュールへのksp依存関係を宣言します。プロセッサモジュール自体では、KSP APIに対する通常のimplementation依存関係を宣言します。

KSP依存関係の追加

プロセッサモジュールのbuild.gradle.ktsで次のように設定します。

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

SymbolProcessorインターフェース

SymbolProcessorを実装します。主なエントリポイントはprocess(resolver: Resolver): Listです。処理できなかったシンボル(依存関係がまだ解決されていないシンボルなど)を返すと、次のラウンドで再処理されます。

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はSymbolProcessorProviderを通じてプロセッサを検出します。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
        )
}

サービス登録ファイル

プロセッサモジュールのresources内に、指定された正確なパスでファイルを作成します。

  • パス:src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
  • 内容:SymbolProcessorProviderクラスの完全修飾名

アノテーションによるシンボルの解決

resolver.getSymbolsWithAnnotation(fqn)を使うと、指定したアノテーションが付与されたすべての宣言を取得できます。取得したシンボルを、想定する宣言の種類(クラス宣言など)に絞り込みます。

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

シンボルの検証

処理する前に、各シンボルを完全に解決できることを確認します。型の参照先がまだコンパイルされていないシンボルは有効ではありません。そのようなシンボルをprocess()から返すと、次のラウンドで再試行されます。

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

クラス宣言の訪問

KSVisitorVoidのビジターパターンを使って、クラスの構造を走査します。visitClassDeclarationをオーバーライドすると、プロパティ、関数、ネストされたクラスにアクセスできます。

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

プロセッサからのログ出力

KSPLoggerを使って、さまざまなレベルのメッセージを出力します。logger.error()はビルドを失敗させ、logger.warn()は警告を表示し、logger.info()は--infoで表示できる情報メッセージを出力します。

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

シンボルのアノテーションへのアクセス

各KSDeclarationにはannotationsシーケンスがあります。filterとargumentsを使って、アノテーションの値を読み取ります。

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

インクリメンタル処理のヒント

CodeGenerator.createNewFile(dependencies = ...)を使って、どの出力ファイルがどの入力シンボルに依存するかを関連付け、その情報をKSPに伝えます。これにより、入力に変更がなければKSPはプロセッサをスキップできます。

確認問題

KSPはSymbolProcessorProviderの実装をどのように検出しますか。

まとめ:最初のSymbolProcessorを書く

重要なポイント:

  • 独立したモジュールでSymbolProcessorとSymbolProcessorProviderを実装します
  • META-INF/services/を通じてプロバイダを登録します
  • resolver.getSymbolsWithAnnotation()を使ってアノテーションが付与されたシンボルを見つけます
  • 処理前にシンボルを検証し、解決できないシンボルは再試行のために返します
  • ビルド時のメッセージにはKSPLoggerを、ファイルの書き出しにはCodeGeneratorを使用します
無料で開始

AI チューターと学ぶ Kotlin — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース
51
レッスン
203

よくある質問

「最初のSymbolProcessorを作成する」レッスンは無料ですか?

はい。「最初のSymbolProcessorを作成する」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し(組み込みコードエディタと24時間対応のAIチューター)、Kotlin Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Kotlin Academyコースには全4レッスンが含まれています。

「最初のSymbolProcessorを作成する」で何を学びますか?

アノテーション付きクラスを検索してログに記録するKSPプロセッサーを実装します。 ブラウザで直接実行するハンズオンコードでKotlin Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Kotlin Academyを始めるのに経験は必要ですか?

事前経験は必要ありません。CoddyKitのKotlin Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。

「最初のSymbolProcessorを作成する」レッスンにはどのくらい時間がかかりますか?

ほとんどのCoddyKitレッスンは約5~10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このKotlin Academyレッスンでコードを書いて実行できますか?

はい。すべてのKotlin Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. KSPとKAPT:KSPが高速な理由
  2. 最初のSymbolProcessorを作成する
  3. KotlinPoetによるKotlinソースファイルの生成
  4. GradleビルドへのKSPプロセッサーの統合
← Kotlin Academyに戻る