为什么 application.yml 里写配置能有 IDE 自动补全和提示？配置元数据是什么？

简化版

IDE（IntelliJ、VS Code）在 application.yml/application.properties 里能自动补全配置项、显示说明和默认值、校验拼写，靠的是「配置元数据（Configuration Metadata）」——一个描述「有哪些配置项、类型是什么、默认值和说明是什么」的 JSON 文件 META-INF/spring-configuration-metadata.json。Spring Boot 自己和各个 starter 都带着这个元数据文件（描述它们提供的配置项，如 server.port、spring.datasource.url），IDE 读取它就能提供智能提示。你自己写的 @ConfigurationProperties 配置类，怎么也让它有 IDE 提示：引入 spring-boot-configuration-processor（一个注解处理器，optional/provided 依赖）——它在编译期扫描你的 @ConfigurationProperties 类，自动生成对应的元数据 JSON，于是你自定义的配置项（如 app.user.name）在 yml 里也能补全和提示。加说明和默认值：给字段写 Javadoc 注释会变成 IDE 的提示文本；还能用 additional-spring-configuration-metadata.json 补充手工元数据。核心：元数据 = 配置项的「说明书」，让 IDE 智能提示。

详细版

配置元数据 JSON 的结构（简化）：

{
  "properties": [
    {
      "name": "app.user.name",           // 配置项名
      "type": "java.lang.String",        // 类型
      "description": "用户名称",          // 说明（来自 Javadoc）
      "defaultValue": "guest",           // 默认值
      "sourceType": "com.example.UserProps"
    }
  ],
  "hints": [ /* 可提供可选值提示等 */ ]
}

让自定义配置类有 IDE 提示：

<!-- 引入配置元数据注解处理器（编译期生成元数据）-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

@ConfigurationProperties(prefix = "app.user")
public class UserProps {
    /**
     * 用户名称。            ← 这段 Javadoc 会变成 IDE 的提示说明
     */
    private String name = "guest";   // = "guest" 会被识别为默认值
    private int maxAge = 120;
    // getter/setter...
}

⚠️ 配置元数据是「开发期体验」的东西，和「运行时是否生效」完全无关——就算没有元数据、没有 IDE 提示，你写的配置照样能被 @ConfigurationProperties 绑定生效（绑定靠的是运行时的宽松绑定机制，见宽松绑定题）。元数据只是让开发时有补全、提示、拼写校验，提升写配置的效率和正确性。所以：元数据文件不存在 ≠ 配置不生效，它纯粹是「给 IDE 看的说明书」。反过来，如果你自定义的配置项在 yml 里被 IDE 标黄「Unknown property」，多半是没引入 spring-boot-configuration-processor（没生成元数据），配置本身仍然是生效的——加上这个依赖、重新编译，提示就有了。

完整版教学

一、现象：IDE 的配置智能提示

先认识这个「习以为常但值得追问」的现象：

在 application.yml 里敲配置时，IDE 能做到：
  ① 自动补全：敲 server. 就弹出 server.port、server.address...
  ② 显示说明：光标停在 server.port 上，显示"服务器监听端口"
  ③ 显示类型和默认值：server.port 是 int，默认 8080
  ④ 拼写校验：写错 serverr.port 会标黄"Unknown property"
  ⑤ 可选值提示：某些枚举类型的配置能提示所有可选值

问题：IDE 怎么知道"有哪些配置项、类型、说明、默认值"？
  它又不认识 Spring Boot 内部的每个配置类
  → 靠"配置元数据"文件（一份描述所有配置项的清单）

这个现象是「IDE 能对 Spring Boot 配置做智能提示」（补全、说明、类型默认值、拼写校验、可选值）。追问「IDE 怎么知道有哪些配置项」——它不认识 Spring Boot 内部的配置类，靠的是「配置元数据」文件（一份描述所有配置项的清单）。理解「IDE 的配置智能提示(补全/说明/类型/校验)靠配置元数据文件、而非 IDE 认识配置类」，就抓住了问题的核心。

