SpringBoot configuration prompts

purpose

Configuration automatically prompts auxiliary function allows the configuration to write faster, greatly improving accuracy.

springboot jar contains all supported configurations provide details of the property metadata file. Purpose of the document is to allow developers to use the IDE user application.propertiesor application.ymlprovide context-sensitive help and code completion when file.
Most metadata file is compiled by treatment with @ConfigurationPropertiescomments all automatically generated. You can also write part of the metadata manually.

version

Reference SpringBoot 2.2.0.RELEASEDocuments

file

jar package META-INF/spring-configuration-metadata.json(automatically generated) or META-INF/additional-spring-configuration-metadata.json(manually added)

Real

<!-- 引入相关依赖 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-configuration-processor</artifactId>
  <optional>true</optional>
</dependency>

@Configuration
@ConfigurationProperties(prefix = "file.upload")
public class FileUploadConfig {
  /** Maximum number of bytes per file */
  private String maxSize = "1024M";

  /** 不允许的文件后缀 */
  private String rejectSuffix;
  //注意：使用的时候必须要有getter/setter，否则不会自动生成该属性对应的提示
  //此处因为篇幅原因省略 getter/setter
}

@Configuration
@ConfigurationProperties("map.test")
public class MapTestConfig {
  /** 测试Map类型数据的提示 */
  private Map<String, Object> data;
  //注意：使用的时候必须要有getter/setter，否则不会自动生成该属性对应的提示
  //此处因为篇幅原因省略 getter/setter
}

Chinese comments are garbled, more deliberately Chinese where noted, will be specified in the following description of the corresponding file, to see whether it will cover.

additional-spring-configuration-metadata.json

{
  "properties": [
    {
      "name": "file.upload.reject-suffix",
      "type": "java.lang.String",
      "defaultValue": "exe,jar",
      "description": "The file suffix is not allowed.",
      "sourceType": "com.lw.metadata.config.FileUploadConfig"
    },
    {
      "name": "map.test.data",
      "type": "java.util.Map",
      "description": "Tips for testing Map type data.",
      "sourceType": "com.lw.metadata.config.MapTestConfig"
    }
  ],
  "hints": [
    {
      "name": "map.test.data.keys",
      "values": [
        {
          "value": "name",
          "description": "The name of the person."
        },
        {
          "value": "sex",
          "description": "The sex of the person."
        }
      ]
    }
  ]
}

After maven compile, generated additional-spring-configuration-metadata.jsonis the same as in the source code, generated spring-configuration-metadata.jsonas follows:

{
  "groups": [
    {
      "name": "file.upload",
      "type": "com.lw.metadata.config.FileUploadConfig",
      "sourceType": "com.lw.metadata.config.FileUploadConfig"
    },
    {
      "name": "map.test",
      "type": "com.lw.metadata.config.MapTestConfig",
      "sourceType": "com.lw.metadata.config.MapTestConfig"
    }
  ],
  "properties": [
    {
      "name": "file.upload.max-size",
      "type": "java.lang.String",
      "description": "Maximum number of bytes per file",
      "sourceType": "com.lw.metadata.config.FileUploadConfig",
      "defaultValue": "1024M"
    },
    {
      "name": "file.upload.reject-suffix",
      "type": "java.lang.String",
      "description": "The file suffix is not allowed.",
      "sourceType": "com.lw.metadata.config.FileUploadConfig",
      "defaultValue": "exe,jar"
    },
    {
      "name": "map.test.data",
      "type": "java.util.Map<java.lang.String,java.lang.Object>",
      "description": "Tips for testing Map type data.",
      "sourceType": "com.lw.metadata.config.MapTestConfig"
    }
  ],
  "hints": [
    {
      "name": "map.test.data.keys",
      "values": [
        {
          "value": "name",
          "description": "The name of the person."
        },
        {
          "value": "sex",
          "description": "The sex of the person."
        }
      ]
    }
  ]
}

effect

It can be seen following phenomena:

• The default value is automatically generated code to prompt file, such as: FileUploadConfig # maxSize
• Comments in the code will be automatically generated to prompt file, such as: FileUploadConfig # maxSize
• additional-spring-configuration-metadata.json file exists in the corresponding attribute prompt override automatically generated, automatically generated if no such property is automatically increased.

Manually writing prompt file

Examples

