Spring Boot：自动配置背后仍是一棵可检查的对象图

1. 现实问题：启动类只有一行，问题却发生在很多配置层

@SpringBootApplication 看起来像一个按钮：一跑就有 Web 服务、JSON、数据库和健康检查。但自动配置是根据 classpath、属性和条件创建 Bean 的过程；缺少驱动、profile 写错、端口被占用或条件未满足时，问题并不在启动类那一行。

Boot 的价值是约定和默认值，不是隐藏机制。学习时要保留三个入口：启动日志告诉你加载了什么，配置属性告诉你输入是什么，Actuator/测试告诉你运行状态是否符合预期。

2. 最小可运行示例：入口、配置属性和健康端点

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class BlogApplication {
    public static void main(String[] args) {
        SpringApplication.run(BlogApplication.class, args);
    }
}

@ConfigurationProperties(prefix = "blog.storage")
record StorageProperties(String root, long maxBytes) {}

对应配置可以是：

server:
  port: ${PORT:8080}
blog:
  storage:
    root: ${BLOG_STORAGE_ROOT:./data}
    max-bytes: 5242880

Boot 4.1 的具体自动配置以官方当前参考文档和项目依赖为准；本路线代码基线为 Java 21。Actuator 端点应只暴露必要范围并单独保护，不要把 env、beans 等敏感端点直接公开到公网。

3. 调用链与对象变化

main 创建 SpringApplication，准备环境、读取命令行/配置文件/环境变量，构建 ApplicationContext。@SpringBootApplication 组合组件扫描、自动配置和配置类能力；条件评估器根据类路径和属性决定哪些配置类生效，Bean 工厂再创建对象和代理。

配置文本先是字符串，Binder 按 prefix 找到属性，转换为 long 和 record 组件，StorageProperties 作为 Bean 注入 Service。HTTP 请求进入嵌入式服务器，健康端点读取应用和依赖状态并返回响应；端口、profile 和 DataSource 配置都可以在启动日志和测试中验证。

4. 为什么这样设计

自动配置减少重复样板，但条件装配允许项目覆盖默认 Bean。Starter 通过依赖集合表达能力边界，BOM 管理相互兼容的版本。配置外置让同一镜像在本地、CI、服务器使用不同资源路径，但敏感值应进入密钥系统或环境，而不是提交到 Git。

配置属性使用类型化 record 比散落 @Value 更容易校验、文档化和测试。配置错误要早失败，例如 root 为空、maxBytes 小于 0；默认值要说明是否安全。Actuator 是观测入口，不是业务授权入口，健康探针还要区分 liveness 与 readiness 的含义。

5. 项目落点：启动证据和运行证据分开

博客系统至少验证：java --version 为 21、Boot 4.1 依赖解析成功、上下文启动、端口监听、数据库连接和 /actuator/health 状态。生产部署把配置摘要（不含秘密）、镜像标签、commit SHA 和启动日志保留。应用启动成功不等于业务接口和数据库流程已验证。

练习：增加 @ConfigurationProperties 校验，写启动测试覆盖缺少 BLOG_STORAGE_ROOT；切换 test profile 使用临时目录，启动后请求健康端点。再故意引入缺少驱动或错误端口，记录失败日志中第一处有用证据。

6. 易错排查

• Bean 没有自动配置：看条件报告、依赖是否在 classpath、配置 key 是否准确。
• 配置读到 null：检查 prefix、命名转换、profile、环境变量优先级和启动工作目录。
• /actuator/health 200 但业务不可用：健康组和依赖检查范围不完整，补充真实关键依赖测试。
• 本地成功部署失败：比较 JDK、容器环境、配置来源、端口监听地址和文件权限。

7. 一页复习

Boot 启动链是 SpringApplication → Environment → 条件自动配置 → Bean 图 → 嵌入式服务器/运行端点。默认值提高速度，类型化配置和条件报告保留可解释性。JDK 21 是课程基线，Boot 4.1 API 以当前官方参考为准；上线证据必须覆盖启动、依赖和真实接口。

配置绑定的输入是 property source 中的字符串，Binder 按 prefix 匹配 key，转换器生成 StorageProperties Bean；@ConfigurationPropertiesScan 或显式启用决定它能否进入容器。只写 @ConfigurationProperties 而没有注册方式，record 不会自动成为可注入 Bean，这类错误应在上下文启动测试中尽早暴露。配置对象创建成功也不代表目录存在、权限足够或数据库可用。