二、配置元数据文件是什么

配置元数据就是一份「配置项说明书」JSON：

文件位置：META-INF/spring-configuration-metadata.json
  （打包在 jar 里，每个提供配置的 jar 都可能带一份）

内容：描述每个配置项
  - name：配置项名（如 server.port）
  - type：类型（java.lang.Integer）
  - description：说明（人类可读的解释）
  - defaultValue：默认值
  - sourceType：这个配置来自哪个类

IDE 的工作：
  扫描项目依赖里所有 jar 的 spring-configuration-metadata.json
  汇总所有配置项 → 敲配置时按这份清单补全、提示、校验

所以：Spring Boot 本体和每个 starter 都带着自己的元数据文件
  → 描述它们提供的配置项
  → 引入 spring-boot-starter-web，就有了 server.* 的提示

配置元数据是「一份 JSON 格式的配置项说明书」（META-INF/spring-configuration-metadata.json）——描述每个配置项的 name/type/description/defaultValue。IDE 扫描项目所有 jar 里的这个文件，汇总配置项清单，据此补全、提示、校验。Spring Boot 本体和每个 starter 都带着自己的元数据文件（描述它们的配置项），所以引入 starter 就有了对应配置的提示。理解「配置元数据是 JSON 说明书(name/type/description/defaultValue)、IDE 扫描所有 jar 的元数据汇总提示、每个 starter 带自己的元数据」，就理解了元数据文件的本质。

三、注解处理器：编译期自动生成元数据

Spring Boot 官方的元数据是怎么来的？靠注解处理器在编译期自动生成：

spring-boot-configuration-processor：
  是一个"注解处理器"（Annotation Processor）
  在"编译期"（javac 编译时）工作：
    1. 扫描项目里所有 @ConfigurationProperties 类
    2. 分析它们的字段（名字、类型、默认值、Javadoc 注释）
    3. 生成 META-INF/spring-configuration-metadata.json

所以你的自定义配置类要有 IDE 提示：
  引入 spring-boot-configuration-processor 依赖
  → 编译时它自动为你的 @ConfigurationProperties 类生成元数据
  → yml 里写 app.user.name 就有补全和提示了

依赖声明：optional=true（Maven）/ annotationProcessor（Gradle）
  → 它只在编译期用，不需要打进运行时（运行时不需要元数据）

★ 引入后要"重新编译"才生成元数据（改了配置类也要重编）

Spring Boot 的元数据靠 spring-boot-configuration-processor（注解处理器） 在编译期自动生成——它扫描项目里的 @ConfigurationProperties 类，分析字段（名字、类型、默认值、Javadoc），生成元数据 JSON。所以让自定义配置类有 IDE 提示：引入这个依赖（optional/annotationProcessor，只编译期用不打进运行时），重新编译后就为你的配置类生成了元数据。理解「spring-boot-configuration-processor 是注解处理器、编译期扫描 @ConfigurationProperties 生成元数据、引入后重新编译就有提示、optional 依赖只编译期用」，就理解了元数据的生成机制。

四、说明和默认值：Javadoc 与字段初值

怎么让自定义配置项的提示里有「说明」和「默认值」：

① 说明（description）：写字段的 Javadoc 注释
   /**
    * 用户的最大年龄限制。       ← 这段会进元数据的 description
    */
   private int maxAge = 120;
   → IDE 提示时显示这段说明

② 默认值（defaultValue）：给字段赋初值
   private int maxAge = 120;    ← 120 被识别为默认值
   private String name = "guest";
   → IDE 提示时显示默认值

③ 类型（type）：字段类型自动识别
   private Duration timeout;    → 提示这是 Duration 类型

所以写配置类时的好习惯：
  - 给字段写清楚的 Javadoc（变成用户看到的说明）
  - 给字段赋合理的默认值（既是真的默认值，又进元数据）
  → 让使用你配置的人（甚至未来的自己）在 IDE 里就能看懂每个配置