{
    "groups": [
        {
            "name": "server",
            "type": "org.springframework.boot.autoconfigure.web.ServerProperties",
            "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
        },
        {
            "name": "spring.jpa.hibernate",
            "type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
            "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
            "sourceMethod": "getHibernate()"
        }
    ],
    "properties": [
        {
            "name": "server.port",
            "type": "java.lang.Integer",
            "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
        },
        {
            "name": "server.address",
            "type": "java.net.InetAddress",
            "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
        },
        {
              "name": "spring.jpa.hibernate.ddl-auto",
              "type": "java.lang.String",
              "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
              "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
        }
    ],
    "hints": [
        {
            "name": "spring.jpa.hibernate.ddl-auto",
            "values": [
                {
                    "value": "none",
                    "description": "Disable DDL handling."
                },
                {
                    "value": "validate",
                    "description": "Validate the schema, make no changes to the database."
                },
                {
                    "value": "update",
                    "description": "Update the schema if necessary."
                },
                {
                    "value": "create",
                    "description": "Create the schema and destroy previous data."
                },
                {
                    "value": "create-drop",
                    "description": "Create and then destroy the schema at the end of the session."
                }
            ]
        }
    ]
}

groups

Packet, the packet class configuration.
Can be grouped according to file, namely: in the same group with all the attributes of a profile

Attributes	Types of	Do you have to	use
name	String	Y	The full name of the grouping
type	String	N	Packet data type class name (eg: @ConfigurationProperties annotated using the full class name, a method using the return type annotation @Bean)
description	String	N	Grouping brief description.
sourceType	String	N	Provide the class name of the source of the packet.
sourceMethod	String	N	Grouping provides a method, comprising brackets and parameter types.

properties

Tip body must

Attributes	Types of	Do you have to	use
name	String	Y	The full name of the property. Name using lowercase periods separated format, such as:server.address
type	String	N	The full signature attribute data types (such as: java.lang.String), or complete generic type (eg: java.util.Map<java.util.String,acme.Myenum>). This property worth prompts the user types. Native type packaging type used here (such as: booleanuse java.lang.Boolean).
description	String	N	Grouping brief description.
sourceType	String	N	Provide the class name of the source of the packet.
defaultValue	Object	N	Defaults. When used as a specified property.
deprecation	Deprecation	N	Specifies whether the property has been abandoned.

deprecation properties are as follows:

Attributes	Types of	Do you have to	use
level	String	N	Abandoned level, it may be warning(the default) or error. warning: Property should still be used; error: attribute does not guarantee that you can use
reason	String	N	Short reason abandoned property.
replacement	String	N	Replace the abandoned property of the new property's full name. May be empty

Note: Before Spring Boot version 1.3, using boolean type deprecated.

The following example comes from official documents, showing how to deal with this scenario:

@ConfigurationProperties("app.acme")
public class AcmeProperties {

    private String name;

    public String getName() { ... }

    public void setName(String name) { ... }

    @DeprecatedConfigurationProperty(replacement = "app.acme.name")
    @Deprecated
    public String getTarget() {
        return getName();
    }

    @Deprecated
    public void setTarget(String target) {
        setName(target);
    }
}

Once getTargetand setTargetmethod to remove from the public API, metadata is automatically discarded prompt will disappear. If you want to keep the tips, you have to add errora manual level metadata abandoned ensure that users can still understand the property. In providing alternatives to do so is particularly useful.

hints

Auxiliary prompt, non-essential

Attributes	Types of	Do you have to	use
name	String	Y	Tip the full name of the property associated with it. Name is in lower case separated by periods format (example: spring.mvc.servlet.path), if the attribute associated with the map type (eg: system.contexts), suggesting that the key may be associated with the map ( system.contexts.keys) or the value ( system.contexts.values).
values	ValueHint[]	N	Set of valid values. (Detailed in the following table)
providers	ValueProvider[]	N	Provider collection. (Detailed in the following table)

values Properties are as follows:

Attributes	Types of	Do you have to	use
value	Object	Y	Tip rms reference element. If the property is an array, value and description can also be an array.
description	String	N	Short description of the corresponding value

### ValueHint

Map for types of support are as follows:

@ConfigurationProperties("sample")
public class SampleProperties {

    private Map<String,Integer> contexts;
    // getters and setters
}

{"hints": [
    {
        "name": "sample.contexts.keys",
        "values": [
            {
                "value": "sample1"
            },
            {
                "value": "sample2"
            }
        ]
    }
]}

