Springの@Valueとは？application.properties/YAMLから値を読み込む方法【保存版】
新人
「Spring Bootのサンプルコードを見ていると、@Valueって書いてある箇所があるんですが、正直何をしているのか分かりません……」
先輩
「最初は分かりにくいよね。@Valueは、設定ファイルに書いた値をプログラムで使うための仕組みなんだ。」
新人
「設定ファイルって、application.propertiesとかapplication.ymlのことですか？」
先輩
「そうそう。Spring Bootでは、その設定ファイルと@Valueを組み合わせることで、コードを柔軟に書けるようになるんだよ。」
1. Springの@Valueとは何か（基本的な役割）
Springの@Valueとは、設定ファイルに書かれた値をクラスのフィールドに読み込むためのアノテーションです。 Spring Bootでは、application.propertiesやapplication.ymlといった設定ファイルに、アプリケーション全体で使う値をまとめて管理します。 @Valueは、その設定値をJavaのコード側で使えるようにする橋渡しの役割を持っています。
Spring Boot初心者のうちは、 「なぜわざわざ設定ファイルから値を読む必要があるのか」 と疑問に感じるかもしれません。 しかし、@Valueを使うことで、 環境ごとに値を切り替えたり、 後から設定だけを変更したりすることが簡単になります。
@Valueは、主に@Controllerや@Serviceなど、 Springが管理しているクラスの中で使われます。 フィールドやコンストラクタ引数に指定することで、 Springが起動時に設定ファイルの値を自動的に注入してくれます。
@Controller
public class SampleController {
@Value("${app.title}")
private String title;
}
この例では、設定ファイルに書かれた「app.title」という値が、 titleというフィールドに自動で代入されます。 開発者は値の取得処理を書く必要がなく、 そのまま変数として利用できます。
2. application.propertiesやYAMLとは何か
application.propertiesやapplication.ymlは、 Spring Bootで使われる設定ファイルです。 データベースの接続情報やアプリケーション名など、 プログラム全体に関わる設定をまとめて記述します。
application.propertiesは、 「キー＝値」というシンプルな形式で書く設定ファイルです。 初心者でも直感的に理解しやすく、 多くの入門記事で使われています。
app.title=サンプルアプリケーション
一方、application.yml（YAML形式）は、 階層構造を持った書き方ができる設定ファイルです。 設定項目が増えてきた場合でも、 まとまりを持って管理しやすい特徴があります。
app:
title: サンプルアプリケーション
どちらを使っても@Valueの使い方は基本的に同じです。 Spring Boot初心者の段階では、 「設定ファイルに書いた値を@Valueで読み込める」 という点を押さえておけば十分です。
3. なぜ設定値をコードに直接書かないのか
初心者が最初にやりがちなのが、 文字列や数値をコードの中に直接書いてしまうことです。 小さなプログラムであれば問題ありませんが、 Spring Bootを使ったアプリケーションではおすすめされません。
もし設定値をコードに直接書いてしまうと、 環境ごとに値を変えたい場合に、 毎回ソースコードを修正する必要が出てきます。 これは、ミスの原因になりやすく、 保守性も下がってしまいます。
application.propertiesやYAMLに設定を切り出し、 @Valueで読み込む形にしておくと、 設定の変更はファイルを書き換えるだけで済みます。 コードに手を加えずに調整できる点は、 実務でも大きなメリットになります。
Spring Boot初心者のうちは、 「@Valueは設定とコードを分離するための仕組み」 と理解しておくと分かりやすいでしょう。 この考え方は、 Spring全体を学んでいくうえでの重要な土台になります。
4. application.propertiesから値を読み込む基本的な使い方
ここでは、Spring Boot初心者が最初に触れることが多い application.propertiesから値を読み込む基本的な使い方を見ていきます。 全体の流れとしてはとてもシンプルで、 「設定ファイルに値を書く → @Valueで指定する → クラスで使う」 という順番になります。
まず、application.propertiesに設定値を記述します。 このファイルは、pleiadesで作成したGradleプロジェクトの場合、 src/main/resources 配下に最初から用意されています。 アプリケーション名や画面表示用の文言など、 後から変更する可能性がある値は、ここにまとめて書いておくのが基本です。
app.message=ようこそSpring Bootへ
次に、この設定値をJavaのコード側で受け取ります。 @Controllerが付いたクラスのフィールドに、 @Valueを使ってキー名を指定します。 このとき、${}で囲んだ中身が、 application.propertiesのキーと対応します。
@Controller
public class MessageController {
@Value("${app.message}")
private String message;
}
Spring Bootが起動するとき、 application.propertiesに書かれた値が読み込まれ、 messageフィールドに自動的に代入されます。 開発者は「どこから値を取ってくるか」を意識するだけで、 ファイル読み込み処理などを書く必要はありません。
このように、設定値が 「設定ファイル → @Value → フィールド」 という流れで渡ってくるイメージを持つことが、 Spring Boot設定を理解する第一歩になります。
5. YAML形式での設定ファイルの書き方と@Valueの指定方法
application.ymlは、application.propertiesと同じ役割を持つ設定ファイルですが、 書き方が少し異なります。 YAML形式では、階層構造を使って設定を整理できるため、 設定項目が増えてきた場合に読みやすくなるという特徴があります。
たとえば、同じ内容をYAML形式で書くと、 次のような形になります。 インデントによって親子関係を表している点がポイントです。
app:
message: ようこそSpring Bootへ
YAML形式で書いた場合でも、 @Valueで指定するキーの考え方は変わりません。 階層をドットでつなげた形で指定します。 この例では「app.message」というキーになります。
@Controller
public class YamlSampleController {
@Value("${app.message}")
private String message;
}
application.propertiesとapplication.ymlの大きな違いは、 「見た目と整理のしやすさ」です。 どちらを使ってもSpring Bootの動きは同じなので、 初心者のうちは、 「設定ファイルの形式が違っても@Valueの指定方法は同じ」 と覚えておけば問題ありません。
実務では、プロジェクトの方針や設定量に応じて、 どちらか一方が選ばれることが多くなります。 まずは両方の書き方を見て、 読めるようになることを目標にしましょう。
6. @Valueでよく使われる書き方と基本パターン
@Valueには、初心者がよく使ういくつかの基本パターンがあります。 ここでは、実務でもよく見かける代表的な使い方を、 シンプルな形で紹介します。
まず最も基本なのが、 文字列や数値をそのまま読み込むパターンです。 設定ファイルに書いた値は、 フィールドの型に合わせて自動的に変換されます。
@Controller
public class BasicValueController {
@Value("${app.port}")
private int port;
}
この場合、application.propertiesやYAMLに書かれた数値が、 int型としてそのまま扱われます。 型変換を自分で意識しなくてよい点も、 Spring Boot初心者にとって扱いやすいポイントです。
次に、設定値が存在しない場合に備えて、 デフォルト値を指定する書き方があります。 設定漏れによるエラーを防ぐために、 よく使われるパターンです。
@Controller
public class DefaultValueController {
@Value("${app.name:デフォルトアプリ}")
private String appName;
}
このようにコロンを使って値を書くと、 設定ファイルにキーが存在しない場合でも、 指定した文字列が使われます。 初心者のうちは、 「設定がまだ決まっていない値」に対して デフォルトを用意しておくと安心です。
@Valueはとても便利ですが、 多くの値を扱う場合は管理が大変になることもあります。 まずは、 「少数の設定値をシンプルに扱う」 という場面で使いながら、 Spring Bootの設定の流れに慣れていくのがおすすめです。
7. @Valueを使うメリットと使わない場合の違い
Spring Boot初心者の段階では、 「@Valueを使わなくても動くのでは？」 と感じることは少なくありません。 実際、小さなサンプルアプリであれば、 コードの中に直接文字列や数値を書いても問題なく動きます。
しかし、@Valueを使う最大のメリットは、 設定と処理を分離できる点にあります。 設定値をapplication.propertiesやYAMLにまとめておくことで、 「どこを見れば設定が分かるのか」 が明確になります。 これは、Spring Boot初心者にとっても、 後からコードを読み返すときに大きな助けになります。
一方、@Valueを使わずに設定値をコードに直接書いてしまうと、 設定変更のたびにソースコードを修正する必要があります。 その結果、 「修正漏れ」 「環境ごとの差分が分からない」 といった問題が起こりやすくなります。
@Valueを使って設定を外に出しておけば、 本番環境、検証環境、開発環境で 同じコードを使い回すことができます。 実務では、 「コードは変えずに設定だけを切り替える」 という考え方がとても重要になるため、 @Valueはその第一歩と言えます。
@Controller
public class CompareController {
@Value("${app.title}")
private String title;
}
このように、設定ファイル側を変更するだけで、 コントローラの動きを柔軟に調整できる点が、 @Valueを使う大きな違いです。 Spring Boot初心者のうちは、 「@Valueは後から効いてくる仕組み」 と捉えておくと理解しやすいでしょう。
8. よくあるミスと値が読み込めない原因
@Valueを使い始めた初心者が 最も戸惑いやすいのが、 「値がnullになる」 「設定を変えたのに反映されない」 というケースです。 エラーが出ないことも多いため、 原因が分からず不安になりがちです。
よくある原因の一つが、 設定ファイルのキー名の間違いです。 application.propertiesやYAMLに書いたキーと、 @Valueで指定したキーが少しでも違うと、 正しく値は読み込まれません。 スペルミスやドットの付け忘れは、 初心者あるあるの代表例です。
次に多いのが、 @Valueを使っているクラスが Springの管理対象になっていないケースです。 @Controllerや@Componentが付いていないクラスでは、 @Valueは動きません。 「値が入らない」と感じたら、 まずクラスにアノテーションが付いているかを確認しましょう。
@Controller
public class MissSampleController {
@Value("${app.mesage}")
private String message;
}
この例では、 設定ファイル側が「app.message」なのに対し、 @Valueでは「app.mesage」と書いています。 このような小さな違いでも、 値は正しく読み込まれません。
また、設定ファイルを変更したのに反映されない場合は、 アプリケーションを再起動していないケースも多く見られます。 Spring Bootは起動時に設定ファイルを読み込むため、 再起動しない限り値は更新されません。
Spring Boot初心者のうちは、 「値が入らない＝@Valueの指定と設定ファイルを疑う」 というチェック順を身に付けておくと、 トラブル対応がかなり楽になります。
9. 実務での利用イメージと学習時の考え方
実務でSpring Bootを使った開発を行う場合、 @Valueはほぼ確実に登場するアノテーションの一つです。 画面に表示する文言や、 外部サービスの接続先、 動作を切り替えるフラグなど、 「後から変わる可能性がある値」 は設定ファイルにまとめられます。
その設定値をコード側で使うための入り口が@Valueです。 実務では、 「設定を外に出しておくことで、 修正範囲を最小限に抑える」 という考え方がとても重視されます。 @Valueは、その感覚を身に付けるための 分かりやすい仕組みと言えます。
学習段階では、 @Valueを使っている理由を 深く考えすぎる必要はありません。 まずは、 「設定ファイルの値をクラスで使うためのもの」 という理解で十分です。 そのうえで、 実際に設定値を変えて挙動が変わる体験をすると、 自然と必要性が分かってきます。
@Controller
public class PracticeController {
@Value("${app.mode}")
private String mode;
}
このように、 環境や状況によって変わる値を 設定ファイルに切り出しておくことで、 コードの見通しが良くなります。 Spring Boot初心者にとって、 @Valueは 「設定と処理を分けて考える」 という習慣を身に付けるための とても良い入口です。
最初は小さな設定からで構いません。 @Valueを使う場面を少しずつ増やしていくことで、 Spring Bootの設計思想が 自然と理解できるようになっていくでしょう。
