@Valueアノテーションで設定値を使う方法をわかりやすく解説！Spring Boot初心者向け完全ガイド

@Valueアノテーションで設定値を使う方法

新人と先輩の会話形式で理解しよう

新人

「先輩、Spring Bootでアプリの設定値を外部から読み込むにはどうすればいいんですか？」

先輩

「いい質問だね。Spring Bootでは@Valueアノテーションを使えば、application.ymlファイルに書いた設定値を簡単にJavaのコードから読み取れるんだよ。」

新人

「なるほど、でもapplication.ymlってどんなファイルなんですか？プロジェクトのどこにあるんですか？」

先輩

「それじゃあ、まずはapplication.ymlの役割と基本的な書き方から見ていこうか！」

1. application.ymlとは？Spring Bootで使う理由

application.ymlは、Spring Bootアプリケーションの設定を管理するためのファイルです。プロジェクトの起動ポートやアプリケーション名、ログ設定、データベースの接続情報など、さまざまな情報をこのファイルに記述します。

このファイルは、プロジェクトのsrc/main/resourcesディレクトリの中にあります。Spring Bootの初期設定ではapplication.propertiesも使用できますが、可読性が高く階層構造を表現しやすいYAML形式のapplication.ymlの方が推奨されています。

以下に、application.ymlの基本的な書き方を示します：


server:
  port: 8080

spring:
  application:
    name: my-sample-app

この例では、サーバーのポート番号とアプリケーション名を設定しています。階層構造になっていて、spring.application.nameという形でアクセスできます。

application.ymlファイルの設定値は、後でJavaのコードから読み取ることができるため、環境によって値を切り替えたいときにとても便利です。

特に「Spring 設定値」「application.yml 読み取り」といった操作は、企業のシステム開発でもよく使われており、初心者のうちからしっかりと理解しておくことが大切です。

2. @Valueアノテーションとは何か？基本的な使い方

@Valueアノテーションは、Spring Frameworkに用意されている便利なアノテーションの一つで、プロパティファイル（今回の場合はapplication.yml）に定義された値をJavaコードに注入するために使用されます。

具体的には、次のような形で使用します：


@Controller
public class SampleController {

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

    @GetMapping("/app-name")
    public String showAppName(Model model) {
        model.addAttribute("appName", appName);
        return "app-name";
    }
}

@Value("${spring.application.name}")と記述することで、application.ymlに書かれている設定値をappNameというフィールドに代入できます。

このときのポイントは、${...}の形式で設定値のキーを指定することです。この形式を間違えると、値を正しく読み取れなくなってしまうので注意しましょう。

このように@Valueを使えば、アプリケーションの設定を外部化して、コードを柔軟に保つことができます。

もう少し実践的な例として、自分でカスタム設定値をapplication.ymlに追加して、それを@Valueで読み取る方法もあります。これについては次のセクションで詳しく解説します。

また、「@Value アノテーション」「application.yml 読み取り方法」はSpring Boot初心者が必ず覚えておくべきキーワードでもあります。検索する際にも役立つので意識しておきましょう。

3. application.ymlにカスタム設定値を定義する方法

実際の開発では、自分たちで定義した設定値（カスタム設定値）をapplication.ymlに追加することがよくあります。たとえば、アプリケーション名や管理者のメールアドレスなど、プロジェクト独自の情報を設定するケースです。

カスタム設定値を定義するには、次のようにapplication.ymlファイルに新しいキーを作成します。


app:
  info:
    title: サンプルアプリケーション
    admin-email: admin@example.com

このようにapp.info.titleやapp.info.admin-emailといった形式でカスタム設定値を記述することで、Javaコードから柔軟に利用できるようになります。

階層構造をきちんと使うことで、設定値が整理され、後から見返しても理解しやすい形にできます。特にSpring カスタム設定を複数用意する場合は、共通のキーの下にまとめて定義するのがおすすめです。