Tip Tip is within Map for each of the key-value.

.keysAnd .valuesthe prefix must be associated Map of keys and values respectively.

providers Properties are as follows:

Attributes	Types of	Do you have to	use
name	String	N	The name of the content provider provides other helpful tips for the element referenced.
parameters	JSON object	N	Any other parameters provider supported (for more information, please see the provider's documentation).

ValueProvider

Generally less than recommended skipped

The following table summarizes the list of supported providers:

Attributes	description
any	Allowed to provide any added value.
class-reference	Automatically available in the project category. Typically the base class specified by the target parameter constraints.
handle-as	Processing property, as if it were defined by the type of target parameters must be defined.
logger-name	Automatically recording the effective record name and group. Typically, the current item available package and class names can be done automatically, groups may be defined.
spring-bean-reference	AutoComplete bean name of the currently available in the project. Generally designated by the target parameter base class constraints.
spring-profile-name	Automatically spring profile name available in the project.

any

In line with the value of all property types.

{"hints": [
    {
        "name": "system.state",
        "values": [
            {
                "value": "on"
            },
            {
                "value": "off"
            }
        ],
        "providers": [
            {
                "name": "any"
            }
        ]
    }
]}

class-reference

Provide the following parameters:

parameter	Types of	Defaults	description
target	String（Class)	无	分配给值的类的全限定类名。通常用于筛选非候选类。
concrete	boolean	true	指定是否仅将具体类视为有效候选。

{"hints": [
    {
        "name": "server.servlet.jsp.class-name",
        "providers": [
            {
                "name": "class-reference",
                "parameters": {
                    "target": "javax.servlet.http.HttpServlet"
                }
            }
        ]
    }
]}

handle-as

允许您将属性的类型替换为更高级的类型。

这通常在属性具有 java.lang.String 类型时发生，因为您不希望配置类依赖于不在类路径上的类。

参数	类型	默认值		描述
target	String（Class）	无	Y	为属性考虑的类型的完全限定名。

可用的值如下：

• 任何 java.lang.Enum： 列出属性的可能值。
• java.nio.charset.Charset： 支持自动完成字符集/编码值（如 utf-8）
• java.util.Locale：自动完成区域设置（如：en_US)
• org.springframework.util.MimeType：支持自动完成 content-type 值（如：text/plain）
• org.springframework.core.io.Resource： 支持自动完成spring的资源抽象以引用文件系统或类路径上的文件 （如：classpath:/sample.properties）

注意：如果要提供多个值，用 Collection 或 数组类型

{"hints": [
    {
        "name": "spring.liquibase.change-log",
        "providers": [
            {
                "name": "handle-as",
                "parameters": {
                    "target": "org.springframework.core.io.Resource"
                }
            }
        ]
    }
]}

logger-name

logger-name provider 自动完成有效的记录器名称和记录器组。 通常，当前项目中可用的包和类名可以自动完成。 如果组已启用（默认），并且配置中标识了自定义记录器组，则应提供该组的自动完成。

支持以下参数：

参数	类型	默认值	描述
group	boolean	true	指定是否应考虑已知组。

由于记录器名称可以是任意名称，此 provider 应允许任何值，但可以突出显示项目的类路径中不可用的有效包和类名。

以下是 logging.level 属性。keys 是 logger 名，values 关联标准的 log levels 或 自定义的 level，

{"hints": [
    {
        "name": "logging.level.keys",
        "values": [
            {
                "value": "root",
                "description": "Root logger used to assign the default logging level."
            },
            {
                "value": "sql",
                "description": "SQL logging group including Hibernate SQL logger."
            },
            {
                "value": "web",
                "description": "Web logging group including codecs."
            }
        ],
        "providers": [
            {
                "name": "logger-name"
            }
        ]
    },
    {
        "name": "logging.level.values",
        "values": [
            {
                "value": "trace"
            },
            {
                "value": "debug"
            },
            {
                "value": "info"
            },
            {
                "value": "warn"
            },
            {
                "value": "error"
            },
            {
                "value": "fatal"
            },
            {
                "value": "off"
            }

        ],
        "providers": [
            {
                "name": "any"
            }
        ]
    }
]}

spring-bean-reference

此 provider 自动完成在当前项目的配置中定义的bean。 支持以下参数：

参数	类型	默认值	描述
target	String（Class）	无	应该分配给候选对象的bean类的完全限定名。通常用于筛选非候选bean。

