Spring Boot 配置元數據指南

1. 概覽

在編寫 Spring Boot 應用程序時，將配置屬性映射到 Java bean 上是很是有用的。可是，記錄這些屬性的最好方法是什麼呢？

在本教程中，咱們將探討 Spring Boot Configuration Processor 和 關聯的 JSON 元數據文件，該 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.7.RELEASE</version>
    <optional>true</optional>
</dependency>複製代碼

這種依賴關係將爲咱們提供在構建項目時調用的 Java 註解處理器。咱們稍後會詳細討論這個問題。

爲了防止 @ConfigurationProperties 不該用於咱們的項目使用的其餘模塊，在 Maven 中添加依賴項爲可選依賴 是最好的作法。

4. 配置屬性示例

如今來研究處理器是怎麼工做的，咱們須要使用 Java bean 獲取在 Spring Boot 應用程序中包含一些屬性：

@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 的屬性而且生成他的 getter 和 setter 方法。

在咱們的測試中，讓咱們快速檢查一下，確保咱們也能夠成功地設置和讀取嵌套屬性：

@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-INF 下看到文件名爲 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",
      "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": []
}複製代碼

接下來，讓咱們看看更改 Java bean 上的註解如何影響元數據。

5.1. 關於配置元數據的其餘信息

首先，讓咱們將 JavaDoc 註釋添加到Server 上.

第二，讓咱們給出一個 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 組，它是經過內部類把 IP 和 port 屬性做爲一個組。

屬性是能夠爲其指定值的配置項。這些屬性配置在後綴爲 .properties或 .yml* 文件中，而且能夠有額外的信息，好比默認值和驗證，就像咱們在上面的示例中看到的那樣。

提示是幫助用戶設置屬性值的附加信息。例如，若是咱們有一組屬性的容許值，咱們能夠提供每一個屬性的描述。IDE 將爲這些提示提供自動選擇的幫助。

配置元數據上的每一個組成都有本身的屬性。來解釋配置屬性的詳細用法。

6. 總結

在本文中，咱們介紹了 Spring Boot 配置處理器及其建立配置元數據的功能。使用元數據可使與配置參數的交互變得更加容易。

咱們給出了一個生成的配置元數據的示例，並詳細解釋了它的格式和組成。

咱們還看到了 IDE 上的自動完成支持是多麼有幫助。

與往常同樣，本文中提到的全部代碼片斷均可以在咱們的 GitHub 存儲庫。

原文：https://www.baeldung.com/spring-boot-configuration-metadata

做者：Dionis Prifti

譯者：遺失的拂曉

------

9月福利，關注公衆號​後臺回覆：004，領取8月翻譯集錦!​往期福利回覆：001，002, 003便可領取！