SpringBoot 配置提示功能

时间 2019-11-06

原文原文链接

目的

配置自动提示的辅助功能可让配置写起来更快，准确率大大提升。html

springboot jar 包含提供全部支持的配置属性细节的元数据文件。文件的目的是为了让 IDE 开发者在用户使用 application.properties 或 application.yml 文件时提供上下文帮助和代码补全。java

大多数元数据文件是在编译时经过处理用 @ConfigurationProperties 注释的全部项自动生成的。也能够手动编写部分元数据。web

版本

参考 SpringBoot 2.2.0.RELEASE 文档spring

文件

jar包中的 META-INF/spring-configuration-metadata.json （自动生成）或 META-INF/additional-spring-configuration-metadata.json （手动添加）sql

实战

<!-- 引入相关依赖 -->
<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
}复制代码

中文注释会乱码，以上故意用中文注释的地方，会在下面文件中指定对应的描述，看是否会覆盖。apache

additional-spring-configuration-metadata.jsonjson

{
  "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."
        }
      ]
    }
  ]
}复制代码

maven compile 以后，生成的 additional-spring-configuration-metadata.json 与源码中的同样，生成的 spring-configuration-metadata.json 以下：数组

{
  "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."
        }
      ]
    }
  ]
}复制代码

效果

由此能够看到如下现象：springboot

代码中的默认值会自动生成到提示文件中，如：FileUploadConfig#maxSize
代码中的注释会自动生成到提示文件中，如：FileUploadConfig#maxSize
additional-spring-configuration-metadata.json 文件中存在的提示会覆盖自动生成的对应属性，若自动生成的没有此属性则自动增长。

手动写提示文件

示例

{
    "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

分组，将配置类分组。能够按照文件来分组，即：将同一个配置文件的全部属性放在同一个组session

属性	类型	是否必须	用途
name	String	Y	分组的完整名称
type	String	N	分组数据类型的类名（如：使用@ConfigurationProperties注释的完整类名、使用@Bean注释的方法返回类型）
description	String	N	分组的简短描述。
sourceType	String	N	提供分组来源的类名。
sourceMethod	String	N	提供分组的方法，包含括号和参数类型。

properties

提示主体，必须

属性	类型	是否必须	用途
name	String	Y	属性的完整名称。名称采用小写句点分隔格式，如：`server.address`
type	String	N	属性数据类型的完整签名（如：`java.lang.String`）或完整的泛型类型（如：`java.util.Map`）。此属性提示用户输入值得类型。原生类型在此处使用其包装类型（如：`boolean`使用`java.lang.Boolean`）。
description	String	N	分组的简短描述。
sourceType	String	N	提供分组来源的类名。
defaultValue	Object	N	默认值。当属性为指定时使用。
deprecation	Deprecation	N	指定属性是否已弃用。

deprecation属性以下：

属性	类型	是否必须	用途
level	String	N	弃用级别，能够是 `warning`（默认值）或 `error`。`warning`：属性应该仍然可使用；`error`：属性不保证可使用
reason	String	N	属性弃用的简短缘由。
replacement	String	N	替换此弃用属性的新属性全名。可为空

注意：Spring Boot 1.3 版本以前，是使用 boolean 类型的 deprecated。

如下示例来源于官方文档，展现了如何处理这种场景：

`java

@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);

}

}

`

一旦 getTarget 和 setTarget 方法从公共 API 中删除，元数据中的自动弃用提示也会消失。若是要保留提示，则添加具备 error 弃用级别的手动元数据能够确保用户仍然了解该属性。在提供替代品时，这样作特别有用。

hints

辅助提示，非必须

属性	类型	是否必须	用途
name	String	Y	提示关联的属性的完整名称。名称是小写句点分隔格式（如：`spring.mvc.servlet.path`），若是属性关联map类型（如：`system.contexts`），提示能够关联map的键（`system.contexts.keys`）或者值（`system.contexts.values`）。
values	ValueHint[]	N	有效值集合。（下表详述）
providers	ValueProvider[]	N	提供者集合。（下表详述）

values 属性以下：

属性	类型	是否必须	用途
value	Object	Y	提示引用元素的有效值。若是属性是数组，value和description也能够是数组。
description	String	N	value 对应的简短描述

ValueHint

对于Map类型的支持以下：

@ConfigurationProperties("sample")
public class SampleProperties {

    private Map<String,Integer> contexts;
    // getters and setters
}复制代码

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

提示是对Map内每一对 key-value 的提示。

.keys 和 .values 前缀必须分别关联 Map 的 keys 和 values。

providers 属性以下：

属性	类型	是否必须	用途
name	String	N	用于为提示所引用的元素提供其余内容帮助的 provider 的名称。
parameters	JSON object	N	provider 所支持的任何其余参数（有关详细信息，请查看 provider 的文档）。

ValueProvider

*通常用不到，建议跳过*

下表总结了支持的 providers 列表：

属性	描述
any	容许提供任何附加值。
class-reference	自动完成项目中可用的类。一般由目标参数指定的基类约束。
handle-as	处理属性，就像它是由必须的 target 参数定义的类型定义的同样。
logger-name	自动完成有效的记录器名称和记录器组。一般，当前项目中可用的包和类名能够自动完成，也能够定义组。
spring-bean-reference	自动完成当前项目中可用的bean名称。一般由 target 参数指定的基类约束。
spring-profile-name	自动完成项目中可用的 spring 配置文件名称。

any

符合属性类型的全部值。

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

class-reference

提供如下参数：

参数	类型	默认值	描述
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。支持如下参数：

{"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 依赖。

`xml

org.springframework.boot

spring-boot-configuration-processor

true

`

处理器获取用@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"
    }
]}复制代码

注意：若是在项目中使用 AspectJ，则须要确保注解处理器只运行一次。使用 Maven 时，能够显式地配置 maven-apt-plugin插件，并仅在那里向注解处理器添加依赖项。还可让 AspectJ 插件运行于全部的处理且在 maven-compiler-plugin 的 configuration 中禁用注解处理，以下：

`java

org.apache.maven.plugins

maven-compiler-plugin

none

`

绑定属性

注解处理器自动将内部类视为嵌套属性。

@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
    }
}复制代码

上述示例生成 server.name、server.host.ip 和 server.host.port 属性的元数据信息。能够在字段上使用@NestedconfigurationProperty 注解来指示应将常规（非内部）类视为嵌套类。

注意：这对集合和映射没有影响，由于这些类型是自动标识的，而且为每一个类型生成一个元数据属性。

添加额外的元数据

Spring Boot 的配置文件处理很是灵活，一般状况下，可能存在不绑定到 @ConfigurationProperties bean的属性。您还可能须要调整现有key的某些属性，为了支持这种状况并让您提供自定义的“提示”，注解处理器会自动将 META-INF/additional-spring-configuration-metadata.json 中的提示项合并到主要元数据文件（spring-configuration-metadata.json）中。

若是引用已自动检测到的属性，则将覆盖描述、默认值和弃用信息（若是指定）。若是当前模块中没有标识手动属性中的声明，则将其做为新属性添加。

additional-spring-configuration-metadata.json 文件的格式与 spring-configuration-metadata.json 文件同样。附加属性文件是可选的。若是没有任何其余属性，就不要添加文件。

参考资料

springboot 配置提示官方文档公众号：逸飞兮（专一于 Java 领域知识的深刻学习，从源码到原理，系统有序的学习）