核心概念速览

Starter 与 Auto-configuration 的关系

• 在 pom.xml 中添加 Spring Boot 各类 starter 依赖，会把相关库和自动配置模块（通常在 *-autoconfigure 或 Spring Boot 的 spring-boot-autoconfigure 中）一起带入项目。

• 注意：添加 starter 并不等于“必然创建所有 Bean”。自动配置类会在满足一组条件时（例如某个类在 classpath、某个 Bean 不存在、某个属性被设置）才注册相应的 Bean。

组件（Bean）与配置绑定 (@ConfigurationProperties)

• @ConfigurationProperties(prefix = "xxx") 用于将以该前缀的配置（如 application.yml）绑定到一个 POJO（属性类）。

• 重要：仅标注 @ConfigurationProperties 并不自动完成绑定——该类必须被注册为 Spring Bean 才会生效。注册方式常见有：

  • 自动配置内部通过 @EnableConfigurationProperties(XxxProperties.class) 已替你注册（Spring Boot 内置 *Properties 通常已注册）。

  • 在应用中使用 @ConfigurationPropertiesScan 扫描或将类标为 @Component（不推荐在库中直接用 @Component）。

  • 使用 @ConstructorBinding 可实现不可变绑定（需要构造器）。

• 属性类通常会提供默认值（字段初始值或常量），用户在 application.yml 中覆盖即可。Spring 支持 relaxed binding（例如 server.port、SERVER_PORT、server-port 等形式互映）。

典型示例与更正说明

ServerProperties 示例

你原文示例能表达意思，但推荐更标准、可运行的写法（包含 getter/setter 或构造器绑定）：

// 推荐写法（基于 setter 绑定）
@ConfigurationProperties(prefix = "server")
public class ServerProperties {
    private Integer port;
​
    public Integer getPort() { return port; }
    public void setPort(Integer port) { this.port = port; }
}

对应 application.yml：

server:
  port: 8888

说明：如果使用 Spring Boot 内置的 ServerProperties，通常该类已由自动配置注册；自定义时请确保已被 Spring 扫描或显式注册。

ThymeleafProperties 示例（建议写法）

带默认值的示例，建议同样提供访问方法：

@ConfigurationProperties(prefix = "spring.thymeleaf")
public class ThymeleafProperties {
    public static final String DEFAULT_PREFIX = "classpath:/templates/";
    private String prefix = DEFAULT_PREFIX;
​
    public String getPrefix() { return prefix; }
    public void setPrefix(String prefix) { this.prefix = prefix; }
}

对应 application.yml：

spring:
  thymeleaf:
    prefix: xxxxxx

自动配置的“按需加载” —— 条件注解一览

Spring Boot 的自动配置大量依赖条件注解（位于 org.springframework.boot.autoconfigure.condition 包），常见的有：

• @ConditionalOnClass：当指定类在 classpath 上存在时生效。

• @ConditionalOnMissingClass：当指定类不存在时生效。

• @ConditionalOnBean：当容器中存在指定 Bean 时生效。

• @ConditionalOnMissingBean：当容器中不存在指定 Bean 时生效（允许用户覆盖自动配置）。

• @ConditionalOnProperty：当存在某个配置属性（且可匹配特定值）时生效（常用来“开/关”功能）。

• @ConditionalOnResource：当指定的资源存在时生效（例如某个文件或配置模板）。

• @ConditionalOnWebApplication：仅在 Web 应用上下文中生效。

• @ConditionalOnNotWebApplication：仅在非 Web 应用上下文中生效。

示例（若 IoC 容器中存在 A Bean 则创建 B Bean）：

@Configuration
public class AppConfig {
​
    @Bean
    public A a(){
        return new A();
    }
​
    @ConditionalOnBean(A.class)
    @Bean
    public B b(){
        return new B();
    }
}

常见误区与补充说明

1. “添加依赖 = 自动注册所有 Bean”——这是误读

   • 自动配置会尝试配置常用组件，但会按注解条件决定是否生效（比如缺少某些第三方类、或用户已自定义 Bean 时，自动配置会跳过或退位）。

2. 属性绑定的生效依赖于注册

   • 内置 *Properties 多已注册；自定义属性类必须被扫描或显式注册，否则 application.yml 的值不会被绑定到该对象。

3. 配置来源与优先级

   • 除了 application.yml，属性还可来自命令行、环境变量、Profile-specific 文件等。Spring 有明确的优先级规则（命令行优先等），这可能影响最终生效值。

4. 覆盖与禁用自动配置

   • 覆盖自动配置：自己定义同类型 Bean（自动配置通常使用 @ConditionalOnMissingBean，因此用户自定义 Bean 会优先）。

   • 禁用自动配置：使用 spring.autoconfigure.exclude=...（在配置文件）或 @SpringBootApplication(exclude = ...)（在代码中）显式排除某些自动配置类。

调试与排查技巧（实用清单）

• 启动时加 --debug 或在 application.properties 中 debug=true：可在控制台看到自动配置决策（哪些配置被启用/跳过）。

• 使用 Spring Boot Actuator（启用 conditions 端点）来查看自动配置条件的具体情况（哪些 @Conditional 生效、哪些未生效及原因）。

• 检查 classpath：确认所需第三方库是否在 classpath 上（常见 @ConditionalOnClass 导致的问题）。

• 若属性未生效，确认属性类是否被注册（@ConfigurationPropertiesScan、@EnableConfigurationProperties 等）。

• 使用 spring.autoconfigure.exclude 临时排除自动配置，验证问题是否由某个自动配置引起。

总结（可替换为博客段落）

在 pom.xml 中添加 Spring Boot starter 依赖，通常会把相关库和自动配置模块一并带入项目。自动配置类会在满足特定条件（例如类在 classpath、某个 Bean 不存在或某个属性被设置）时为你注册需要的组件（Bean）。这些组件的默认行为和参数多数可在 @ConfigurationProperties 类或自动配置类中找到，用户可通过 application.yml、环境变量或命令行等方式覆盖默认值。需要注意的是：@ConfigurationProperties 标注的类必须作为 Spring Bean 注册后才能被绑定；自动配置本身是按需加载的，且允许用户通过自定义 Bean 或 spring.autoconfigure.exclude 来覆盖或禁用其行为。理解这些机制有助于快速诊断“为什么某个 Bean 未按预期创建”或“为什么某个配置未生效”的问题。