配置元数据-1
SpringBoot jar包含元数据文件，这些文件提供了所有支持的配置属性的详细信息。这些文件旨在让IDE开发人员在用户使用时提供上下文帮助和“代码完成”（application.propertes或application.yml）。
大部分元数据文件是在编译时通过处理用@ConfigurationProperties注释的所有项自动生成的。但是，可以手动为案例编写部分元数据。
一、元数据格式
配置元数据文件位于META-INF/spring-configuration-metadata.json. 它们使用JSON格式，将项目分类为“groups”或“properties”，将附加值提示分类为“hints”，如下例所示：
{"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."
}
]
}
]}
每个“属性”都是用户用给定值指定的配置项。例如，服务器端口以及服务器地址可能在application.properties指定，如下所示：
server.port=9090 server.address=127.0.0.1
“groups”是更高级别的项，它们本身不指定值，而是为属性提供上下文分组。例如服务器端口以及服务器地址属性是服务器组的一部分。
不要求每个“属性”都有一个“组”。有些属性可能本身就存在。
最后，“hints”是用于帮助用户配置给定属性的附加信息。例如，当开发人员配置spring.jpa.hibernate.ddl auto属性，工具可以使用提示为none、validate、update、create和create drop值提供一些自动完成帮助。
Group属性
groups数组中包含的JSON对象可以包含下表所示的属性：
| 名称 | 类型 | 目的 |
| name | String | 组的全名。此属性是必需的。 |
| type | String | 组的数据类型的类名。例如，如果组基于用@ConfigurationProperties注释的类，则该属性将包含该类的完全限定名。如果它基于@Bean方法，那么它将是该方法的返回类型。如果类型未知，则可以省略该属性。 |
| description | String | 可以向用户显示的组的简短描述。如果没有说明，可以省略。建议用简短的段落描述，第一行提供简明的摘要。说明中的最后一行应以句点（.）结尾。 |
| sourceType | String | 提供此组的源的类名。例如，如果该组基于用@ConfigurationProperties注释的@Bean方法，则该属性将包含包含该方法的@Configuration类的完全限定名。如果源类型未知，则可以省略该属性。 |
| sourceMethod | String | 提供此组的方法的全名（包括括号和参数类型）（例如，@ConfigurationProperties注释的@Bean方法的名称）。如果源方法未知，则可以省略。 |
Property 属性
properties数组中包含的JSON对象可以包含下表中描述的属性：
| 名称 | 类型 | 目的 |
| name | String | 属性的全名。名称采用小写句点分隔形式（例如，server.address). 此属性是必需的。 |
| type | String | 属性的数据类型的完整签名（例如，java.lang.String)但也可以是一个完整的泛型类型（例如java.util.Map<java.lang.String,acme.MyEnum>)。可以使用此属性指导用户输入的值类型。为了保持一致性，原语的类型是通过使用其对应的包装器来指定的（例如，boolean变成java.lang.Boolean). 注意，这个类可能是一个复杂类型，在绑定值时从字符串转换而来。如果类型未知，则可以省略。 |
| description | String | 可以显示给用户的属性的简短描述。如果没有说明，可以省略。建议用简短的段落描述，第一行提供简明的摘要。说明中的最后一行应以句点（.）结尾。 |
| sourceType | String | 该类的源提供了该类的名称。例如，如果属性来自用@ConfigurationProperties注释的类，则此属性将包含该类的完全限定名。如果源类型未知，则可以省略。 |
| defaultValue | Object | 默认值，如果未指定属性，则使用该值。如果属性的类型是数组，则可以是值数组。如果默认值未知，则可以省略。 |
| deprecation | Deprecation | 指定属性是否已弃用。如果该字段未被否决或该信息未知，则可以省略该字段。下表提供了关于deprecation属性的更多详细信息。 |
每个properties元素的deprecation属性中包含的JSON对象可以包含以下属性：
| 名称 | 类型 | 目的 |
| level | String | 弃用级别，可以是warning（默认值）或error。当属性具有warning弃用级别时，它仍应绑定在环境中。但是，当属性具有error弃用级别时，该属性将不再受管理且不绑定。 |
| reason | String | 对不推荐使用该属性的原因的简短描述。如果没有理由，可以省略。建议用简短的段落描述，第一行提供简明的摘要。说明中的最后一行应以句点（.）结尾。 |
| replacement | String | 替换此不推荐使用的属性的全名。如果没有替换此属性，则可以省略。 |
在SpringBoot1.3之前，可以使用一个不推荐使用的boolean属性，而不是deprecision元素。这仍然以不推荐的方式支持，不应再使用。如果没有原因和替换，则应设置一个空的弃用对象。
也可以通过将@DeprecatedConfigurationProperty注解添加到公开deprecated属性的getter，在代码中以声明方式指定。例如，假设app.acme.target属性混乱，已重命名为app.acme.name属性. 以下示例说明如何处理这种情况：
@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);
}
}
没有办法设定一个level。由于代码仍在处理属性，因此始终假定为warning。
前面的代码确保不推荐使用的属性仍然有效（在幕后委托给name属性）。一旦可以从公共API中删除getTarget和setTarget方法，元数据中的自动弃用提示也将消失。如果希望保留提示，则添加带有error弃用级别的手动元数据可确保用户仍能了解该属性。当提供替换件时，这样做特别有用。
提示属性
提示数组中包含的JSON对象可以包含下表所示的属性：
| 名称 | 类型 | 目的 |
| name | String | 此提示引用的属性的全名。名称采用小写句点分隔形式（例如 spring.mvc.servlet.path）。如果属性引用一个map（例如system.contexts)，该提示要么应用于map的键(system.contexts.keys)或者map的value(system.contexts.values)上。此属性是必需的。 |
| values | ValueHint[] | ValueHint对象定义的有效值的列表（下表中描述）。每个条目定义值并可能有一个描述。 |
| providers | ValueProvider[] | 由ValueProvider对象定义的提供程序列表。每个条目定义提供程序的名称及其参数（如果有）。 |
每个hint元素的values属性中包含的JSON对象可以包含下表中描述的属性：
| 名称 | 类型 | 目的 |
| value | Object | 提示所指向的元素的有效值。如果属性的类型是数组，它也可以是值数组。此属性是必需的。 |
| description | String | 可以显示给用户的值的简短描述。如果没有说明，可以省略。建议用简短的段落描述，第一行提供简明的摘要。说明中的最后一行应以句点（.）结尾。 |
每个hint元素的providers属性中包含的JSON对象可以包含下表中描述的属性：
| 名称 | 类型 | 目的 |
| name | String | 用于为提示所指向的元素提供附加内容帮助的提供程序的名称。 |
| parameters | JSON object | 提供程序支持的任何其他参数 |
二、提供手动提示
要改善用户体验并进一步帮助用户配置给定属性，可以提供其他元数据：
- 描述属性的潜在值列表。
- 关联提供程序，将定义良好的语义附加到属性，以便工具可以根据项目上下文发现潜在值的列表。
值提示
每个提示的name属性都引用属性的名称。spring.jpa.hibernate.ddl auto属性：none、validate、update、create和create drop。每个值也可能有一个描述。
如果属性的类型是Map，则可以为键和值提供提示（但不能为映射本身提供提示）。特殊的.keys和.values后缀必须分别引用键和值。
假设示例上下文将魔法字符串值映射为整数，如下例所示：
@ConfigurationProperties("sample")
public class SampleProperties {
private Map<String,Integer> contexts;
// getters and setters
}
魔法值在本例中是sample1和sample2。为了为键提供额外的内容帮助，可以将以下JSON添加到模块的手动元数据中：
{"hints": [
{
"name": "sample.contexts.keys",
"values": [
{
"value": "sample1"
},
{
"value": "sample2"
}
]
}
]}
我们建议对这两个值使用枚举。如果您的IDE支持它，那么这是迄今为止最有效的自动完成方法。