この段階で注意したいのは、インデントのミスです。YAML形式はスペースの数で階層が決まるため、インデントがずれているとエラーになります。基本的には半角スペース2つ、または4つで揃えるようにしましょう。

4. Javaクラスで@Valueを使って設定値を読み取る実践例

次に、先ほど定義したapplication.ymlのカスタム設定値を、Javaのクラスで@Valueアノテーションを使って読み取る方法を実践してみましょう。

以下のようなコントローラを作成することで、定義した値を画面に表示できます。


@Controller
public class AppInfoController {

    @Value("${app.info.title}")
    private String appTitle;

    @Value("${app.info.admin-email}")
    private String adminEmail;

    @GetMapping("/info")
    public String showInfo(Model model) {
        model.addAttribute("title", appTitle);
        model.addAttribute("email", adminEmail);
        return "info";
    }
}

@Value("${app.info.title}")や@Value("${app.info.admin-email}")のように記述することで、先ほどのapplication.ymlから値を取得できます。

読み取った値は、Spring MVCのModelを使ってHTMLテンプレートに渡すことができます。これにより、設定ファイルで値を管理しつつ、動的に画面へ表示できます。

このように、application.yml 読み取りの実践を通して、設定値をコードと分離して管理するメリットが実感できると思います。

初心者がよくつまずくポイントとして、「設定値のキーのスペルミス」や「値の未設定」があります。もし起動時にエラーが出た場合は、まずapplication.ymlに該当するキーが正しく存在しているかを確認しましょう。

5. 設定値を複数の場所で使いまわすときの工夫

アプリケーションが大きくなってくると、同じ設定値を複数のコントローラやサービスで使う場面が出てきます。このような場合、毎回@Valueアノテーションを書くと、コードの重複が増えてしまいます。

そこでおすすめなのが、カスタムのコンポーネントクラスを作って、設定値を一元的に管理する方法です。


@Component
@ConfigurationProperties(prefix = "app.info")
public class AppInfoProperties {

    private String title;
    private String adminEmail;

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getAdminEmail() {
        return adminEmail;
    }

    public void setAdminEmail(String adminEmail) {
        this.adminEmail = adminEmail;
    }
}

このように@ConfigurationPropertiesを使うことで、プロパティの接頭辞（ここではapp.info）に一致する値を自動的にバインドできます。

使用する側では、次のようにインジェクションして使えます：


@Controller
public class AppInfoController {

    private final AppInfoProperties appInfo;

    public AppInfoController(AppInfoProperties appInfo) {
        this.appInfo = appInfo;
    }

    @GetMapping("/info")
    public String showInfo(Model model) {
        model.addAttribute("title", appInfo.getTitle());
        model.addAttribute("email", appInfo.getAdminEmail());
        return "info";
    }
}

この方法のメリットは、複数の場所で共通の設定値を使いまわせる点と、コードの可読性・保守性が大きく向上する点にあります。

特に、Spring カスタム設定を多数扱うようなプロジェクトでは、@Valueだけでなく@ConfigurationPropertiesの活用も検討してみてください。

ただし、@ConfigurationPropertiesを有効にするためには、クラスに@Componentを付けるか、別途@EnableConfigurationPropertiesで明示的に有効化する必要があることを覚えておきましょう。

6. @Valueで設定値が読み込めないときの原因と対策（トラブルシューティング）

Spring Bootを使っていて@Valueで設定値を読み込もうとしたのに、なぜか値がnullになったり、アプリが起動しなくなった経験はありませんか？これは初心者が非常につまずきやすいポイントです。ここでは代表的な原因と対策を丁寧に解説していきます。

まず、最も多いのは設定キーのスペルミスです。たとえばapplication.ymlでは次のように書いたつもりでも：


app:
  info:
    title: テストアプリ

Java側で次のように@Valueを書くと、キーが一致せず読み込めません。


@Value("${app.information.title}") // 誤り："information"と書いてしまっている
private String appTitle;

正しくは${app.info.title}と書かなければいけません。このように、YAMLのキー名と完全に一致しないとSpringは値を注入してくれません。

