|
此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.4.3！ |
使用 Annotation Processor 生成您自己的元数据
您可以轻松地从带有@ConfigurationProperties通过使用spring-boot-configuration-processor罐。
该 jar 包括一个 Java 注释处理器，该处理器在编译项目时调用。
配置 Annotation 处理器
使用 Maven 构建时，配置编译器插件（3.12.0 或更高版本）以添加spring-boot-configuration-processor到 Annotation Processor 路径中：
<project>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
</project>使用 Gradle 时，应在annotationProcessor配置，如以下示例所示：
dependencies {
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}如果您使用的是additional-spring-configuration-metadata.json文件中，使用compileJavatask 应配置为依赖于processResources任务，如以下示例所示：
tasks.named('compileJava') {
inputs.files(tasks.named('processResources'))
}此依赖关系可确保在编译期间 Comments 处理器运行时其他元数据可用。
|
如果你在你的项目中使用 AspectJ，你需要确保 Comments 处理器只运行一次。
有几种方法可以做到这一点。
使用 Maven，您可以配置 |
|
如果您在项目中使用 Lombok，则需要确保其注释处理器在 |
自动元数据生成
处理器会选取带有@ConfigurationProperties.
使用@ConfigurationProperties不受支持。 |
如果类具有单个参数化构造函数，则每个构造函数参数将创建一个属性，除非构造函数使用@Autowired.
如果类具有显式注释为@ConstructorBinding，则为该构造函数的每个构造函数参数创建一个属性。
否则，将通过存在标准 getter 和 setter 来发现属性，并对 collection 和 map 类型进行特殊处理（即使仅存在 getter，也会检测到）。
注解处理器还支持使用@Data,@Value,@Getter和@Setterlombok 注释。
请考虑以下示例：
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("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;
}
}
This exposes three properties where my.server.name has no default and my.server.ip and my.server.port defaults to "127.0.0.1" and 9797 respectively.
The Javadoc on fields is used to populate the description attribute.
For instance, the description of my.server.ip is "IP address to listen to.".
The description attribute can only be populated when the type is available as source code that is being compiled.
It will not be populated when the type is only available as a compiled class from a dependency.
For such cases, manual metadata should be provided.
You should only use plain text with @ConfigurationProperties field Javadoc, since they are not processed before being added to the JSON.
If you use @ConfigurationProperties with record class then record components' descriptions should be provided via class-level Javadoc tag @param (there are no explicit instance fields in record classes to put regular field-level Javadocs on).
The annotation processor applies a number of heuristics to extract the default value from the source model.
Default values can only be extracted when the type is available as source code that is being compiled.
They will not be extracted when the type is only available as a compiled class from a dependency.
Furthermore, default values have to be provided statically.
In particular, do not refer to a constant defined in another class.
Also, the annotation processor cannot auto-detect default values for Collectionss.
For cases where the default value could not be detected, manual metadata should be provided.
Consider the following example:
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("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
}
}
In order to document default values for properties in the class above, you could add the following content to the manual metadata of the module:
{"properties": [
{
"name": "my.messaging.addresses",
"defaultValue": ["a", "b"]
},
{
"name": "my.messaging.container-type",
"defaultValue": "simple"
}
]}
Only the name of the property is required to document additional metadata for existing properties.
Nested Properties
The annotation processor automatically considers inner classes as nested properties.
Rather than documenting the ip and port at the root of the namespace, we could create a sub-namespace for it.
Consider the updated example:
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("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;
}
}
}
The preceding example produces metadata information for my.server.name, my.server.host.ip, and my.server.host.port properties.
You can use the @NestedConfigurationProperty annotation on a field or a getter method to indicate that a regular (non-inner) class should be treated as if it were nested.
This has no effect on collections and maps, as those types are automatically identified, and a single metadata property is generated for each of them.
Adding Additional Metadata
Spring Boot’s configuration file handling is quite flexible, and it is often the case that properties may exist that are not bound to a @ConfigurationProperties bean.
You may also need to tune some attributes of an existing key or to ignore the key altogether.
To support such cases and let you provide custom "hints", the annotation processor automatically merges items from META-INF/additional-spring-configuration-metadata.json into the main metadata file.
If you refer to a property that has been detected automatically, the description, default value, and deprecation information are overridden, if specified.
If the manual property declaration is not identified in the current module, it is added as a new property.
The format of the additional-spring-configuration-metadata.json file is exactly the same as the regular spring-configuration-metadata.json.
The items contained in the “ignored.properties” section are removed from the “properties” section of the generated spring-configuration-metadata.json file.
The additional properties file is optional.
If you do not have any additional properties, do not add the file.