Spring Boot Configuration Processor 使用指南
一、概述
spring-boot-configuration-processor 是 Spring Boot 提供的一个用于编译期处理 @ConfigurationProperties 注解的模块。它的主要作用是生成配置元数据文件（spring-configuration-metadata.json），用于增强开发体验，例如：
- 在 IDE 中为配置文件（
application.yml/application.properties）提供自动补全、文档提示。 - 提供类型、默认值、描述等信息，方便配置管理和排查错误。
具体是干啥呢？举个例子，比如你在yml中自定义了一个token配置的配置项，如下：
发现了一个提示：Cannot resolve configuration property ‘jwt.token.secret’，无法解析配置属性“jwt.token.secrete” ，你点击它，也不会跳转到对应的配置类去。这和一些springboot自带的自动配置属性为什么不一样？其实就是没有依赖spring-boot-configuration-processor，依赖它，就OK了
二、引入依赖
在 Maven 项目中加入如下依赖：
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-configuration-processor</artifactId><optional>true</optional> <!-- 编译期依赖，不传递 -->
</dependency>
或者使用 provided scope（可选）：
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-configuration-processor</artifactId><scope>provided</scope>
</dependency>
注意：Gradle 用户应添加：
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
三、使用方式
- 创建配置类，并使用
@ConfigurationProperties注解标记：
@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {/*** 服务名称*/private String name;/*** 超时时间（秒）*/private int timeout = 30;// Getter / Setter
}
- 注册该配置类（任选一种方式）：
- 使用
@EnableConfigurationProperties：
@EnableConfigurationProperties(MyServiceProperties.class)
@Configuration
public class AppConfig {}
- 或者直接用
@Component注解让其被 Spring 扫描：
@Component
@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {}
四、生成的文件说明
编译后会自动在 target/classes/META-INF/ 目录下生成：
spring-configuration-metadata.json
这个文件包含了配置类中的每个字段的元数据，如：
{"name": "my.service.timeout","type": "java.lang.Integer","defaultValue": 30,"description": "超时时间（秒）"
}
该文件被 IDEA 和其他支持 Spring Boot 的工具识别并用于配置提示。
五、常见问题
1. 没有提示怎么办？
- 确保使用了
@ConfigurationProperties，不是@Value。 - 确保类已注册为 Spring Bean（通过
@Component或@EnableConfigurationProperties）。 - 检查是否已引入
spring-boot-configuration-processor并正确编译生成 metadata。 - 确保项目已 重新构建（Rebuild），并非仅增量编译。
2. 如何为字段添加描述？
使用 JavaDoc 注释即可自动写入 metadata 提示中：
/*** 是否启用缓存*/
private boolean cacheEnabled;
六、适用版本
spring-boot-configuration-processor通常与 Spring Boot 主版本一致。例如：- Spring Boot 3.2.x ⇒ 使用
spring-boot-configuration-processor:3.2.x - Spring Boot 2.7.x ⇒ 使用
spring-boot-configuration-processor:2.7.x
- Spring Boot 3.2.x ⇒ 使用
七、总结
| 优点 | 描述 |
|---|---|
| 配置补全 | 在 IDE 中自动提示可配置项 |
| 自动生成文档 | 生成描述信息、默认值等 |
| 类型安全 | 配置类支持类型校验、校验注解支持 |
| 编译期处理，运行时无影响 | 不会影响程序运行，只在开发时生效 |
spring-configuration-metadata.json 的工作原理是基于注解处理器（Annotation Processor）机制，在编译期自动生成配置属性的元数据文件，供开发工具（比如 IntelliJ IDEA 或 VS Code）使用，用于提供配置提示、文档说明、默认值等功能。
八、 🌱 工作原理详解
1. 基于注解处理器（Annotation Processor）
spring-boot-configuration-processor 的模块，其中内置了一个注解处理器，它会在 Java 编译时扫描你的代码：
- 查找所有使用了
@ConfigurationProperties注解的类。 - 提取类中的字段、JavaDoc 注释、默认值、类型信息。
- 将这些信息生成 JSON 格式的元数据。
这个注解处理器符合 Java 标准的 APT（Annotation Processing Tool）机制。
2. 编译期生成 spring-configuration-metadata.json
编译时，该 Processor 会在你的项目输出目录生成：
target/classes/META-INF/spring-configuration-metadata.json
里面的内容大致如下：
{"properties": [{"name": "my.service.timeout","type": "java.lang.Integer","defaultValue": 30,"description": "超时时间（秒）"}]
}
这不是被 Spring Boot 应用读取的文件，而是给 IDE / 开发工具 用的。
3. IDE 如何使用？
像 IntelliJ IDEA、VS Code 这类工具，会在你打开 application.yml / application.properties 时：
- 扫描 classpath 下的
META-INF/spring-configuration-metadata.json - 加载其中的
name、type、description等 - 然后在你输入配置项时，提供自动补全、类型提示、文档说明等
例如：
my.service.timeout: 30
# ↑ IDE 会提示 "超时时间（秒）", 类型为 Integer，默认值 30
4. 开发者还能做什么？
你可以通过自定义 additional-spring-configuration-metadata.json 来补充额外的配置项提示（比如没有显式定义的配置项，如 SPI 加载的类）。
放置位置：
src/main/resources/META-INF/additional-spring-configuration-metadata.json
格式与自动生成的 JSON 相同。
✅ 总结流程图：
@ConfigProps类 + spring-boot-configuration-processor↓编译期注解处理器（APT）↓生成 spring-configuration-metadata.json↓IDE 读取该文件 → 提供自动补全 & 文档提示