SpringBoot構成メタデータのガイド

投稿日: 2019-10-18 2022-11-09
タグ: Spring Boot

1. 概要

Spring Bootアプリケーションを作成するときは、構成プロパティをJavaBeanにマップすると便利です。しかし、これらのプロパティを文書化するための最良の方法は何ですか？

このチュートリアルでは、 Spring Boot構成プロセッサーおよび関連するJSONメタデータファイルについて説明します。これらのファイルには、各プロパティの意味や制約などが記載されています。

2. 構成メタデータ

開発者として取り組んでいるアプリケーションのほとんどは、ある程度構成可能である必要があります。ただし、通常、構成パラメーターが何をするのか、デフォルト値があるのか、非推奨であるのか、そして時にはプロパティが存在するのかさえわからないのか、私たちは本当に理解していません。

私たちを助けるために、Spring BootはJSONファイルに構成メタデータを生成します。これにより、プロパティの使用方法に関する有用な情報が得られます。したがって、構成メタデータは、構成プロパティとの対話に必要な情報を含む記述ファイルです。

このファイルの本当に素晴らしい点は、 IDEもを読み取ることができるため、Springプロパティのオートコンプリートやその他の構成のヒントが得られることです。

3. 依存関係

この構成メタデータを生成するために、spring-boot-configuration-processor依存関係の構成プロセッサーを使用します。

それでは、先に進んで、依存関係をオプションとして追加しましょう。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <version>2.1.6.RELEASE</version>
    <optional>true</optional>
</dependency>

この依存関係により、プロジェクトのビルド時に呼び出されるJavaアノテーションプロセッサが提供されます。これについては後で詳しく説明します。

プロジェクトが使用する他のモジュールに@ConfigurationPropertiesが適用されないようにするために、Mavenにオプションとして依存関係を追加することをお勧めします。

4. 構成プロパティの例

プロセッサの動作を確認するために、JavaBeanを介してSpringBootアプリケーションに含める必要のあるプロパティがいくつかあると想像してみてください。

@Configuration
@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {
	
    public static class Server {

        private String ip;
        private int port;

        // standard getters and setters
    }
	
    private String username;
    private String password;
    private Server server;
	
    // standard getters and setters
}

これを行うには、@ConfigurationPropertiesアノテーションを使用します。 構成プロセッサーは、この注釈が付いたクラスとメソッドをスキャンして、構成パラメーターにアクセスし、構成メタデータを生成します。

これらのプロパティのいくつかをプロパティファイルに追加してみましょう。この場合、それをdatabaseproperties-test.propertiesと呼びます。

#Simple Properties
database.username=baeldung
database.password=password

そして、念のために、すべてが揃っていることを確認するためのテストも追加します。

@RunWith(SpringRunner.class)
@SpringBootTest(classes = AnnotationProcessorApplication.class)
@TestPropertySource("classpath:databaseproperties-test.properties")
public class DatabasePropertiesIntegrationTest {

    @Autowired
    private DatabaseProperties databaseProperties;

    @Test
    public void whenSimplePropertyQueriedThenReturnsPropertyValue() 
      throws Exception {
        Assert.assertEquals("Incorrectly bound Username property", 
          "baeldung", databaseProperties.getUsername());
        Assert.assertEquals("Incorrectly bound Password property", 
          "password", databaseProperties.getPassword());
    }
    
}

また、内部クラス Server を介して、ネストされたプロパティdatabase.server.idおよびdatabase.server.portを追加しました。 内部クラスServer と、独自のゲッターとセッターを備えたフィールド serverを追加する必要があります。

私たちのテストでは、ネストされたプロパティも正常に設定および読み取ることができることを確認するために、簡単なチェックを行います。

@Test
public void whenNestedPropertyQueriedThenReturnsPropertyValue() 
  throws Exception {
    Assert.assertEquals("Incorrectly bound Server IP nested property",
      "127.0.0.1", databaseProperties.getServer().getIp());
    Assert.assertEquals("Incorrectly bound Server Port nested property", 
      3306, databaseProperties.getServer().getPort());
}

これで、プロセッサを使用する準備が整いました。

5. 構成メタデータの生成

構成プロセッサがファイルを生成することは前述しましたが、これは注釈処理を使用します。

したがって、プロジェクトをコンパイルすると、 target / classes/META内にspring -configuration-metadata.jsonというファイルが表示されます。 -INF ：

{
  "groups": [
    {
      "name": "database",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 0
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

次に、JavaBeanのアノテーションを変更するとメタデータにどのように影響するかを見てみましょう。

5.1. 構成メタデータに関する追加情報

まず、サーバーにJavaDocコメントを追加しましょう。

次に、 database.server.port フィールドにデフォルト値を指定し、最後に@Minおよび@Maxアノテーションを追加します。

public static class Server {

    /**
     * The IP of the database server
     */
    private String ip;

    /**
     * The Port of the database server.
     * The Default value is 443.
     * The allowed values are in the range 400-4000.
     */
    @Min(400)
    @Max(800)
    private int port = 443;

    // standard getters and setters
}

ここでspring-configuration-metadata.json ファイルを確認すると、次の追加情報が反映されていることがわかります。

{
  "groups": [
    {
      "name": "database",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "description": "The IP of the database server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "description": "The Port of the database server. The Default value is 443.
        The allowed values are in the range 400-4000",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 443
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

database.server.ipフィールドとdatabase.server.portフィールドで違いを確認できます。確かに、追加情報は非常に役立ちます。その結果、開発者とIDEは、各プロパティの機能を理解しやすくなります。

また、ビルドをトリガーして更新されたファイルを取得することも確認する必要があります。 Eclipseでは、自動ビルドオプションをオンにすると、保存アクションごとにビルドがトリガーされます。 IntelliJでは、ビルドを手動でトリガーする必要があります。

5.2. メタデータ形式を理解する

JSONメタデータファイルを詳しく見て、そのコンポーネントについて説明しましょう。

Groups は、値自体を指定せずに、他のプロパティをグループ化するために使用される高レベルのアイテムです。この例では、 database グループがあります。これは、構成プロパティのプレフィックスでもあります。また、内部クラスを介して作成した server groupがあり、ipおよびportプロパティをグループ化します。

プロパティは、値を指定できる構成アイテムです。これらのプロパティは.propertiesまたは.ymlファイルで設定され、上記の例で見たように、デフォルト値や検証などの追加情報を持つことができます。

ヒントは、ユーザーがプロパティ値を設定するのに役立つ追加情報です。たとえば、プロパティに許可された値のセットがある場合、それぞれが何をするかについての説明を提供できます。 IDEは、これらのヒントの自動競合ヘルプを提供します。

構成メタデータの各コンポーネントには、構成プロパティをより詳細に説明するための独自の属性があります。

6. 結論

この記事では、Spring BootConfigurationProcessorとその構成メタデータを作成する機能について説明しました。このメタデータを使用すると、構成パラメーターの操作がはるかに簡単になります。

生成された構成メタデータの例を示し、その形式とコンポーネントについて詳しく説明しました。

また、IDEのオートコンプリートサポートがいかに役立つかを見ました。

いつものように、この記事で言及されているすべてのコードスニペットは、GitHubリポジトリにあります。

getdocs

13036