資料５．Javaのアノテーション

アノテーションとは

アノテーション（Annotation）とは、クラス・メソッド・フィールドなどに付加情報を与えるJavaの仕組みです。「@」記号で始まり、コンパイラやツールに対する指示・情報を表します。アノテーション自体はプログラムの動作に直接影響しませんが、コンパイル時の検証、コードの自動生成、実行時の処理制御などに活用されます。

アノテーションの書き方

@アノテーション名
対象（クラス・メソッド・フィールドなど）

Java標準アノテーション

Javaには、java.langパッケージに標準で用意されているアノテーションがあります。

Java標準アノテーションの一覧
アノテーション	用途	付与できる対象
@Override	親クラス・インターフェースのメソッドをオーバーライドしていることを明示	メソッド
@Deprecated	廃止予定（非推奨）であることを示す	クラス・メソッド・フィールド
@SuppressWarnings	指定した種類のコンパイル警告を抑制する	クラス・メソッド・フィールドなど
@FunctionalInterface	関数型インターフェースであることを明示（Java 8以降）	インターフェース
@SafeVarargs	可変長引数の型安全性を保証することを示す	メソッド・コンストラクタ

@Override

親クラスまたはインターフェースのメソッドをオーバーライドしていることを明示します。省略可能ですが、付けることを強く推奨します。メソッド名や引数を間違えた場合にコンパイルエラーで気づくことができます。

public abstract class Animal {
    abstract void speak();
}

public class Dog extends Animal {
    @Override
    public void speak() {
        System.out.println("ワン！");
    }
}

@Deprecated

そのクラス・メソッド・フィールドが廃止予定（非推奨）であることを示します。@Deprecatedが付いた要素を使用すると、コンパイル時に警告が出力されます。古いAPIを残しつつ、使用を控えるよう促す場合に使います。

public class OldApi {
    /**
     * @deprecated 代わりに newMethod() を使用してください。
     */
    @Deprecated
    public void oldMethod() {
        System.out.println("旧メソッド");
    }

    public void newMethod() {
        System.out.println("新メソッド");
    }
}

@SuppressWarnings

コンパイラが出力する特定の警告を抑制します。引数に抑制する警告の種類を文字列で指定します。警告の原因を理解した上で意図的に使用している場合にのみ使い、むやみに使用することは避けましょう。

import java.util.*;

public class Sample {
    @SuppressWarnings("unchecked")
    public void method() {
        // 型パラメータなしのArrayList（Raw型）を使用
        ArrayList list = new ArrayList();
        list.add("テスト");
    }
}

主な警告の種類は以下のとおりです。

引数	抑制する警告の内容
"all"	すべての警告を抑制する
"unchecked"	型キャストやジェネリクスに関する警告を抑制する
"deprecation"	廃止予定の要素を使用した場合の警告を抑制する
"rawtypes"	Raw型（型パラメータなしのジェネリクス型）の使用警告を抑制する
"unused"	未使用の変数・メソッドに関する警告を抑制する

@FunctionalInterface

抽象メソッドを1つだけ持つ関数型インターフェースであることを明示します（Java 8以降）。ラムダ式で使用できるインターフェースに付与します。誤って2つ以上の抽象メソッドを定義した場合、コンパイルエラーで検出できます。

@FunctionalInterface
public interface Calculator {
    // 抽象メソッドは1つだけ
    int calculate(int a, int b);
}

// ラムダ式で実装
Calculator add = (a, b) -> a + b;
System.out.println(add.calculate(3, 5));  // 8

Javadocアノテーション（タグ）

Javadocコメント（/** */）の中で使用する特殊なタグです。これらはJavadocツールがAPI文書を自動生成する際に使用されます。

主なJavadocタグ
タグ	書き方	説明
@param	@param 引数名説明	メソッドの引数の説明
@return	@return 説明	メソッドの戻り値の説明
@throws	@throws 例外クラス名説明	スローされる例外の説明
@author	@author 著者名	クラスの作成者
@version	@version バージョン番号	クラス・メソッドのバージョン
@since	@since バージョン番号	その要素が追加されたバージョン
@see	@see 参照先	関連するクラス・メソッドへの参照
@deprecated	@deprecated 説明	廃止の理由と代替手段の説明（@Deprecatedとセットで使う）

/**
 * 2つの整数の最大値を返すメソッド。
 *
 * @param a 1つ目の整数
 * @param b 2つ目の整数
 * @return aとbのうち大きい方の値
 * @since 1.0
 * @see Math#max(int, int)
 */
public int max(int a, int b) {
    return (a >= b) ? a : b;
}

カスタムアノテーション（独自アノテーション）

Javaでは@interfaceキーワードを使って独自のアノテーションを定義することもできます。フレームワーク（SpringやJUnit等）では多数のカスタムアノテーションが活用されています。

カスタムアノテーションの定義

public @interface アノテーション名 {
　　// 要素（省略可能）
　　型要素名() default デフォルト値;
}

// アノテーションの定義
public @interface Author {
    String name();
    String date() default "未定義";
}

// アノテーションの使用
@Author(name = "田中太郎", date = "2024-01-01")
public class MyClass {
    // ...
}

カスタムアノテーションはSpring FrameworkのDI（@Autowired、@Component）やJUnitのテスト（@Test、@BeforeEach）など、実際の開発現場で広く活用されています。