カスタム設定値を作ってJavaから読み取る方法をやさしく解説！初心者向けSpring Bootの設定入門

カスタム設定値を作ってJavaから読み取る方法

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

新人

「先輩、application.ymlに自分で設定を追加して、それをJavaのコードから読み取る方法ってありますか？」

先輩

「もちろんあるよ。application.ymlはSpring Bootのプロパティ設定ファイルだから、そこにカスタム設定を書いてJavaから取り出せるんだ。」

新人

「どこにあるんですか？それに、どうやって書くんですか？」

先輩

「よし、それじゃあapplication.ymlの基本から順に解説していこうか！」

1. application.ymlファイルとは？どこにあるのか

application.ymlファイルは、Spring Bootの設定ファイルのひとつです。アプリケーションの起動ポートやデータベース設定、ログレベルの変更、そして今回のようなカスタム設定値まで、すべてここで定義できます。

このファイルはプロジェクトのsrc/main/resourcesディレクトリの中に配置されています。PleiadesでGradleプロジェクトを作成すると、自動的にこの場所にファイルが生成されます。

以下は基本的な構造の例です：


server:
  port: 8080

spring:
  application:
    name: sample-app

このように、キーと値を階層構造で記述するのが特徴です。設定内容は自動的にSpring Bootが読み込んで、アプリケーションに反映してくれます。

また、拡張子が.propertiesではなく.ymlなのはYAML形式だからです。YAMLは可読性が高く、設定を階層的に表現できるため、近年ではapplication.yml形式が主流になっています。

2. Spring Bootでプロパティ（設定値）を管理する仕組みとは

Spring Bootでは、プロパティファイルに定義した値をJavaのコードから簡単に読み取れる仕組みが用意されています。これにより、アプリケーション全体の設定を一元管理できるようになります。

たとえば、APIキーやメールサーバーのホスト名、外部サービスのURLなど、ハードコーディングせずに設定ファイルに記述しておけば、環境ごとの切り替えが簡単になります。

Spring Bootが設定値を管理する基本的な方法には、次のようなものがあります：

@Value アノテーションを使って値を1つずつ読み込む方法
@ConfigurationPropertiesを使って複数の設定をまとめて読み込む方法

この記事の次のセクションでは、まずapplication.ymlにカスタム設定値を定義して、それをJavaコードから@Valueで読み取る方法を説明します。

ちなみに、Springでは「プロパティの注入」と呼ばれる仕組みによって、自動的にapplication.ymlの設定値がJavaクラスのフィールドにセットされます。これが「DI（依存性注入）」の一環です。

この仕組みを理解しておくと、Spring カスタム設定の活用や、application.yml 読み取りのポイントがぐっとわかりやすくなります。

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

Spring Bootでは、application.ymlに自由に自分だけの設定値を追加することができます。これを「カスタム設定値」と呼びます。用途に応じて任意のキーを定義できるため、非常に柔軟です。

まずは例を見てみましょう。たとえば、会社名とサポートメールアドレスを設定したい場合は、以下のように記述します。


myapp:
  company-name: サンプル株式会社
  support-email: support@example.com

このように階層構造でカスタムキーを定義することで、後からJavaのコードで簡単に読み取ることが可能になります。

注意点としては、スペースの数が非常に重要だということです。インデントを間違えると、設定が無効になったり、Spring Bootが起動しなくなる場合もあります。必ず半角スペース2つか4つで統一してください。

このように、カスタム設定値は用途に応じて柔軟に設計でき、アプリケーション全体の設定を見やすく管理するためにも役立ちます。

4. @Valueアノテーションでカスタム設定値をJavaクラスから読み込む方法

定義したカスタム設定値は、Javaのコードから@Valueアノテーションを使って読み取ることができます。これはもっとも基本的でシンプルな読み取り方法です。

以下は、先ほど定義したcompany-nameとsupport-emailを読み取る例です。


import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Controller;

@Controller
public class InfoController {

    @Value("${myapp.company-name}")
    private String companyName;

    @Value("${myapp.support-email}")
    private String supportEmail;

    public void printInfo() {
        System.out.println("会社名：" + companyName);
        System.out.println("問い合わせ先：" + supportEmail);
    }
}

@Valueの中には、${}で囲んで設定ファイルで定義したキーをそのまま記述します。ここでは、myapp.company-nameとmyapp.support-emailを読み込んでいます。

これにより、application.yml 読み取り方法としてもっとも簡単に動作させることができます。テスト時や少数の値を使いたいときにはとても便利です。

ただし、たくさんの設定値を扱いたい場合は、次回紹介する@ConfigurationPropertiesの使用がおすすめです。

また、@Valueで値が読み込まれないときは、スペルミスやプロファイル設定の影響などが原因であることが多いです。トラブルシューティングについては後半で詳しく紹介します。

5. よく使われるカスタム設定の用途

カスタム設定値は、実際のアプリ開発の中でさまざまな場面で使われます。特に以下のようなケースでは、application.ymlで設定しておくことで、再利用や環境ごとの切り替えがスムーズに行えます。

