Spring Boot 配置元数据指南

1. 概览

在编写 Spring Boot 应用程序时,将配置属性映射到 Java bean 上是很是有用的。可是,记录这些属性的最好方法是什么呢?html

在本教程中,咱们将探讨 Spring Boot Configuration Processor关联的 JSON 元数据文件,该 JSON 文档记录每一个属性的含义、约束等。java

2. 配置元数据

做为开发人员,咱们开发的大多数应用程序在某种程度上必须是可配置的。可是在一般状况下,咱们并不可以真正的理解配置参数的做用,好比它有默认值,又或者是过期的,有时咱们甚至不知道该属性的存在。git

为了帮助咱们理清楚,Spring Boot 生成了配置元数据的 JSON 文件,为咱们提供关于如何使用属性的有用信息。因此,配置元数据是一个描述性文件,它包含与配置属性交互所需的必要信息。github

这个文件的好处是 IDE 也能读懂它,从而为咱们提供自动完成 Spring 属性配置的工做,以及其余配置提示。spring

3. 依赖

为了生成此配置元数据,咱们将使用 spring-boot-configuration-processor* 的依.数据库

所以,让咱们继续将依赖项添加为可选依赖json

<dependency>    
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <version>2.1.7.RELEASE</version>
    <optional>true</optional>
</dependency>复制代码

这种依赖关系将为咱们提供在构建项目时调用的 Java 注解处理器。咱们稍后会详细讨论这个问题。maven

为了防止 @ConfigurationProperties 不该用于咱们的项目使用的其余模块,在 Maven 中添加依赖项为可选依赖 是最好的作法。spring-boot

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.iddatabase.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.ipdatabase.server.port 属性的不一样之处。事实上,额外的信息是很是有帮助的。开发人员和 IDE 都更容易理解每一个属性的功能。

咱们还应该确保触发构建以得到更新的文件。在Eclipse中,若是咱们检查自动生成选项时,每一个保存操做都将触发生成。在 IntelliJ 中,咱们应该手动触发构建。

5.2. 理解元数据格式

让咱们仔细看看 JSON 元数据文件,并讨论其组成。

Groups 是用于分组其余属性的较高级别的项,而不指定值自己。在咱们的例子中,咱们有数据库组,它也是配置属性的前缀。咱们还有一个 database 组,它是经过内部类把 IPport 属性做为一个组。

属性是能够为其指定值的配置项。这些属性配置在后缀为 .properties或 .yml* 文件中,而且能够有额外的信息,好比默认值和验证,就像咱们在上面的示例中看到的那样。

提示是帮助用户设置属性值的附加信息。例如,若是咱们有一组属性的容许值,咱们能够提供每一个属性的描述。IDE 将为这些提示提供自动选择的帮助。

配置元数据上的每一个组成都有本身的属性。来解释配置属性的详细用法。

6. 总结

在本文中,咱们介绍了 Spring Boot 配置处理器及其建立配置元数据的功能。使用元数据可使与配置参数的交互变得更加容易。

咱们给出了一个生成的配置元数据的示例,并详细解释了它的格式和组成。

咱们还看到了 IDE 上的自动完成支持是多么有帮助。

与往常同样,本文中提到的全部代码片断均可以在咱们的 GitHub 存储库

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

做者:Dionis Prifti

译者:遗失的拂晓

------

9月福利,关注公众号​后台回复:004,领取8月翻译集锦!​往期福利回复:001,002, 003便可领取!

img

相关文章
相关标签/搜索