Spring Bootのカスタムプロパティの定義方法をやさしく解説！初心者向け独自設定の書き方ガイド

Spring Bootのカスタムプロパティの定義

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

新人

「Spring Bootで、自分で作った設定値をapplication.propertiesに書いて使う方法ってあるんですか？」

先輩

「あるよ。それは“カスタムプロパティ”って呼ばれていて、独自のキーで設定を追加できるんだ。」

新人

「独自ってことは、Spring Bootがもともと用意しているプロパティじゃないってことですよね？」

先輩

「そうそう。たとえばmyapp.titleとかcustom.messageみたいに、自分だけの設定名を定義できるんだ。じゃあ、まずは“カスタムプロパティとは何か”から説明するね。」

1. カスタムプロパティとは何か？

Spring Bootのカスタムプロパティとは、自分で好きな名前の設定項目を定義して、application.propertiesやapplication.ymlに追加する方法のことです。

通常はserver.portやspring.datasource.urlなどの既存プロパティを使いますが、カスタムプロパティでは、たとえば次のように独自の名前を自由につけられます。


myapp.title=わたしのアプリケーション
myapp.version=1.0.0

このようなカスタム設定は、アプリのタイトルやバージョン情報、または業務ロジックに関係する独自のパラメータなど、自由に使い道を決めることができます。

Spring Boot カスタムプロパティは、設定ファイルの可読性と柔軟性を高め、メンテナンス性にも優れています。特に、複数環境（開発・本番）で異なる値を設定するときにも役立ちます。

2. カスタムプロパティを定義する方法

カスタムプロパティは、application.propertiesやapplication.ymlに書いて定義します。それぞれの記述方法を具体的に見ていきましょう。

2-1. application.propertiesでの定義

プロジェクト内のsrc/main/resources/application.propertiesファイルに、次のように記述します。


custom.message=こんにちは、Spring Boot！
custom.author=山田太郎

ここで定義したプロパティは、Javaのコードから読み込んで使用することができます。

2-2. application.ymlでの定義

application.ymlファイルを使う場合は、YAML形式で階層的に記述します。


custom:
  message: こんにちは、Spring Boot！
  author: 山田太郎

application.yml 独自プロパティは、見た目がスッキリしていて、複雑な構造のプロパティも扱いやすくなります。ただし、インデント（字下げ）に注意してください。

このように定義したSpring Boot カスタムプロパティは、@Valueや@ConfigurationPropertiesを使ってコード側で読み込むことができます。この読み込み方法については、次のパートで詳しく説明します。

Spring Bootでは標準プロパティだけでなく、独自の設定を自由に追加できるため、設定の柔軟性が高く、アプリケーションの拡張性にも貢献します。

3. カスタムプロパティをJavaコードで読み込む方法（@Valueの使い方）

Spring Bootでカスタムプロパティを読み込む一番シンプルな方法が、@Valueアノテーションを使う方法です。これは、個別のプロパティ値を直接Javaコード内の変数に読み込むのに適しています。

たとえば、次のようにapplication.propertiesに定義されたカスタムプロパティがあります。


custom.message=こんにちは、Spring Boot！

このプロパティを@Controllerの中で使いたい場合、次のように@Valueを記述します。


package com.example.demo.controller;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class CustomController {

    @Value("${custom.message}")
    private String message;

    @GetMapping("/show-message")
    public String showMessage(Model model) {
        model.addAttribute("message", message);
        return "message-view";
    }
}

@Value("${custom.message}")の形式で、設定ファイルに定義したキーを指定します。Spring Boot カスタムプロパティ読み込みの基本的な方法として、とてもよく使われています。

HTML（Thymeleaf）テンプレートでは、次のようにして読み込んだ値を表示します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>カスタムプロパティの表示</title>
</head>
<body>
    <h1>カスタムプロパティの読み込み結果</h1>
    <p th:text="${message}">ここにメッセージが表示されます</p>
</body>
</html>

@Valueは簡単に使えますが、複数のプロパティをまとめて扱いたい場合や階層構造を扱う場合には少し不便です。そのようなケースでは、次の@ConfigurationPropertiesの方法が便利です。

4. カスタムプロパティを複数まとめて読み込む方法（@ConfigurationProperties）

@ConfigurationPropertiesは、複数のプロパティを1つのJavaクラスにまとめて読み込むためのアノテーションです。設定値が多い場合や階層構造のプロパティを扱うときに特に便利です。

たとえば、次のようにapplication.ymlに設定されている場合を考えます。


myapp:
  title: サンプルアプリ
  version: 1.2.3
  author:
    name: 山田太郎
    email: yamada@example.com

このような階層構造のカスタムプロパティを扱うには、次のようにJavaクラスを作成します。


package com.example.demo.config;

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

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

    private String title;
    private String version;
    private Author author;

    public static class Author {
        private String name;
        private String email;

        // GetterとSetter
        public String getName() { return name; }
        public void setName(String name) { this.name = name; }

        public String getEmail() { return email; }
        public void setEmail(String email) { this.email = email; }
    }

    // GetterとSetter
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public String getVersion() { return version; }
    public void setVersion(String version) { this.version = version; }

    public Author getAuthor() { return author; }
    public void setAuthor(Author author) { this.author = author; }
}

このMyAppPropertiesクラスでは、myapp.titleやmyapp.author.nameなどのカスタムプロパティを自動的に読み込んで、Javaオブジェクトとして扱うことができます。