APIキーや認証トークン：外部サービスとの連携に必要な情報を管理
エラーメッセージや通知文言：ユーザーに表示するテキストを一元管理
サポート先のメールアドレスやURL：運営者の連絡先や問い合わせページなど
定数として使う値：最大件数や初期値などの固定値

例えば、エラーメッセージを設定ファイルで管理しておくと、将来の改修時にもコードを触らずに対応できるため、運用効率が大幅に向上します。

下記は、ユーザー登録時のメッセージを設定した例です。


messages:
  register-success: 登録が完了しました。
  register-fail: 登録に失敗しました。再度お試しください。

これをJavaコードで利用するには、以下のように@Valueで読み取ります。


@Value("${messages.register-success}")
private String registerSuccessMessage;

@Value("${messages.register-fail}")
private String registerFailMessage;

こうしておけば、メッセージの修正や翻訳なども柔軟に対応できます。とくに多言語対応をする場合にも、この手法は非常に役立ちます。

Spring @Value 設定値の活用は、開発者にとって非常に強力なテクニックです。まずは1つの値から試し、徐々に活用範囲を広げていくと良いでしょう。

6. 複数の設定値をまとめて管理するには（@ConfigurationPropertiesの活用）

複数のカスタム設定値を使いたい場合、ひとつずつ@Valueで読み込むのは面倒になります。そんなときは@ConfigurationPropertiesを使うと、設定値をグループ化してまとめて扱うことができます。

たとえば以下のように、application.ymlにまとまったカスタム設定を定義します。


myapp:
  company-name: サンプル株式会社
  support-email: support@example.com
  contact-phone: 03-1234-5678

この設定を読み込むJavaクラスを作成しましょう。以下のように@Componentと@ConfigurationPropertiesを付けて宣言します。


import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "myapp")
public class MyAppProperties {

    private String companyName;
    private String supportEmail;
    private String contactPhone;

    // ゲッターとセッター
    public String getCompanyName() {
        return companyName;
    }
    public void setCompanyName(String companyName) {
        this.companyName = companyName;
    }
    public String getSupportEmail() {
        return supportEmail;
    }
    public void setSupportEmail(String supportEmail) {
        this.supportEmail = supportEmail;
    }
    public String getContactPhone() {
        return contactPhone;
    }
    public void setContactPhone(String contactPhone) {
        this.contactPhone = contactPhone;
    }
}

このクラスを別の@Controllerクラスから使うには、フィールドインジェクションやコンストラクタインジェクションで注入します。


import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;

@Controller
public class InfoController {

    private final MyAppProperties myAppProperties;

    @Autowired
    public InfoController(MyAppProperties myAppProperties) {
        this.myAppProperties = myAppProperties;
    }

    public void printAll() {
        System.out.println("会社名：" + myAppProperties.getCompanyName());
        System.out.println("メール：" + myAppProperties.getSupportEmail());
        System.out.println("電話番号：" + myAppProperties.getContactPhone());
    }
}

このように@ConfigurationPropertiesを使えば、Spring カスタムプロパティ切り替えにも柔軟に対応できます。まとめて管理することで保守性も高まり、構造もすっきりします。

7. プロファイル（開発用・本番用）ごとに設定を切り替える方法

開発環境と本番環境では、接続先のURLや表示する文言などが異なることがよくあります。Spring Bootでは、プロファイルという仕組みを使って環境ごとに設定値を切り替えることができます。

まず、application.ymlの中で、spring.profiles.activeを指定して現在のプロファイルを設定します。


spring:
  profiles:
    active: dev

次に、プロファイルごとの設定ファイルを作成します。たとえば開発用にはapplication-dev.yml、本番用にはapplication-prod.ymlを作ります。


# application-dev.yml
myapp:
  support-email: dev-support@example.com


# application-prod.yml
myapp:
  support-email: prod-support@example.com

こうすることで、プロファイルがdevのときは開発用のメールアドレスが、prodのときは本番用のアドレスが自動で読み込まれます。

この切り替えは、アプリケーションの設定を環境に応じて安全に分離するうえで非常に重要です。特にAPIキーやデータベース接続先などは、絶対に本番と開発で同じにしないようにしましょう。

プロファイルを設定ファイル内に書く方法以外にも、実行時引数や環境変数として指定することも可能です。


--spring.profiles.active=prod

この仕組みを活用すれば、Spring カスタムプロパティ切り替えもシンプルかつ確実に行えるようになります。

8. カスタム設定値のトラブルシューティング（読み取れない原因など）

application.ymlに値を定義してもJavaコードで読み取れないことがあります。そんなときは、以下のような点を確認してみましょう。

インデントのミス：YAMLではスペースのずれが命取りです。タブではなく半角スペースを使い、階層を揃えましょう。
キー名の間違い：Java側で指定した@Value("${...}")のキーが正しく一致しているか確認してください。
プロファイルの影響：現在アクティブなプロファイルが、期待している設定ファイルと一致しているかをチェックします。
クラスに@Componentがついていない：@ConfigurationPropertiesを使うクラスには@Componentを付けないと読み込まれません。
依存関係が不足している：@ConfigurationPropertiesを使う場合、spring-boot-configuration-processorを依存に追加すると補完が効きやすくなります。

