Kotlin Academy · レッスン

カスタムアノテーションの作成と対象指定

Q: 「カスタムアノテーションの作成と対象指定」で何を学びますか？

保持ポリシーを持つアノテーションを定義し、クラス、関数、プロパティに適用します。 ブラウザで直接実行するハンズオンコードでKotlin Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

保持ポリシーを持つアノテーションを定義し、クラス、関数、プロパティに適用します。

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

カスタムアノテーションを使う理由

アノテーションは、宣言（クラス、関数、プロパティ、パラメータ）に付加されるメタデータです。カスタムアノテーションを使うと、フレームワーク、ビルドツール（KSP／KAPT）、または独自の実行時ロジックで処理するコードに印を付けられます。

アノテーションを宣言する

annotation classキーワードを使用します。アノテーションクラスにはコンストラクタパラメータを持たせられます（使用できるのはプリミティブ型、String、KClass、列挙型、他のアノテーション、またはそれらの配列だけです）。

annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

メタアノテーション：@Target

@Targetは、アノテーションを使用できる場所を制限します。一般的なターゲットには、CLASS、FUNCTION、PROPERTY、FIELD、VALUE_PARAMETER、CONSTRUCTORがあります。

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

@Retention：アノテーションはいつ利用できるか

@Retentionは、アノテーションの有効期間を制御します。

SOURCE — コンパイル後に破棄される
BINARY — .classファイルに保存されるが、リフレクションからは参照できない
RUNTIME — 保存され、実行時に参照できる（ほとんどの用途でのデフォルト）

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable：同じアノテーションを複数回適用する

デフォルトでは、1つの宣言にアノテーションを適用できるのは1回だけです。@Repeatableを付けると、複数回適用できるようになります。

@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)

コンストラクタとパラメータにアノテーションを付ける

コンストラクタのパラメータと、プライマリコンストラクタのプロパティにアノテーションを付けられます。@field:、@get:、@param:のuse-siteターゲットを使用すると、どの要素にアノテーションを付けるかを制御できます。

data class User(
    @field:Validate(minLength = 2) val name: String,
    @field:Validate(minLength = 0, maxLength = 120) val email: String
)

ユースサイトターゲット

Kotlinは、1つのプロパティから複数のバイトコード要素（フィールド、getter、setter、パラメータ）を生成します。use-siteターゲットは、どの要素にアノテーションを付けるかを指定します。

@field: バッキングフィールド
@get: getter
@set: setter
@param: コンストラクタパラメータ

クラスにアノテーションを付ける

クラスに付けるアノテーションは、フレームワークによる処理の対象であることを示すのに役立ちます（たとえば、シリアライズ可能、インジェクション可能、特定のモジュールの一部であることを示します）。

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository

@Repository
class UserRepository

@MustBeDocumented

@MustBeDocumentedを追加すると、生成されたAPIドキュメントにそのアノテーションが確実に表示されます。公開APIの契約の一部となるアノテーションに使用してください。

@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)

アノテーションパラメータ：デフォルト値と配列

パラメータにはデフォルト値を設定でき、varargキーワードまたは明示的な配列型を使って配列を受け取ることもできます。

annotation class Roles(vararg val value: String)

@Roles("ADMIN", "EDITOR")
class AdminPanel

アノテーションのKClassパラメータ

アノテーションでは、KClassを使ってクラス型を参照できます。

annotation class Serializer(val using: KClass<out Any>)

@Serializer(using = GsonAdapter::class)
class Event

クイックチェック

カスタムアノテーションを実行時にKotlinリフレクションから利用可能にする@Retentionの値はどれですか？

まとめ：カスタムアノテーション

主なポイント：

annotation classで宣言する。パラメータに使用できるのはプリミティブ型、String、KClass、列挙型、配列に限られる
@Target — 適用できる場所
@Retention — 利用できる時期（リフレクションにはRUNTIMEを使用する）
@Repeatable — 1つの宣言に複数回適用できるようにする
use-siteターゲット（@field:、@get:など）で、どのバイトコード要素にアノテーションを付けるかを制御する

よくある質問

「カスタムアノテーションの作成と対象指定」レッスンは無料ですか？

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

「カスタムアノテーションの作成と対象指定」で何を学びますか？

保持ポリシーを持つアノテーションを定義し、クラス、関数、プロパティに適用します。ブラウザで直接実行するハンズオンコードでKotlin Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

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

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

「カスタムアノテーションの作成と対象指定」レッスンにはどのくらい時間がかかりますか？

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

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

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

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

Kotlin Reflection：KClass、KFunction、KProperty
カスタムアノテーションの作成と対象指定
実行時にアノテーションを読み取る
リフレクションベースのバリデーションとマッピング

← Kotlin Academyに戻る