Spring Bootの@Valueアノテーションの使い方を完全解説！初心者でも理解できるSpELとプロパティの落とし穴

1. @Valueアノテーションとは

1. @Valueアノテーションとは

@Valueアノテーションは、Spring FrameworkやSpring Bootでプロパティファイルに記述された設定値をクラスに注入（インジェクション）するための仕組みです。主にapplication.propertiesやapplication.ymlに定義された値を読み込んで使うことができます。

Spring Bootの設定やプロファイルを活用するうえで、@Valueの使い方は非常に重要です。例えば、APIキーやファイルパス、フラグなどを外部設定として読み込むことで、環境ごとの切り替えが容易になります。

2. 基本的な使い方（プレースホルダ）

2. 基本的な使い方（プレースホルダ）

もっとも基本的な使い方は、プレースホルダ形式でapplication.propertiesに書かれたキーを@Valueで読み込む形です。

app.name=SpringBootSample
app.version=1.0.0

@Component
public class AppInfo {

    @Value("${app.name}")
    private String appName;

    @Value("${app.version}")
    private String appVersion;

    public void printInfo() {
        System.out.println("アプリ名：" + appName);
        System.out.println("バージョン：" + appVersion);
    }
}

アプリ名：SpringBootSample
バージョン：1.0.0

このように、${キー名}の形式でプロパティを読み込むことができます。

3. SpEL（Spring Expression Language）の使い方

3. SpEL（Spring Expression Language）の使い方

@Valueでは、単なるプレースホルダだけでなく、SpEL（スぺル：Spring Expression Language）も利用できます。SpELを使えば、式による値の加工や計算が可能です。

@Component
public class UserInfo {

    @Value("#{20 + 5}")
    private int age;

    @Value("#{systemProperties['user.name']}")
    private String userName;

    public void show() {
        System.out.println("年齢：" + age);
        System.out.println("ユーザー名：" + userName);
    }
}

年齢：25
ユーザー名：your_os_user_name

SpELでは、数値計算やシステムプロパティの参照、さらにはBeanのプロパティ値の参照なども可能になります。

4. デフォルト値の指定方法

4. デフォルト値の指定方法

@Valueでプロパティが見つからなかった場合に、アプリケーションが起動時にエラーになるのを防ぐには、デフォルト値を指定することが重要です。

@Value("${app.description:説明が未設定です}")
private String appDescription;

この例では、app.descriptionというプロパティが存在しない場合に、「説明が未設定です」という文字列が使われます。

5. 配列やリストの読み込み

5. 配列やリストの読み込み

カンマ区切りの値をリストとして読み込むことも可能です。これは、簡単な構成リストなどを扱いたいときに便利です。

app.languages=Java,Python,JavaScript

@Value("#{'${app.languages}'.split(',')}")
private List<String> languages;

注意点として、split(',')という形で明示的に分割する必要があります。

6. よくある落とし穴

6. よくある落とし穴

Spring Boot初心者が@Valueを使う際に陥りやすい問題点を紹介します。

・プロパティが存在しない場合のエラー

デフォルト値を指定していない場合、プロパティが存在しないとアプリ起動時にIllegalArgumentExceptionが発生します。必ず:でデフォルトを用意しましょう。

・SpELとプレースホルダの混同

${...}はプレースホルダ、#{...}はSpELです。この２つは意味も処理のされ方も異なるので、混同しないようにしましょう。

・@Valueの型変換エラー

プロパティ値が指定の型に変換できない場合、例外が発生します。たとえば@Value("${app.port}")に対して、プロパティがabcdのような文字列だとint型に変換できません。

・Beanとして管理されていないと読み込まれない

@ValueはSpringのDI機能を使うため、対象クラスが@Componentや@ServiceなどでBean登録されている必要があります。

7. Spring Bootでのプロファイル活用と@Value

7. Spring Bootでのプロファイル活用と@Value

Spring Bootでは、プロファイル（dev、prodなど）を切り替えることで、異なる設定ファイルを使い分けることができます。プロファイルに応じた@Valueの切り替えも自動的に行われます。

# application-dev.properties
api.endpoint=https://dev-api.example.com

# application-prod.properties
api.endpoint=https://api.example.com

@Value("${api.endpoint}")
private String endpoint;

プロファイルは、application.propertiesや起動オプションで指定可能です。

spring.profiles.active=dev

8. @ConfigurationPropertiesとの使い分け

8. @ConfigurationPropertiesとの使い分け

@Valueは単一の値を読み込むには便利ですが、多数の設定をまとめて扱いたい場合は、@ConfigurationPropertiesの方が適しています。

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private String version;

    // getter / setter
}

設定値が増えてくると、可読性や保守性の観点から@ConfigurationPropertiesの利用が推奨されます。