Skip to content

01-spring-boot-essentials.md

Latest commit

 

History

History
187 lines (144 loc) · 7.89 KB

01-spring-boot-essentials.md

File metadata and controls

187 lines (144 loc) · 7.89 KB
Raw

Spring Boot 核心速查

文档简介: Spring Boot 4.x 核心条目速查：自动配置机制、核心注解、REST 与配置绑定、Actuator 端点，以及从 Boot 2 / Boot 3 迁移的关键变化

目标读者: 有旧版 Spring/Boot 经验、需要对照现代化（Boot 4.x + Jakarta EE 11 + Java 21/25）的开发者

前置知识: IoC/依赖注入概念；Java 基础见 现代 Java 特性

文档信息（用途、难度与维护记录）

📚 文档元数据

属性 内容
模块 08-java-revisited
象限 字典
难度 ⭐⭐
标签 #SpringBoot #自动配置 #注解 #Actuator
更新日期 2026年9月

🚀 Boot 3.x 关键变化（对照旧版）

变化点 Boot 2.x Boot 3.x
命名空间 javax.* jakarta.*（Jakarta EE 9+）
Java 基线 Java 8+ Java 17+（推荐 21/25）
自动配置注册 META-INF/spring.factories META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
Spring Framework 5.x 6.x（原生 AOT、虚拟线程友好）
可观测性 Micrometer 1.x Micrometer 1.x + Observation API 统一指标/追踪

🚀 Boot 3.x → 4.x 关键变化（2025-11 发布 4.0，基于 Spring Framework 7）

变化点 Boot 3.x Boot 4.x
基础框架 Spring Framework 6.x Spring Framework 7.x（Jakarta EE 11：Servlet 6.1 / JPA 3.2 / Validation 3.1）
JSON 库 Jackson 2（com.fasterxml.jackson） Jackson 3（tools.jackson；注解仍是 com.fasterxml.jackson.annotation），自动配置 JsonMapper
Web MVC starter spring-boot-starter-web spring-boot-starter-webmvc
AOP starter spring-boot-starter-aop spring-boot-starter-aspectj
错误处理属性 server.error.* spring.web.error.*（如 spring.web.error.include-message、spring.web.error.whitelabel.enabled）
内嵌服务器 Tomcat 10 / Jetty 12 Tomcat 11 / Jetty 12.1（Servlet 6.1；Undertow 支持移除）
Spring Security 6.x 7.0.x
空安全 JSR 305 JSpecify（框架 API 全面标注）
测试栈 JUnit 5 + Testcontainers 1.x JUnit 6（Jupiter）+ Testcontainers 2.0（artifact 改名 testcontainers-*）
新能力 — API 版本化、HTTP Service Clients、starter 全面模块化（Flyway/Liquibase 需独立 starter）

属性批量迁移用官方 spring-boot-properties-migrator（runtime 依赖，迁移完移除）；逐条对照见 Boot 3→4 迁移速查。

🏗️ 启动与自动配置

定义: @SpringBootApplication 是三合一注解，自动配置按"条件满足才装配"的原则工作。

@SpringBootApplication   // = @Configuration + @EnableAutoConfiguration + @ComponentScan
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

自动配置机制链路：

  1. @EnableAutoConfiguration 触发 AutoConfiguration.imports 中列出的自动配置类加载
  2. 每个配置类由 @ConditionalOnClass/@ConditionalOnMissingBean/@ConditionalOnProperty 等条件注解把关
  3. 用户自定义 Bean 优先（@ConditionalOnMissingBean 语义），可用 spring.autoconfigure.exclude 排除
@AutoConfiguration
@ConditionalOnClass(DataSource.class)
public class MyAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean          // 用户没配才上
    public MyService myService(MyProps props) { return new MyService(props); }
}

🏷️ 核心注解速查

分类 注解 说明
声明 Bean @Component @Service @Repository @Controller 组件扫描注册（语义化别名）
配置类 @Configuration + @Bean Java 配置；proxyBeanMethods=false 提升启动速度
注入 @Autowired / 构造器注入（推荐） 单构造器可省略注解
条件 @ConditionalOnClass @ConditionalOnMissingBean @ConditionalOnProperty 自动配置/条件装配
环境 @Profile("prod") @Value("${key}") 环境隔离 / 简单取值
配置绑定 @ConfigurationProperties(prefix = "app") 批量绑定，类型安全
生命周期 @PostConstruct @PreDestroy 初始化/销毁回调

⚙️ 配置绑定（record 原生支持）

@ConfigurationProperties(prefix = "app.mail")
public record MailProps(String host, int port, boolean sslEnabled) {}
// application.yml: app.mail.host=smtp.example.com
@SpringBootApplication
@ConfigurationPropertiesScan        // 扫描并注册配置属性 Bean
public class App {}

陷阱: 缺少 @ConfigurationPropertiesScan（或 @EnableConfigurationProperties）时绑定类不会注册为 Bean。

🌐 REST 注解速查

@RestController
@RequestMapping("/api/books")
public class BookController {

    @GetMapping("/{isbn}")                          // GET，路径变量
    public Book get(@PathVariable String isbn) { ... }

    @PostMapping                                    // POST，JSON 请求体
    @ResponseStatus(HttpStatus.CREATED)
    public Book create(@RequestBody @Valid BookRequest req) { ... }

    @GetMapping
    public Page<Book> list(@RequestParam(defaultValue = "0") int page) { ... }

    @PutMapping("/{isbn}")
    public Book update(@PathVariable String isbn, @RequestBody BookRequest req) { ... }

    @DeleteMapping("/{isbn}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable String isbn) { ... }
}

异常集中处理：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BookNotFoundException.class)
    public ProblemDetail handle(BookNotFoundException e) {
        var pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
        return pd;                                  // RFC 7807 问题详情（Boot 3 默认支持）
    }
}

🩺 Actuator

定义: 生产级运维端点集合，配合 Micrometer 暴露健康、指标与追踪数据。

端点 用途
/actuator/health 健康检查（含 DB/Redis 等指示器）；show-details 可看详情
/actuator/info 构建信息（需配置 info.* 属性）
/actuator/metrics JVM/HTTP/自定义指标
/actuator/prometheus Prometheus 抓取格式（需引入 micrometer-registry-prometheus）
/actuator/env 环境属性（默认脱敏） 
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus    # 默认只暴露 health,info
  endpoint:
    health:
      show-details: always

陷阱: include: "*" 全暴露有安全风险——生产按需最小化并配合认证。

✅ 最佳实践 / ❌ 陷阱清单

构造器注入让必要依赖在创建时明确，成组配置用专门类型便于校验；少量简单值也可按场景使用其他配置方式。虚拟线程属于需要验证的运行选择，先确认负载以等待为主，并限制下游并发。

迁移到 Jakarta 的是相关企业 API 命名空间，并非所有 javax 都要替换，例如 JDK 自带的一些 javax 包仍然存在。事务与配置对象是否被容器管理要检查真实调用路径；用失败用例确认回滚和缺配置时的启动行为。

🔗 相关文档

阅读导航

本模块理解地图 · 完整目录与版本 · 通用术语