以下示例表示：spring.jmx.server 属性定义了使用 MBeanServer

{"hints": [
    {
        "name": "spring.jmx.server",
        "providers": [
            {
                "name": "spring-bean-reference",
                "parameters": {
                    "target": "javax.management.MBeanServer"
                }
            }
        ]
    }
]}

spring-profile-name

此 provider 自动完成在当前项目的配置中定义的spring配置文件。

以下示例表示：spring.profiles.active属性可启用的配置文件名称。

{"hints": [
    {
        "name": "spring.profiles.active",
        "providers": [
            {
                "name": "spring-profile-name"
            }
        ]
    }
]}

可重复的元数据项

具有相同“property”和“group”名称的对象可以在元数据文件中多次出现。 例如，可以将两个单独的类绑定到同一前缀，每个类都有可能重叠的属性名。 虽然多次出现在元数据中的相同名称不应是常见的，但元数据的使用者应注意确保他们支持该名称。

自动生成提示文件

通过使用 spring-boot-configuration-processor jar，您可以从用 @ConfigurationProperties 注释的类中轻松生成自己的配置元数据文件。 jar包含一个java注释处理器，在编译项目时调用它。 用此处理器，需要引入 spring-boot-configuration-processor 依赖。

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

处理器获取用@configurationproperties注释的类和方法。 配置类中字段值的 javadoc 用于填充 description 属性。

注意：仅仅只应将简单文本与@configurationproperties字段javadoc一起使用，因为在将它们添加到json之前不会对它们进行处理。

如果类有一个“至少一个参数”的构造函数，则为每个构造函数参数创建一个属性。 否则，通过标准getter和setter来发现属性，这些getter和setter对集合类型进行了特殊处理（即使只有getter存在，也会检测到）。

注解处理器还支持使用@data、@getter和@setter 的 lombok 注解。

注解处理器无法自动检测 Enum 和 Collections 的默认值。在集合或枚举属性具有非空默认值的情况下，应提供手动元数据。

@ConfigurationProperties(prefix="acme.messaging")
public class MessagingProperties {

    private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b")) ;

    private ContainerType = ContainerType.SIMPLE;

    // ... getter and setters

    public enum ContainerType {
        SIMPLE,
        DIRECT
    }
}

为了提示上述属性的默认值，应该手动添加如下元数据：

{"properties": [
    {
        "name": "acme.messaging.addresses",
        "defaultValue": ["a", "b"]
    },
    {
        "name": "acme.messaging.container-type",
        "defaultValue": "simple"
    }
]}

Note: If you use AspectJ in a project, you need to ensure the annotation processor to run only once. When using Maven, the explicitly configured maven-apt-pluginplug, and to add a dependency where only annotation processors. You can also make AspectJ plug-in runs on all of the processing and in maven-compiler-pluginthe configurationdisabled annotation process, as follows:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <proc>none</proc>
    </configuration>
</plugin>

Binding Properties

Annotation processor automatically considered the inner nested property class.

@ConfigurationProperties(prefix="server")
public class ServerProperties {
    private String name;
    private Host host;
    // ... getter and setters
    public static class Host {
        private String ip;
        private int port;
        // ... getter and setters
    }
}

Generating the above-described examples server.name, server.host.ipand server.host.portmeta data attribute information. @NestedconfigurationProperty annotations may be used to indicate the field should be on a conventional (non-internal) type considered nested class.

NOTE: This does not affect collection and mapping, as these types are automatically identified, and generates a metadata property for each type.

Add additional metadata

Spring Boot configuration file processing very flexible, under normal circumstances, there may not be bound to the @ConfigurationPropertiesbean properties. You also may need to adjust some of the properties of an existing key, in order to support this and allows you to provide "prompt" custom annotation processor automatically META-INF/additional-spring-configuration-metadata.jsonprompts entries merged into the main metadata file ( the Spring-Configuration- metadata.json ) in .

If a reference has been automatically detected attribute, description will cover, information discarded and default values ​​(if specified). If the current module is not declared to manually identify the properties, it is added as a new property.

additional-spring-configuration-metadata.jsonThe file format and spring-configuration-metadata.jsonfile the same. Additional property file is optional. If there are no other attributes, do not add the file.

Reference material

springboot configuration tips official document
public number: Yifei Come (focus on the Java domain knowledge in-depth study and orderly learning from the source to the principles of the system)