自定义配置项的「说明」和「默认值」来自代码本身：说明来自字段的 Javadoc 注释（会进元数据的 description）、默认值来自字段初值（= 120 被识别为 defaultValue）、类型自动识别。所以写 @ConfigurationProperties 类的好习惯是「给字段写清楚 Javadoc + 赋合理默认值」，让使用者在 IDE 里就看懂每个配置。理解「说明来自 Javadoc、默认值来自字段初值、类型自动识别、写配置类应写 Javadoc 和默认值」，就掌握了让提示更友好的方法。

五、手工补充元数据

有些元数据自动生成不了，需要手工补充：

additional-spring-configuration-metadata.json：
  位置：src/main/resources/META-INF/
  作用：手工补充/覆盖自动生成的元数据

什么时候需要手工补充：
  ① 提供"可选值提示"（hints）：
     如某配置只能是 dev/test/prod，让 IDE 提示这几个值
  ② 描述"动态/无法自动识别"的配置：
     如通过 Environment 直接读的、没有对应 @ConfigurationProperties 字段的
  ③ 补充/修正自动生成的说明、默认值

例（提供可选值提示）：
  {
    "hints": [{
      "name": "app.mode",
      "values": [
        {"value": "dev", "description": "开发模式"},
        {"value": "prod", "description": "生产模式"}
      ]
    }]
  }

自动生成（configuration-processor）+ 手工补充（additional-...json）
  = 完整的配置元数据 → 最好的 IDE 体验

有些元数据自动生成不了，用 additional-spring-configuration-metadata.json（手工补充）——放在 META-INF/，用于：提供可选值提示（hints，如某配置只能 dev/test/prod）、描述动态/无对应字段的配置、修正自动生成的内容。自动生成（configuration-processor）+ 手工补充 = 完整元数据。理解「additional-spring-configuration-metadata.json 手工补充元数据、用于可选值 hints/动态配置/修正、和自动生成配合得到完整元数据」，就掌握了手工补充的方法。

六、元数据 ≠ 运行时生效

一个必须澄清的认知：元数据只影响开发体验，不影响运行时：

关键区分：
  配置元数据 → 开发期的 IDE 提示（补全、说明、校验）
  配置绑定生效 → 运行时的 @ConfigurationProperties 绑定（宽松绑定机制）
  → 两者完全独立！

推论：
  ① 没有元数据（没引入 configuration-processor）：
     IDE 里写自定义配置会标黄"Unknown property"
     但配置照样能绑定生效！（运行时不需要元数据）
     → 标黄不代表配置无效，只是 IDE 不认识而已

  ② 有元数据：
     只是 IDE 智能提示更好，运行时行为不变

  ③ 元数据说明/默认值写错：
     只影响 IDE 显示，不影响实际绑定的值

所以排查"配置不生效"时，别被"IDE 标黄"误导：
  IDE 标黄 = 缺元数据（加 configuration-processor 解决）
  配置不生效 = 绑定问题（字段没 setter / POJO 没成 Bean / key 写错）
  → 是两码事

必须澄清：配置元数据（开发期 IDE 提示）和配置绑定生效（运行时）完全独立——没有元数据（没引入 configuration-processor）时，IDE 会标黄「Unknown property」，但配置照样绑定生效（运行时不需要元数据）；元数据写错也只影响 IDE 显示不影响实际值。所以排查「配置不生效」别被「IDE 标黄」误导：标黄 = 缺元数据（加 configuration-processor）；不生效 = 绑定问题（字段没 setter/POJO 没成 Bean/key 错），是两码事。理解「元数据只影响 IDE 提示不影响运行时生效、缺元数据会标黄但配置仍有效、别把 IDE 标黄当成配置不生效」，就避开了一个常见的认知误区。

记忆钩子：「IDE 对 Spring Boot 配置的智能提示(补全/说明/类型默认值/拼写校验/可选值)靠’配置元数据’JSON(META-INF/spring-configuration-metadata.json,描述配置项 name/type/description/defaultValue);Spring Boot 和每个 starter 自带元数据;让自定义 @ConfigurationProperties 有提示→引入 spring-boot-configuration-processor(编译期注解处理器扫描配置类生成元数据,optional 依赖,要重新编译);说明来自字段 Javadoc、默认值来自字段初值;可选值等手工补充用 additional-spring-configuration-metadata.json;★元数据只影响开发期 IDE 提示、不影响运行时生效——缺元数据 IDE 标黄但配置照样绑定生效」。