自动配置可以按条件拆解：classpath 有 Web 依赖才装 MVC，存在 DataSource 配置才尝试数据库 Bean，用户自己提供 Bean 时默认配置可能退让。条件报告、启动日志和 /actuator/health 分别说明“为何装配”“当前启动怎样”“依赖是否可用”。项目文件可在 config/StorageProperties、config/StorageConfig 和 application.yml 中保持一一对应，不要把 key 散落在字符串常量里。

排错时 Bean 缺失查扫描/启用注解、包路径和 profile；绑定失败查命名、类型和环境变量优先级；启动成功但上传失败查目录权限和容器卷；健康 200 但数据库查询失败查 health 组是否真的包含 DataSource。JDK 21、Boot 4.1、镜像 JRE 和 CI release 要同时记录，避免只看本机版本。

练习是为 StorageProperties 增加校验和启动测试：缺 root、负 maxBytes、正确配置各一条；启动后访问 health，再临时改端口和目录权限观察失败日志。把条件报告、测试数、端口监听和健康响应保存为一次可复现的启动证据。

Boot 启动时的输入包括 classpath、环境变量、配置文件、命令行参数和应用主类，输出包括 Environment、BeanDefinition、ApplicationContext、嵌入式服务器和运行端点。@SpringBootApplication 负责扫描和自动配置，但 @ConfigurationProperties 只是元数据标记，必须通过 @ConfigurationPropertiesScan 或 @EnableConfigurationProperties 注册；否则注入 StorageProperties 会在上下文创建时失败。

自动配置的判断应能回放：依赖存在、条件满足、用户没有覆盖 Bean，配置值通过 Binder 绑定，Bean 初始化成功，健康检查读取真实依赖。Boot 4.1 的当前 API、Spring Framework 7 的 Web 能力和项目 BOM 共同决定可用类型，文章示例以 Java 21 为运行基线，不用尚未验证的 JDK 25 API。升级时应把 release、镜像和 CI 一起更新。

项目文件可把启动类放根包，配置属性放 config/properties，数据源/存储配置放 config，业务 Bean 放 feature 包。application.yml 只保存非秘密默认和环境占位，生产值来自环境/密钥系统；Actuator 的端点暴露列表和 Security 规则也应进入配置审查。启动日志保存 profile、端口和关键依赖状态，但不打印秘密。

排错时应用不启动查第一处条件/Bean/端口异常，属性为空查 prefix、命名转换、profile 和优先级，健康不准确查 health group 与依赖检查，容器启动后读写失败查工作目录/卷/权限。看到 NoSuchBeanDefinition 不要直接加 @Component，先确认它本应由扫描、配置属性扫描还是 @Bean 注册。

练习是写四条启动测试：正确配置、缺 root、负 maxBytes、缺数据库驱动；启动应用请求 health，保存返回和日志；再把配置放进 Docker 环境变量，验证本地与容器对象图一致。将条件报告、Java 版本、Boot 依赖和端口监听作为一次可复制的启动记录。

验证清单：用正确 root、缺 root、负 maxBytes、缺数据库驱动四套配置启动应用，分别保存 Binder 结果、Bean 创建、端口、health 和第一条失败原因；正确配置必须能注入 StorageProperties，缺少 @ConfigurationPropertiesScan 或显式 @EnableConfigurationProperties 时测试应明确失败，而不是把属性 record 当成普通类自动发现。再用 Docker 环境变量覆盖本地默认值，比较两次 Environment 与对象图，确认没有把秘密写进日志。

把 Boot 的最小运行证据固定成一组步骤：清理旧产物，使用 Java 21 和项目 BOM 构建，启动后等待端口，访问 health 和一个真实业务端点，停止进程并检查资源关闭。条件报告说明为什么装配，启动日志说明何时完成，health 说明依赖是否可用；三者不能互相替代。若 health 为 200 但业务查询失败，加入真实 DataSource 检查或独立探活，不要只改状态码。

进阶附录：AOT、分层 JAR 与配置优先级

生产镜像可以使用分层 JAR 提高缓存命中，AOT 能提前处理部分运行时工作，但要重新验证反射、代理和资源扫描。配置优先级要在项目中写清，命令行、环境变量、配置文件和 profile 的覆盖关系不能靠记忆；敏感配置永不写进启动日志。