使用注释处理器生成自己的元数据
您可以使用 spring-boot-configuration-processor jar 从使用 @ConfigurationProperties 注解的项目中轻松生成自己的配置元数据文件。该 jar 包含一个 Java 注解处理器，它在编译项目时被调用。
配置注解处理器
要使用处理器，请在 spring-boot-configuration-processor 上添加依赖项。
使用 Maven 时，依赖项应声明为可选，如以下示例所示
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>使用 Gradle 时，依赖项应声明在 annotationProcessor 配置中，如以下示例所示
dependencies {
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}如果您使用的是 additional-spring-configuration-metadata.json 文件，则应将 compileJava 任务配置为依赖于 processResources 任务，如以下示例所示
tasks.named('compileJava') {
inputs.files(tasks.named('processResources'))
}此依赖项确保在编译期间注解处理器运行时，附加元数据可用。
|
如果您在项目中使用 AspectJ，则需要确保注解处理器只运行一次。有几种方法可以做到这一点。使用 Maven 时，您可以显式配置 |
|
如果您在项目中使用 Lombok，则需要确保其注解处理器在 |
自动元数据生成
处理器会获取所有使用 @ConfigurationProperties 注解的类和方法。
如果类只有一个带参数的构造函数，则会为每个构造函数参数创建一个属性，除非构造函数使用 @Autowired 注解。如果类有一个显式使用 @ConstructorBinding 注解的构造函数，则会为该构造函数的每个构造函数参数创建一个属性。否则，属性将通过标准 getter 和 setter 的存在来发现，并对集合和映射类型进行特殊处理（即使只存在 getter 也会检测到）。注解处理器还支持使用 @Data、@Value、@Getter 和 @Setter lombok 注解。
考虑以下示例
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {
/**
* Name of the server.
*/
private String name;
/**
* IP address to listen to.
*/
private String ip = "127.0.0.1";
/**
* Port to listener to.
*/
private int port = 9797;
// getters/setters ...
public String getName() {
return this.name;
}
public void setName(String name) {
this.name = name;
}
public String getIp() {
return this.ip;
}
public void setIp(String ip) {
this.ip = ip;
}
public int getPort() {
return this.port;
}
public void setPort(int port) {
this.port = port;
}
// fold:off
}这将公开三个属性，其中 my.server.name 没有默认值，而 my.server.ip 和 my.server.port 的默认值分别为 "127.0.0.1" 和 9797。字段上的 Javadoc 用于填充 description 属性。例如，my.server.ip 的描述是“要监听的 IP 地址”。
您应该只使用带有 @ConfigurationProperties 字段 Javadoc 的纯文本，因为它们在添加到 JSON 之前不会被处理。
|
如果您将 @ConfigurationProperties 与记录类一起使用，则应通过类级 Javadoc 标签 @param 提供记录组件的描述（记录类中没有显式实例字段来放置常规字段级 Javadoc）。
注解处理器应用了一些启发式方法来从源模型中提取默认值。默认值必须以静态方式提供。特别是，不要引用在另一个类中定义的常量。此外，注解处理器无法自动检测 Enum 和 Collections 的默认值。
对于无法检测到默认值的情况，应提供 手动元数据。考虑以下示例
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "my.messaging")
public class MyMessagingProperties {
private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));
private ContainerType containerType = ContainerType.SIMPLE;
// getters/setters ...
public List<String> getAddresses() {
return this.addresses;
}
public void setAddresses(List<String> addresses) {
this.addresses = addresses;
}
public ContainerType getContainerType() {
return this.containerType;
}
public void setContainerType(ContainerType containerType) {
this.containerType = containerType;
}
public enum ContainerType {
SIMPLE, DIRECT
}
}为了记录上述类中属性的默认值，您可以将以下内容添加到 模块的手动元数据 中
{"properties": [
{
"name": "my.messaging.addresses",
"defaultValue": ["a", "b"]
},
{
"name": "my.messaging.container-type",
"defaultValue": "simple"
}
]}
只需要属性的 name 就可以记录现有属性的附加元数据。
|
嵌套属性
注解处理器会自动将内部类视为嵌套属性。与其在命名空间的根目录下记录ip和port，我们可以为其创建一个子命名空间。请考虑更新后的示例
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {
private String name;
private Host host;
// getters/setters ...
public String getName() {
return this.name;
}
public void setName(String name) {
this.name = name;
}
public Host getHost() {
return this.host;
}
public void setHost(Host host) {
this.host = host;
}
public static class Host {
private String ip;
private int port;
// getters/setters ...
public String getIp() {
return this.ip;
}
public void setIp(String ip) {
this.ip = ip;
}
public int getPort() {
return this.port;
}
public void setPort(int port) {
this.port = port;
}
// @fold:off // getters/setters ...
}
}前面的示例为my.server.name、my.server.host.ip和my.server.host.port属性生成了元数据信息。您可以在字段上使用@NestedConfigurationProperty注解来指示将常规（非内部）类视为嵌套类。
| 这不会影响集合和映射，因为这些类型会自动识别，并且会为每个类型生成一个单独的元数据属性。 |
添加额外元数据
Spring Boot 的配置文件处理非常灵活，通常情况下，可能存在未绑定到@ConfigurationProperties bean 的属性。您可能还需要调整现有键的一些属性。为了支持这些情况并让您提供自定义“提示”，注解处理器会自动将META-INF/additional-spring-configuration-metadata.json中的项合并到主元数据文件中。
如果您引用了已自动检测到的属性，则会覆盖描述、默认值和弃用信息（如果指定）。如果在当前模块中未识别手动属性声明，则会将其添加为新属性。
additional-spring-configuration-metadata.json文件的格式与常规spring-configuration-metadata.json完全相同。额外的属性文件是可选的。如果您没有其他属性，请不要添加该文件。