設定値が読み込めないときには、「設定値読み込めない」という状況が多くの初学者で発生しますが、焦らずひとつずつ確認すれば必ず原因にたどりつけます。

特にプロファイルが切り替わっている場合、意図しない設定が適用されることがあるため、開発時にはapplication.ymlとapplication-dev.ymlなどを分けて使っていることを忘れないようにしましょう。

また、Spring Bootの設定はアプリケーション起動時に読み込まれるため、設定ファイルを修正した後はプロジェクトの再起動を行う必要があります。

それでもうまくいかない場合は、ログ出力を有効にして、アプリ起動時にプロパティがどう扱われているかを確認するのも有効です。

こうしたトラブルに対応できるようになることで、Spring Bootでの開発力がぐっと高まります。

まとめ

Spring Bootのapplication.ymlを活用したカスタム設定値の管理方法は、初心者にとって理解しておくべき非常に重要な基礎技術です。とくにこの記事で解説した「カスタム設定値の定義方法」「@Valueを使ったJavaコードからの読み取り方法」「@ConfigurationPropertiesを使った複数設定の一括管理」「プロファイルごとの設定切り替え」「設定値が読み取れないときのトラブルシューティング」などは、実務で頻繁に遭遇するSpring Bootアプリケーションの設定管理の基本であり、アプリケーション品質にも大きな影響を与える重要ポイントです。 Spring Bootの設定ファイルであるapplication.ymlは、単なる値の置き場ではなく、アプリケーションの挙動を安全かつ効率よく制御するための中心的な役割を果たします。設定値を外部化することで、ハードコーディングを防ぎ、環境ごとの切り替えも柔軟に行うことができ、開発効率も運用効率も格段に向上します。とくに、APIキーや外部サービスのURL、サポートメールアドレス、固定文言の管理などは、application.ymlで管理することで、コードの見通しがよくなり、変更時の影響範囲も最小限に抑えられます。また、カスタム設定値をJavaから読み取る方法としてもっとも手軽なのが@Valueアノテーションであり、単一の値を小規模な用途で扱う場合に非常に便利です。記事内で紹介したように、@Value("${myapp.company-name}")のようにプロパティキーを指定するだけで簡単に読み取れます。逆に、多数の設定値を扱う場合は@ConfigurationPropertiesを使い、構造化されたプロパティをJavaクラスとしてまとめて管理することで、コードの可読性と保守性が大幅に向上します。さらに、開発用と本番用で設定を切り替えるプロファイル機能を理解することも非常に重要で、application-dev.ymlやapplication-prod.ymlを用意することで、環境に応じた設定切り替えが自動で行われ、誤った設定を本番へデプロイしてしまう事故も防げます。設定が読み取れない場合の原因として多いのが「インデントミス」「キー名の誤り」「プロファイルの不一致」「アノテーション不足」などであり、これらを体系的に理解しておくことでトラブルシューティング能力も大幅に向上します。以下に、この記事全体の理解を深めるためのサンプルコードを再掲しておきます。


myapp:
  company-name: サンプル株式会社
  support-email: support@example.com
  contact-phone: 03-1234-5678


@Controller
public class InfoController {

    @Value("${myapp.company-name}")
    private String companyName;

    @Value("${myapp.support-email}")
    private String supportEmail;

    public void printInfo() {
        System.out.println("会社名：" + companyName);
        System.out.println("問い合わせ先：" + supportEmail);
    }
}

Spring Bootのカスタム設定は、覚えれば覚えるほど開発の効率が上がり、アプリケーションの品質と管理性が向上します。特に設定値の外部化は、変更に強い設計を実現するための最初の一歩であり、これをしっかり理解することで、今後のアプリケーション開発において強力な武器となります。カスタム設定を使いこなし、より安全で柔軟なSpring Bootアプリケーション開発を目指していきましょう。

新卒エンジニアと先輩社員の振り返り会話

新人：「きょう学んだSpring Bootのカスタム設定は思っていた以上に奥が深いんですね。application.ymlに値を書くだけでJavaコードから読み取れるのはすごく便利です。」

先輩：「そうだね。特に設定値を環境ごとに切り替えられるプロファイル機能は実務では必須だから、しっかり押さえておくと役に立つよ。」

新人：「@Valueで簡単に読み取れるのも便利でしたけど、@ConfigurationPropertiesでまとめて管理できる方法もすごく実用的だと思いました！」

先輩：「うん。設定項目が増えてきたら必ず@ConfigurationPropertiesを使った方が整理しやすいし保守性も高まるよ。」

新人：「トラブルシューティングの部分も役に立ちました。インデントやキーのミスでエラーになることが多いって知って、これからはもっと慎重に書こうと思います。」

先輩：「それは良い姿勢だね。設定ファイルはアプリ全体に影響するから、丁寧に扱うことがとても大切なんだ。今回学んだ内容は実務で必ず活きるから、ぜひ次の開発でも活用してみてね。」

新人：「はい！今回のまとめで理解が深まりました。次は@ConfigurationPropertiesを実際に使った実装にも挑戦してみます！」