この設定クラスを@Controllerの中で使うには、次のように@Autowiredで注入します。


package com.example.demo.controller;

import com.example.demo.config.MyAppProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class InfoController {

    private final MyAppProperties myAppProperties;

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

    @GetMapping("/info")
    public String showInfo(Model model) {
        model.addAttribute("title", myAppProperties.getTitle());
        model.addAttribute("version", myAppProperties.getVersion());
        model.addAttribute("authorName", myAppProperties.getAuthor().getName());
        return "info-view";
    }
}

そしてHTML側では、次のようにして各値を表示します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>アプリ情報</title>
</head>
<body>
    <h1 th:text="${title}">アプリタイトル</h1>
    <p>バージョン: <span th:text="${version}"></span></p>
    <p>作成者: <span th:text="${authorName}"></span></p>
</body>
</html>

@ConfigurationPropertiesは、設定項目が増えてきたときや再利用性を高めたいときに最適な方法です。Spring Boot カスタムプロパティ読み込みや@ConfigurationProperties 解説といったキーワードで検索されることも多く、実務でも頻繁に活用されています。

注意点としては、@ConfigurationPropertiesを使うクラスには、必ず@Componentか@Configurationを付ける必要があります。また、すべてのプロパティに対してGetterとSetterを定義する必要があります。

このように、@Valueはシンプルで個別読み取りに便利、@ConfigurationPropertiesは構造的にまとめて管理できるという違いがあります。用途に応じて使い分けましょう。

5. プロファイルごとにカスタムプロパティを切り替える方法

Spring Bootでは、「プロファイル」という仕組みを使って、開発・テスト・本番など、環境ごとに設定を切り替えることができます。これは、Spring Boot カスタムプロパティ切り替えを実現するために非常に重要な機能です。

まず、設定ファイルをプロファイルごとに分けるには、ファイル名に-{プロファイル名}を付けた設定ファイルを作成します。たとえば以下のようなファイル構成になります。

application.properties（共通設定）
application-dev.properties（開発環境用）
application-prod.properties（本番環境用）

たとえば、application-dev.propertiesに以下のように書きます。


custom.message=これは開発環境のメッセージです

そしてapplication-prod.propertiesには次のようにします。


custom.message=これは本番環境のメッセージです

どのプロファイルを使うかは、起動時にspring.profiles.activeで指定します。application.propertiesで指定する例はこちらです。


spring.profiles.active=dev

また、Gradleで実行する場合は、次のようにコマンドラインから指定することも可能です。


./gradlew bootRun --args='--spring.profiles.active=prod'

application.ymlでもプロファイルごとの設定が可能です。次のように---（ハイフン3つ）で区切って、それぞれのプロファイル用の設定を記述します。


spring:
  profiles:
    active: dev
---
spring:
  config:
    activate:
      on-profile: dev
custom:
  message: これは開発環境のメッセージです
---
spring:
  config:
    activate:
      on-profile: prod
custom:
  message: これは本番環境のメッセージです

このように設定しておくと、プロファイルに応じてcustom.messageの内容が切り替わります。

この仕組みを活用すれば、開発者が本番と開発で異なる設定を安全に管理でき、同じソースコードでも環境に応じた挙動を実現できます。

6. カスタムプロパティを使う際の注意点とベストプラクティス

最後に、カスタムプロパティを安全かつ効率よく活用するための注意点とベストプラクティスを紹介します。設定ミスや予期しない挙動を防ぐためにも、以下のポイントは非常に重要です。

6-1. 命名規則を統一する

カスタムプロパティ名には、必ずプロジェクト固有の接頭辞をつけるようにしましょう。たとえばmyapp.やcustom.のようにすると、他のプロパティとの衝突を防げます。

例：


myapp.title=タスク管理システム
myapp.theme.color=blue

6-2. デフォルト値を設定する

@Valueを使う場合、環境によって値が設定されていない可能性があります。そんなときにアプリが落ちないように、:（コロン）でデフォルト値を指定するのがよい習慣です。


@Value("${custom.message:デフォルトメッセージ}")
private String message;

これでcustom.messageが未定義でもエラーにはならず、代わりに「デフォルトメッセージ」が使われます。

6-3. 定義したプロパティを一覧で整理する

設定が多くなると、どこに何を書いたかわからなくなることがあります。そのため、application.propertiesやapplication.ymlの冒頭にコメントで目的や用途をメモしておくとよいです。


# アプリケーション全体の設定
myapp.title=受発注システム
myapp.admin.email=admin@example.com

6-4. 意図しない上書きを避ける

Spring Bootでは、プロパティの優先順位があるため、思わぬところで値が上書きされてしまうことがあります。特に環境変数やコマンドライン引数がapplication.propertiesよりも優先される点に注意しましょう。

1位：コマンドライン引数
2位：OSの環境変数
3位：application-{profile}.properties
4位：application.properties

6-5. application.ymlのインデントに注意

YAML形式では、インデントのミスが多いです。半角スペースで揃える必要があり、タブキーを使ってしまうとエラーになる場合があります。VSCodeやPleiadesのエディタで表示モードを変更し、インデントの確認ができるようにしておくと安心です。

このように、カスタム設定ベストプラクティスを守ることで、保守性が高く、他の開発者にもわかりやすい設定になります。特にチーム開発では、ルールを統一しておくことが成功のカギになります。

この記事を読んだ人からの質問