また、もう一つのよくある失敗例が、YAMLファイルのインデントミスです。YAMLは見た目以上に厳格で、インデントのずれでSpringがファイルを正しく読み取れなくなることがあります。

その他にも、以下のような原因があります：

Spring Bootのプロファイルによってapplication.ymlが読み込まれていない
該当プロパティが環境変数などで上書きされている
@Valueが付いているクラスがSpring管理外である（例：@Componentなどのアノテーションが付いていない）

このような場合は、まずログをよく確認し、次にキーとインデントを丁寧にチェックしましょう。「@Value 読み込めない」と検索することで、多くの先人のトラブルシューティング事例も見つけられるので、困ったら検索してみてください。

7. プロファイル（dev/prod）ごとに設定値を切り替える方法と@Valueとの関係

Spring Bootでは、本番環境（prod）と開発環境（dev）で設定値を切り替えたい場面がよくあります。たとえば、データベースのURLやメールサーバーの設定などは環境によって変える必要があります。

これを実現するために、Spring Bootでは「プロファイル」という仕組みが用意されています。プロファイルとは、環境ごとに異なる設定を持つことができる仕組みで、YAMLファイルを以下のように分けて記述できます。


# application-dev.yml
app:
  info:
    title: 開発用アプリ

# application-prod.yml
app:
  info:
    title: 本番用アプリ

そして、application.ymlの中で使用するプロファイルを指定します。


spring:
  profiles:
    active: dev

このように指定すると、起動時にapplication-dev.ymlが読み込まれます。これにより、設定値が環境ごとに自動で切り替わるようになります。

そしてJavaコードでは、これまでと同様に@Valueで設定値を読み取るだけで、プロファイルに応じた値が注入されるようになります。


@Value("${app.info.title}")
private String appTitle;

この方法は、いわゆる「Spring 設定値切り替え」の基本です。開発と本番でコードを分けることなく、安全に環境ごとの動作を切り替えられるので、とても実用的です。

もし設定がうまく切り替わらない場合は、プロファイル名に間違いがないか、対象のYAMLファイルが存在しているか、アプリケーション起動時にプロファイルが適用されているかを確認してください。

8. よくある活用パターン（APIキーやメッセージ管理など）

@Valueは、ただ設定値を読み込むだけでなく、実際のアプリ開発において様々な場面で活用されています。ここではその代表的な使い方を紹介します。

まず代表的なのが「APIキーの管理」です。外部サービスと連携する場合、APIキーをコードに直接書くのではなく、application.ymlで管理するのが安全でスマートです。


api:
  weather:
    key: ABC123XYZ


@Value("${api.weather.key}")
private String weatherApiKey;

このようにしておけば、APIキーの変更が必要になったときにもコードを修正せずに済みますし、キーの漏洩リスクも減らせます。

もう一つのよくある活用方法は、「定型メッセージの管理」です。バリデーションエラーやユーザーへの通知メッセージなど、一定の文言を設定ファイルで集中管理できます。


message:
  user:
    required: ユーザー名は必須です。
    invalid: 無効なユーザー名です。


@Value("${message.user.required}")
private String userRequiredMessage;

こうしたメッセージを@Valueで読み込んで表示することで、画面ごとに文言の一貫性を保つことができます。また、多言語対応が必要になったときにも拡張しやすくなります。

最後にもう一つ重要な使い方として、「スイッチ用のフラグ」があります。たとえば機能のON/OFFを切り替えたいときに、設定ファイルで制御できます。


feature:
  maintenance-mode: true


@Value("${feature.maintenance-mode}")
private boolean isMaintenanceMode;

このように、設定ファイルで機能を制御することで、デプロイせずに動作を柔軟に切り替えることができます。

@Valueは地味に見えて、実はさまざまな現場で活躍する重要なアノテーションです。今回紹介したような「APIキーの設定」「定型メッセージの集中管理」「環境フラグの制御」といった場面で、積極的に使っていきましょう。