Spring Boot jar 包含元数据文件,这些文件提供了所有受支持的配置属性的详细信息。这些文件旨在让 IDE 开发人员在用户使用文件时提供上下文帮助和“代码完成application.properties” application.yml。
大多数元数据文件是在编译时通过处理所有带有注释的项目自动生成的@ConfigurationProperties。但是,可以为极端情况或更高级的用例手动编写部分元数据。
配置元数据文件位于 jar 中META-INF/spring-configuration-metadata.json。他们使用 JSON 格式,其中的项目分类在“组”或“属性”下,附加值提示分类在“提示”下,如以下示例所示:
每个“属性”都是用户指定一个给定值的配置项。例如,server.port可能server.address会在您的application.properties/中指定application.yaml,如下所示:
特性
“组”是更高级别的项目,它们本身不指定值,而是为属性提供上下文分组。例如,server.port和server.address属性是server组的一部分。
最后,“提示”是用于帮助用户配置给定属性的附加信息。例如,当开发人员配置spring.jpa.hibernate.ddl-auto属性时,工具可以使用提示为none、validate、update、create和create-drop值提供一些自动完成帮助。
数组中包含的 JSON 对象groups可以包含下表所示的属性:
姓名 |
类型 |
目的 |
|
细绳 |
组的全名。该属性是强制性的。 |
|
细绳 |
组的数据类型的类名。例如,如果组基于用 注释的类 |
|
细绳 |
可以向用户显示的组的简短描述。如果没有可用的描述,则可以省略。建议描述是简短的段落,第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
|
细绳 |
贡献此组的源的类名。例如,如果组基于用 |
|
细绳 |
贡献该组的方法的全名(包括括号和参数类型)(例如,带 |
数组中包含的 JSON 对象properties可以包含下表中描述的属性:
姓名 |
类型 |
目的 |
|
细绳 |
财产的全名。名称采用小写的句点分隔形式(例如, |
|
细绳 |
属性数据类型的完整签名(例如 |
|
细绳 |
可以向用户显示的属性的简短描述。如果没有可用的描述,则可以省略。建议描述是简短的段落,第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
|
细绳 |
提供此属性的源的类名。例如,如果属性来自用 注释的类 |
|
目的 |
未指定属性时使用的默认值。如果属性的类型是数组,则它可以是值数组。如果默认值未知,则可以省略。 |
|
弃用 |
指定该属性是否已弃用。如果该字段未弃用或该信息未知,则可以省略。下表提供了有关该 |
deprecation每个元素的属性中包含的 JSON 对象properties可以包含以下属性:
姓名 |
类型 |
目的 |
|
细绳 |
弃用级别,可以是 |
|
细绳 |
属性被弃用的原因的简短描述。如果没有可用的原因,则可以省略。建议描述是简短的段落,第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
|
细绳 |
替换此已弃用属性的属性的全名。如果没有替代此属性,则可以省略。 |
也可以通过将@DeprecatedConfigurationProperty注释添加到公开已弃用属性的 getter 来在代码中以声明方式指定弃用。例如,假设该my.app.target属性令人困惑并被重命名为my.app.name. 以下示例显示了如何处理这种情况:
前面的代码确保不推荐使用的属性仍然有效(委托给name幕后的属性)。一旦可以从公共 API 中删除getTargetandsetTarget方法,元数据中的自动弃用提示也会消失。如果您想保留提示,添加具有error弃用级别的手动元数据可确保用户仍了解该属性。当提供 a 时,这样做特别有用replacement。
数组中包含的 JSON 对象hints可以包含下表所示的属性:
姓名 |
类型 |
目的 |
|
细绳 |
此提示所指的属性的全名。名称采用小写句点分隔形式(例如 |
|
值提示[] |
由对象定义的有效值列表 |
|
价值提供者[] |
对象定义的提供者列表 |
values每个hint元素的属性中包含的 JSON 对象可以包含下表中描述的属性:
姓名 |
类型 |
目的 |
|
目的 |
提示所指元素的有效值。如果属性的类型是一个数组,它也可以是一个值数组。该属性是强制性的。 |
|
细绳 |
可以向用户显示的值的简短描述。如果没有可用的描述,则可以省略。建议描述是简短的段落,第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
providers每个hint元素的属性中包含的 JSON 对象可以包含下表中描述的属性:
姓名 |
类型 |
目的 |
|
细绳 |
提供者的名称,用于为提示所指的元素提供额外的内容帮助。 |
|
JSON 对象 |
提供程序支持的任何附加参数(查看提供程序的文档以获取更多详细信息)。 |
具有相同“属性”和“组”名称的对象可以在元数据文件中出现多次。例如,您可以将两个单独的类绑定到相同的前缀,每个类都有可能重叠的属性名称。虽然元数据中多次出现的相同名称不应该是常见的,但元数据的消费者应该注意确保他们支持它。
为了改善用户体验并进一步帮助用户配置给定的属性,您可以提供额外的元数据:
描述属性的潜在值列表。
关联一个提供者,将定义明确的语义附加到属性,以便工具可以根据项目的上下文发现潜在值列表。
2.1. 值提示
每个提示的name属性是指name一个属性的。在前面显示的初始示例中,我们为spring.jpa.hibernate.ddl-auto属性提供了五个值:none、validate、update、create和create-drop。每个值也可能有描述。
如果您的属性是 类型Map,您可以为键和值提供提示(但不能为地图本身提供提示)。特殊.keys和.values后缀必须分别引用键和值。
假设 amy.contexts将魔法String值映射到整数,如以下示例所示:
神奇的值是(在这个例子中)是sample1和sample2。为了为密钥提供额外的内容帮助,您可以将以下 JSON 添加到模块的手动元数据中:
2.2. 价值提供者
提供程序是一种将语义附加到属性的强大方法。在本节中,我们定义了可用于您自己的提示的官方提供程序。但是,您最喜欢的 IDE 可能实现了其中的一些,也可能没有实现。此外,它最终可以提供自己的。
下表总结了支持的提供商列表:
姓名 |
描述 |
|
允许提供任何附加值。 |
|
自动完成项目中可用的类。通常受 |
|
处理属性,就好像它是由强制 |
|
自动完成有效的记录器名称和记录器组。通常,当前项目中可用的包和类名称可以自动完成以及定义的组。 |
|
自动完成当前项目中可用的 bean 名称。通常受 |
|
自动完成项目中可用的 Spring 配置文件名称。 |
2.2.1. 任何
特殊的any provider 值允许提供任何附加值。如果支持,则应应用基于属性类型的常规值验证。
如果您有值列表并且任何额外值仍应被视为有效,则通常使用此提供程序。
以下示例提供on
和off
作为 的自动完成值system.state
:
请注意,在前面的示例中,也允许使用任何其他值。
2.2.2类参考
类引用提供程序自动完成项目中可用的类。此提供程序支持以下参数:
范围 |
类型 |
默认值 |
描述 |
|
|
没有任何 |
应分配给所选值的类的完全限定名称。通常用于过滤掉非候选类。请注意,此信息可以由类型本身通过公开具有适当上限的类来提供。 |
|
|
真的 |
指定是否只有具体类被视为有效候选者。 |
以下元数据片段对应于server.servlet.jsp.class-name
定义JspServlet
要使用的类名的标准属性:
2.2.3. 处理为
handle-as提供程序允许您将属性的类型替换为更高级别的类型。这通常发生在属性具有java.lang.String
类型时,因为您不希望配置类依赖于可能不在类路径中的类。此提供程序支持以下参数:
范围 |
类型 |
默认值 |
描述 |
|
|
没有任何 |
要为属性考虑的类型的完全限定名称。此参数是必需的。 |
可以使用以下类型:
- Any
java.lang.Enum
:列出属性的可能值。(我们建议使用类型定义属性Enum
,因为 IDE 不需要进一步的提示来自动完成值) -
java.nio.charset.Charset
:支持字符集/编码值的自动补全(如UTF-8
) -
java.util.Locale
: 语言环境的自动补全(例如en_US
) -
org.springframework.util.MimeType
: 支持内容类型值的自动补全(如text/plain
) -
org.springframework.core.io.Resource
: 支持自动完成 Spring 的资源抽象以引用文件系统或类路径上的文件(例如classpath:/sample.properties
)
以下元数据片段对应于spring.liquibase.change-log
定义要使用的更改日志路径的标准属性。它实际上在内部用作 aorg.springframework.core.io.Resource
但不能这样公开,因为我们需要保留原始 String 值以将其传递给 Liquibase API。
2.2.4. 记录器名称
记录器名称提供程序自动完成有效的记录器名称和记录器组。通常,可以自动完成当前项目中可用的包和类名称。如果启用了组(默认)并且在配置中标识了自定义记录器组,则应为其提供自动完成功能。特定的框架可能有额外的魔法记录器名称,这些名称也可以被支持。
此提供程序支持以下参数:
范围 |
类型 |
默认值 |
描述 |
|
|
|
指定是否应考虑已知组。 |
由于记录器名称可以是任意名称,因此此提供程序应允许任何值,但可以突出显示项目类路径中不可用的有效包和类名称。
以下元数据片段对应于标准logging.level
属性。键是记录器名称,值对应于标准日志级别或任何自定义级别。由于 Spring Boot 定义了一些开箱即用的记录器组,因此已为它们添加了专用值提示。
2.2.5. Spring Bean 参考
spring-bean-reference提供者自动完成当前项目配置中定义的 bean 。此提供程序支持以下参数:
范围 |
类型 |
默认值 |
描述 |
|
|
没有任何 |
应分配给候选者的 bean 类的完全限定名称。通常用于过滤掉非候选bean。 |
以下元数据片段对应于spring.jmx.server
定义MBeanServer
要使用的 bean 名称的标准属性:
2.2.6. 弹簧配置文件名称
spring-profile-name提供程序自动完成在当前项目的配置中定义的 Spring 配置文件。
以下元数据片段对应于spring.profiles.active
定义要启用的 Spring 配置文件名称的标准属性:
3. 使用注释处理器生成您自己的元数据
@ConfigurationProperties
您可以使用spring-boot-configuration-processor
jar从带有注释的项目轻松生成自己的配置元数据文件。该 jar 包含一个 Java 注释处理器,它会在您的项目编译时调用。
3.1配置注解处理器
要使用处理器,请包含对spring-boot-configuration-processor
.
对于 Maven,应将依赖项声明为可选的,如以下示例所示:
使用 Gradle,应在annotationProcessor
配置中声明依赖项,如以下示例所示:
如果您使用的是additional-spring-configuration-metadata.json
文件,compileJava
则应将任务配置为依赖于processResources
任务,如下例所示:
此依赖关系确保在编译期间注释处理器运行时附加元数据可用。
3.2. 自动元数据生成
处理器拾取带有注释的类和方法@ConfigurationProperties
。
如果该类也用 注释@ConstructorBinding
,则需要一个构造函数,并且为每个构造函数参数创建一个属性。否则,通过对集合和映射类型进行特殊处理的标准 getter 和 setter 的存在来发现属性(即使仅存在 getter 也会被检测到)。注释处理器还支持使用@Data
、@Value
、@Getter
和@Setter
lombok 注释。
考虑以下示例:
这公开了三个属性,其中my.server.name
没有默认值my.server.ip
并且分别my.server.port
默认为"127.0.0.1"
和9797
。字段上的 Javadoc 用于填充description
属性。例如,描述my.server.ip
是“要收听的 IP 地址”。
注释处理器应用许多启发式方法从源模型中提取默认值。必须静态提供默认值。特别是,不要引用另一个类中定义的常量。此外,注释处理器无法自动检测Enum
s 和Collections
s 的默认值。
对于无法检测到默认值的情况,应提供手动元数据。考虑以下示例:
为了记录上面类中属性的默认值,您可以将以下内容添加到模块的手动元数据中:
3.2.1嵌套属性
注释处理器自动将内部类视为嵌套属性。我们可以为它创建一个子命名空间,而不是在命名空间的根部记录ip
和。port
考虑更新的例子:
前面的示例为 、 和 属性生成元my.server.name
数据my.server.host.ip
信息my.server.host.port
。您可以@NestedConfigurationProperty
在字段上使用注释来指示应将常规(非内部)类视为嵌套类。
3.3. 添加其他元数据
Spring Boot 的配置文件处理非常灵活,并且经常会出现未绑定到@ConfigurationProperties
bean 的属性。您可能还需要调整现有密钥的某些属性。为了支持这种情况并让您提供自定义“提示”,注释处理器会自动将项目从合并META-INF/additional-spring-configuration-metadata.json
到主元数据文件中。
如果您引用已自动检测到的属性,则描述、默认值和弃用信息将被覆盖(如果已指定)。如果当前模块中未识别手动属性声明,则将其添加为新属性。
该additional-spring-configuration-metadata.json
文件的格式与常规spring-configuration-metadata.json
. 附加属性文件是可选的。如果您没有任何其他属性,请不要添加该文件。