【Spring Boot 应用开发】-06 自动配置-生成配置元数据

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"

三、使用方式

1. 创建配置类，并使用 @ConfigurationProperties 注解标记：

@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {

    /**
     * 服务名称
     */
    private String name;

    /**
     * 超时时间（秒）
     */
    private int timeout = 30;

    // Getter / Setter
}

2. 注册该配置类（任选一种方式）：

• 使用 @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

七、总结

s‍pring-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 读取该文件 → 提供自动补全 & 文档提示