1 / 4概念
Architecture
Spring 的容器把对象何时创建、依赖从哪来、何时销毁写成一张可读的定义表,Spring Boot 在这张表前加了一层条件评估,让空白工程也能直接启动。判断标准不是能否跑起来,而是能否指着一个 bean 说清它由哪条定义注册、为什么通过了条件评估。
1 概念
1.1 一句话定义
ApplicationContext 是 bean 定义的注册表加上生命周期的执行器。它读取配置类、扫描注解、评估自动配置条件,把定义变成实例,再按类型与限定符把依赖交给需要的一方。
1.2 它解决什么问题
- 装配成本:对象之间的
new与传参从业务代码里消失,接线集中到一处。 - 可替换性:按接口注册,多实现靠限定符区分,测试可以整体替换。
- 版本组合:starter 把彼此兼容的依赖打成一组,版本号不必手工对齐。
- 环境差异:同一份产物用 profile 与外部属性适配开发、预发与生产。
- 基础设施默认值:自动配置补齐连接池、序列化、内嵌容器等默认 bean。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 请求如何进入 controller、事务与连接池 | Web and Data |
| 认证、授权、Actuator 与探针 | Security and Operations |
| 注解的保留策略与泛型擦除 | Type System |
| 类加载顺序、元空间与启动期内存 | JVM Runtime |
| 事务的隔离级别与锁语义 | Transactions & Concurrency |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| IoC 容器 | 由外部创建并组装对象 | 不等于工厂方法 |
| bean definition | 对如何创建一个 bean 的描述 | 不是 bean 实例 |
ApplicationContext | 定义表、单例缓存与事件总线的组合 | 不只是一个 Map |
| 组件扫描 | 按包路径把注解类登记为定义 | 不扫描无注解的类 |
| 自动配置 | 按条件补充定义 | 不是零配置,用户定义优先 |
| starter | 依赖集合加自动配置入口 | 不是业务模块 |
BeanFactoryPostProcessor | 实例化前改写定义 | 改定义,不改实例 |
BeanPostProcessor | 初始化前后改写 bean | 代理在这里生成 |
| 作用域 | singleton、prototype 等实例策略 | prototype 不归容器销毁 |
| profile | 一组按环境激活的属性文档 | 不是部署单元 |
| 属性源 | 属性名到值的来源,按序覆盖 | 顺序决定谁胜出 |
2 机制
2.1 心智模型
启动分成两段不可混的工序:先把定义收齐并完成条件判断,再把定义变成实例。第一段可以任意增删,第二段一旦执行就只能按定义走,所以排查启动问题要先看定义表,再看实例化。
2.2 机制拆解
- 启动序列:
SpringApplication推断应用类型,准备Environment,创建上下文,执行BeanFactoryPostProcessor,注册BeanPostProcessor,预实例化单例,启动内嵌容器,最后调用Runner。 - 组件扫描:
@SpringBootApplication由@SpringBootConfiguration、@EnableAutoConfiguration、@ComponentScan组合而成,扫描起点是主类所在包。 - 配置类:
@Configuration(proxyBeanMethods = true)用 CGLIB 生成子类,@Bean方法互调返回同一实例;关掉代理后互调就是普通方法调用。 - 自动配置:
AutoConfigurationImportSelector读取 classpath 上的导入清单,逐条评估@Conditional;@ConditionalOnMissingBean让用户的定义胜出。 - 生命周期:实例化、属性填充、
Aware回调、初始化前置处理、@PostConstruct、InitializingBean、init-method、初始化后置处理、使用、销毁回调。 - 解析顺序:先按类型取候选,
@Qualifier缩小集合,@Primary在多候选中给出默认,参数名匹配作为兜底,仍不唯一就抛NoUniqueBeanDefinitionException。 - 循环依赖:字段或 setter 注入的单例可借提前暴露的引用完成,构造器注入无法完成,因为容器造不出半成品;Boot 2.6 起默认拒绝。
2.3 完整枚举
SpringApplication.run 的完整阶段:
| 阶段 | 关键动作 | 可扩展点 |
|---|---|---|
| 推断应用类型 | 由 classpath 判定 SERVLET、REACTIVE 或无 | WebApplicationType |
| 加载初始化器 | 读取 ApplicationContextInitializer | spring.factories |
| 注册监听器 | 读取 ApplicationListener | 同一份清单 |
| 准备环境 | 合并属性源、激活 profile、解析命令行 | EnvironmentPostProcessor |
| 创建上下文 | 按类型实例化 ApplicationContext | ApplicationContextFactory |
| 注册主类 | 把主类登记为 bean 定义 | 主类所在包即扫描根 |
| 刷新上下文 | 执行后置处理器、注册钩子、预实例化单例、启动容器 | BeanFactoryPostProcessor |
| 调用运行器 | 执行 ApplicationRunner 与 CommandLineRunner | 启动后任务 |
| 发布就绪事件 | 发布 ApplicationReadyEvent,注册关闭钩子 | 健康状态 |
自动配置可用的条件注解全集:
| 注解 | 判定依据 |
|---|---|
@ConditionalOnClass | 类路径上存在指定类 |
@ConditionalOnMissingClass | 类路径上不存在指定类 |
@ConditionalOnBean | 容器里已有指定 bean |
@ConditionalOnMissingBean | 容器里没有指定 bean |
@ConditionalOnSingleCandidate | 该类型只有一个候选,或有一个 @Primary |
@ConditionalOnProperty | 属性存在且值与条件匹配 |
@ConditionalOnResource | 资源路径存在 |
@ConditionalOnWebApplication | 应用类型为 Web |
@ConditionalOnNotWebApplication | 应用类型不是 Web |
@ConditionalOnExpression | SpEL 表达式为真 |
@ConditionalOnJava | JVM 版本落在区间内 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 冷启动 | 1–10 秒 | 与 bean 数、扫描范围、JIT 预热相关 |
| 自动配置候选 | 数百个 | 由 classpath 上的导入清单决定 |
| 单例 bean 数 | 数百到数千 | 基础设施 bean 占多数 |
| 属性源 | 十余个 | 命令行与环境变量优先 |
| 配置类增强 | 每个 @Bean 方法一次拦截 | 关掉代理可省下 |
| 扫描开销 | 与包内类数成正比 | 收窄根包最有效 |
3 实践
3.1 最小示例
@SpringBootApplication
class App {}
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(OrderProps.class)
class OrderConfig {
@Bean
OrderService orderService(OrderRepository repo, OrderProps props) {
return new OrderService(repo, props.timeout());
}
}
@ConfigurationProperties(prefix = "order")
record OrderProps(Duration timeout) {}
@Service
class Checkout {
private final OrderService orders;
Checkout(OrderService orders) { this.orders = orders; }
}
追踪:SpringApplication.run 推断为 SERVLET 应用后准备 Environment,application.yml 里的 order.timeout: 2s 进入属性源;@EnableConfigurationProperties 把 OrderProps 登记为定义,绑定用宽松绑定把 order.timeout 写进 timeout 组件;orderService 的方法参数由容器解析,OrderRepository 来自数据访问的自动配置。
单例预实例化阶段,Checkout 的构造器只有一个参数,容器不必看到 @Autowired 也能选中 OrderService。若此时没有 OrderRepository 的定义,失败发生在造 Checkout 之前,日志会给出从 Checkout 到 OrderService 再到 OrderRepository 的依赖链。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 启动应用 | SpringApplication.run(App.class, args) | 生产入口仍是 java -jar |
| 查看条件报告 | --debug | 列出命中与未命中的自动配置 |
| 激活 profile | --spring.profiles.active=prod | 也可用环境变量 |
| 覆盖单个属性 | --server.port=8081 | 命令行优先级最高 |
| 绑定一组配置 | @ConfigurationProperties(prefix = "order") | 类型安全,可加校验 |
| 让用户定义优先 | @ConditionalOnMissingBean | 自动配置的默认写法 |
| 定义第三方类型 | @Bean 方法 | 无法加注解的类只能这样注册 |
| 列出所有定义 | ApplicationContext#getBeanDefinitionNames | 排查重复定义 |
| 允许循环引用 | spring.main.allow-circular-references | 不建议开启 |
3.3 标准流程
- 主类放在根包,扫描范围与模块边界对齐。
- 依赖通过 starter 引入,版本交给 BOM。
- 依赖一律构造器注入,字段加
final。 - 业务配置收进
@ConfigurationProperties,必填项加校验注解。 - 数据源、安全链、序列化这类有外部约束的组件显式配置并写测试。
- 用
ApplicationContextRunner验证条件,用完整上下文测试验证装配。
3.4 与相邻技术的组合
- 构建工具:starter 的 BOM 决定版本,冲突在依赖树里解决,不在代码里绕。
- Type System:注解靠反射读取,
@ConfigurationProperties可生成元数据供 IDE 补全。 - JVM Runtime:启动期的类加载、CGLIB 生成与元空间占用都是启动成本。
- Web 与数据:MVC 与事务代理都是容器里注册的 bean,配置错误会以运行期异常出现。
- 测试:切片测试只加载相关定义,完整上下文测试才能暴露条件顺序问题。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 装配方式 | 自动配置 / 显式配置 | 启动可预测性与升级成本 |
| 扫描范围 | 根包 / 收窄到模块 | 启动时间与误注册 |
| 配置类代理 | proxyBeanMethods 开关 | CGLIB 开销与互调语义 |
| 实例化时机 | 预实例化 / 懒加载 | 启动时间与首次请求延迟 |
| 运行形态 | JVM jar / AOT 产物 / 原生镜像 | 启动速度与反射限制 |
3.6 决策规则
- 保留自动配置,只覆盖有安全含义或容量含义的部分。
- 构造器注入;字段注入只出现在测试夹具里。
@Configuration默认proxyBeanMethods = false,除非确实要互调。- 配置项集中到
@ConfigurationProperties,不要在业务类里散落@Value。 - 启动时间要作为 SLO 时,先测量再决定是否上 AOT 或原生镜像。
- 循环依赖必须改结构,不要打开
allow-circular-references。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| Spring Boot 自动配置 | 约定完整,生态最全 | 启动慢、内存高 | 通用后端 |
| 纯 Spring Framework | 装配完全可控 | 基础设施要自己搭 | 框架与库 |
| Quarkus | 启动快、内存低 | 扩展生态不同 | Serverless、容器密集 |
| Micronaut | 编译期装配 | 生态较小 | 低内存微服务 |
| 手写工厂加 Servlet | 无反射、可预测 | 一切自建 | 极小服务 |
| Boot 加 AOT 或原生镜像 | 启动到毫秒级 | 反射受限、构建慢 | 弹性伸缩 |
3.8 何时不该用
- 只有一个 HTTP 入口的函数式服务,轻量库更直接。
- 冷启动是硬指标且团队没有调优经验,先评估替代框架。
- 需要精确控制对象创建顺序与生命周期的场景。
- 运行环境无法接受反射与字节码生成。
- 团队不打算维护依赖升级,starter 的版本红利会变成负债。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
启动报 NoSuchBeanDefinitionException | 类被扫到范围之外,或没标 stereotype | 调整包结构或扫描配置 |
启动报 NoUniqueBeanDefinitionException | 同一类型有多个实现 | @Qualifier 指定或 @Primary |
| 构造器循环依赖启动失败 | 两个 bean 互相构造 | 拆出第三方组件 |
| 配置项始终为 null | 未注册 @ConfigurationProperties | 加 @EnableConfigurationProperties |
| profile 切换无效 | 激活方式与属性名不一致 | 用 --debug 看生效属性源 |
@Bean 互调拿到新实例 | 关掉了配置类代理 | 改为方法参数注入 |
| 启动越来越慢 | 扫描过宽、starter 过多 | 收窄根包,按需引入 |
| 上线后内存持续上涨 | 单例里放了无界缓存 | 加上限或换外部缓存 |
@PostConstruct 里调事务方法无效 | 代理在初始化之后才生成 | 移到 Runner 或事件里 |
| 原生镜像启动失败 | 反射未注册 | 补 AOT 提示或配置 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 字段注入 | 依赖隐藏、测试难替换 | 构造器注入 |
@Lazy 掩盖循环依赖 | 启动通过,直到运行期才失败 | 重新分层 |
配置类里 new 依赖 | 绕过容器,代理失效 | 用方法参数注入 |
| 全域扫描 | 启动慢、误注册 | 只扫根包 |
到处写 @Value | 无校验、无元数据 | @ConfigurationProperties |
| 生产打开循环引用 | 半初始化对象流入业务 | 改结构 |
4.3 可观测信号
启动耗时要能按阶段拆开:ApplicationStartup 配合 BufferingApplicationStartup 给出每个阶段的耗时,条件评估报告给出哪些自动配置生效,bean 定义数量给出装配规模,@PostConstruct 与 Runner 的耗时给出启动尾部成本。上下文刷新事件的时间戳可以区分定义阶段慢还是实例化阶段慢。
4.4 安全 / 性能 / 一致性边界
- 安全边界:配置绑定会把属性值写进对象,密钥应走环境变量或密钥管理,不要落在仓库里的
application.yml。 - 性能边界:反射、CGLIB 与类路径扫描是启动成本,稳态吞吐与之无关,拿启动耗时做容量规划会得出错误结论。
- 一致性边界:单例是进程内共享状态,任何可变字段都是并发写入点。
- 可演进边界:构造器签名就是 bean 之间的契约,改签名会同时影响测试、AOT 提示与代理生成。