七、常见误区与追问

误区：IDE 标黄「Unknown property」说明配置无效。 不是——标黄只说明缺元数据（IDE 不认识这个配置项），配置照样能被 @ConfigurationProperties 绑定生效；引入 spring-boot-configuration-processor 重新编译后标黄就消失了，但配置的生效与否和标黄无关。
误区：配置元数据是运行时用的。 元数据纯粹是「给 IDE 看的开发期说明书」，运行时完全用不到——配置绑定靠运行时的宽松绑定机制；所以元数据是 optional/编译期依赖，不打进也不影响运行。
误区：自定义配置类天然就有 IDE 提示。 需要引入 spring-boot-configuration-processor（编译期注解处理器）为你的 @ConfigurationProperties 类生成元数据，且要重新编译；不引入就没有提示（会标黄），但配置仍生效。
误区：配置项的说明要单独写文件。 直接写字段的 Javadoc 注释就会被注解处理器提取成元数据的 description（IDE 提示文本），字段初值会被识别为默认值——说明和默认值来自代码本身，不用额外写。
追问：怎么让自己写的 @ConfigurationProperties 在 yml 里有自动补全？ 引入 spring-boot-configuration-processor 依赖（optional=true），它在编译期扫描 @ConfigurationProperties 类生成 spring-configuration-metadata.json，重新编译后 IDE 就能读取并对你的配置项补全、提示；给字段写 Javadoc 和默认值让提示更友好。
追问：怎么给某个配置项提供可选值（枚举）提示？ 用 additional-spring-configuration-metadata.json 的 hints——为某配置项声明 values 列表（每个 value 带 description），IDE 就会在写该配置时提示这些可选值；这类「可选值」自动生成识别不了，要手工补充。
追问：spring-boot-configuration-processor 为什么用 optional/provided 依赖？ 它是编译期注解处理器，只在编译时用来生成元数据，运行时完全不需要；用 optional=true（Maven）或 annotationProcessor（Gradle）声明，既能在编译期生效，又不会作为传递依赖打进最终 jar 或泄漏给依赖你的模块。

八、加强记忆

IDE 对 Spring Boot 配置的智能提示（补全、说明、类型/默认值、拼写校验、可选值）靠「配置元数据（Configuration Metadata）」——一个 JSON 文件 META-INF/spring-configuration-metadata.json，描述每个配置项的 name/type/description/defaultValue。Spring Boot 本体和每个 starter 都自带元数据（描述它们的配置项），IDE 扫描所有 jar 的元数据汇总提示。让自定义 @ConfigurationProperties 有 IDE 提示：引入 spring-boot-configuration-processor（编译期注解处理器，扫描配置类自动生成元数据，optional 依赖只编译期用、要重新编译）；说明来自字段 Javadoc、默认值来自字段初值、类型自动识别。可选值等自动识别不了的用 additional-spring-configuration-metadata.json（手工补充 hints）。关键认知：元数据只影响开发期 IDE 提示、与运行时是否生效完全无关——没有元数据时 IDE 会标黄「Unknown property」，但配置照样绑定生效（运行时不需要元数据）；排查「配置不生效」别被「IDE 标黄」误导（标黄 = 缺元数据加 processor；不生效 = 绑定问题如字段没 setter/POJO 没成 Bean/key 错）。一句话「IDE 配置提示靠配置元数据 JSON(name/type/description/defaultValue),starter 自带;自定义配置引入 spring-boot-configuration-processor 编译期生成元数据(说明来自 Javadoc/默认值来自初值),可选值用 additional 文件补充;元数据只影响 IDE 提示不影响运行时——缺元数据标黄但配置仍生效」。

简化版

详细版