服务端开发

Appearance

Spring Boot 自动配置 ​

概述 ​

Spring Boot 自动配置是一个强大的特性，它会根据你添加的 jar 依赖自动配置你的 Spring 应用程序。这个特性大大简化了 Spring 应用程序的开发和配置过程，让开发者能够快速构建功能完整的应用程序。

IMPORTANT

自动配置解决了传统 Spring 应用程序需要大量手动配置的问题，通过"约定优于配置"的原则，让开发者专注于业务逻辑而不是繁琐的配置。

什么是自动配置 ​

自动配置是 Spring Boot 的核心特性之一，它通过检测类路径上的依赖来自动配置 Spring 应用程序。例如：

  • 如果 HSQLDB 在你的类路径上，并且你没有手动配置任何数据库连接 bean，那么 Spring Boot 会自动配置一个内存数据库
  • 如果检测到 spring-boot-starter-web 依赖，会自动配置 Tomcat 和 Spring MVC
  • 如果检测到 spring-boot-starter-data-jpa 依赖，会自动配置 JPA 和数据源

启用自动配置 ​

要启用自动配置，你需要在你的 @Configuration 类上添加 @EnableAutoConfiguration 或 @SpringBootApplication 注解。

kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

// @SpringBootApplication 包含了 @EnableAutoConfiguration
// 这是推荐的方式，它还包含了 @Configuration 和 @ComponentScan
@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}
java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

TIP

建议只在主配置类上添加一个 @SpringBootApplication 或 @EnableAutoConfiguration 注解。通常我们推荐使用 @SpringBootApplication，因为它是一个组合注解，包含了常用的其他注解。

实际业务场景示例 ​

让我们通过一个实际的电商系统来演示自动配置的威力：

kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

/**
 * 电商系统主应用类
 * 使用 @SpringBootApplication 注解启用自动配置
 */
@SpringBootApplication
class ECommerceApplication

fun main(args: Array<String>) {
    runApplication<ECommerceApplication>(*args)
}
kotlin
import jakarta.persistence.*

/**
 * 产品实体类
 * 由于类路径中有 JPA 依赖，Spring Boot 会自动配置：
 * - 数据源 (DataSource)
 * - 实体管理器 (EntityManager)
 * - 事务管理器 (TransactionManager)
 * - JPA 存储库支持
 */
@Entity
@Table(name = "products")
data class Product(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0,

    @Column(nullable = false)
    val name: String,

    @Column(nullable = false)
    val price: Double,

    @Column
    val description: String? = null
)
kotlin
import org.springframework.web.bind.annotation.*

/**
 * 产品控制器
 * 由于类路径中有 Web 依赖，Spring Boot 会自动配置：
 * - 嵌入式 Tomcat 服务器
 * - Spring MVC 框架
 * - JSON 消息转换器
 * - 异常处理器
 */
@RestController
@RequestMapping("/api/products")
class ProductController(private val productService: ProductService) {

    @GetMapping
    fun getAllProducts(): List<Product> {
        return productService.findAll()
    }

    @PostMapping
    fun createProduct(@RequestBody product: Product): Product {
        return productService.save(product)
    }
}

逐步替换自动配置 ​

自动配置是非侵入式的，这意味着你可以在任何时候开始定义自己的配置来替换自动配置的特定部分。

场景：自定义数据源配置 ​

假设你的电商系统需要连接到生产环境的 MySQL 数据库，而不是使用默认的内存数据库：

kotlin
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.jdbc.DataSourceBuilder
import javax.sql.DataSource

/**
 * 自定义数据源配置
 * 一旦定义了自己的 DataSource bean，
 * Spring Boot 的默认嵌入式数据库支持就会自动退出
 */
@Configuration
class DatabaseConfig {

    /**
     * 自定义数据源配置
     * 这会替换 Spring Boot 的默认数据源自动配置
     */
    @Bean
    @ConfigurationProperties(prefix = "app.datasource")
    fun dataSource(): DataSource {
        return DataSourceBuilder.create()
            .driverClassName("com.mysql.cj.jdbc.Driver")
            .url("jdbc:mysql://localhost:3306/ecommerce")
            .username("ecommerce_user")
            .password("secure_password")
            .build()
    }
}
yaml
# 自定义数据源属性
app:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://prod-db:3306/ecommerce
    username: ${DB_USERNAME:ecommerce_user}
    password: ${DB_PASSWORD:secure_password}

# JPA 配置（仍然使用自动配置，但可以自定义属性）
spring:
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect

调试自动配置 ​

当你需要了解当前应用了哪些自动配置以及原因时，可以使用 --debug 开关启动应用程序：

bash
# 启动应用程序并显示自动配置报告
java -jar ecommerce-app.jar --debug

这会在控制台输出详细的条件报告，显示：

  • 哪些自动配置类被应用了
  • 哪些被跳过了
  • 跳过的原因（条件不满足）

TIP

使用调试模式可以帮助你理解 Spring Boot 的自动配置决策过程，这对于排查配置问题非常有用。

禁用特定的自动配置类 ​

在某些情况下，你可能不希望某些自动配置被应用。Spring Boot 提供了多种方式来禁用特定的自动配置类。

使用 exclude 属性 ​

kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
import org.springframework.boot.runApplication

/**
 * 禁用数据源自动配置
 * 适用场景：当你不需要数据库连接或者想要完全自定义数据源配置时
 */
@SpringBootApplication(exclude = [DataSourceAutoConfiguration::class])
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}
java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

实际业务场景：微服务架构 ​

在微服务架构中，不同的服务可能需要不同的自动配置。例如：

kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration
import org.springframework.boot.runApplication

/**
 * 认证服务应用
 * 这是一个纯的认证服务，不需要完整的 Web MVC 功能
 * 只需要 REST API 能力
 */
@SpringBootApplication(exclude = [
    WebMvcAutoConfiguration::class // 禁用完整的 Web MVC 自动配置
])
class AuthServiceApplication

fun main(args: Array<String>) {
    runApplication<AuthServiceApplication>(*args)
}
kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
import org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration
import org.springframework.boot.runApplication

/**
 * 通知服务应用
 * 这个服务只负责发送邮件和短信通知，不需要数据库
 */
@SpringBootApplication(exclude = [
    DataSourceAutoConfiguration::class,      // 禁用数据源自动配置
    HibernateJpaAutoConfiguration::class     // 禁用 JPA 自动配置
])
class NotificationServiceApplication

fun main(args: Array<String>) {
    runApplication<NotificationServiceApplication>(*args)
}

使用 excludeName 属性 ​

如果要排除的类不在类路径上，可以使用 excludeName 属性指定完全限定名：

kotlin
@SpringBootApplication(
    excludeName = [
        "org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration",
        "org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration"
    ]
)
class MyApplication

使用配置属性 ​

你也可以通过配置属性来控制要排除的自动配置类列表：

yaml
# application.yml
spring:
  autoconfigure:
    exclude:
      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
      - org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration

TIP

你可以同时在注解级别和配置属性级别定义排除项，两者会合并生效。

WARNING

虽然自动配置类是 public 的，但只有类名被视为公共 API，可以用于禁用自动配置。不建议直接使用这些类的内部内容（如嵌套配置类或 bean 方法）。

自动配置包 ​

自动配置包是各种自动配置功能在扫描实体和 Spring Data 存储库等内容时默认查找的包。

默认包确定 ​

@EnableAutoConfiguration 注解（直接使用或通过 @SpringBootApplication 存在）决定了默认的自动配置包。

kotlin
package com.ecommerce.main

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

/**
 * 主应用类位于 com.ecommerce.main 包
 * 这将成为默认的自动配置包
 * Spring Boot 会在这个包及其子包中扫描：
 * - JPA 实体 (@Entity)
 * - Spring Data 存储库接口
 * - 组件 (@Component, @Service, @Repository, @Controller)
 */
@SpringBootApplication
class ECommerceApplication

fun main(args: Array<String>) {
    runApplication<ECommerceApplication>(*args)
}
kotlin
package com.ecommerce.main.entity

import jakarta.persistence.*

/**
 * 这个实体会被自动扫描到
 * 因为它位于主应用类的子包中
 */
@Entity
data class User(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0,
    val email: String,
    val name: String
)

配置额外的扫描包 ​

使用 @AutoConfigurationPackage 注解可以配置额外的包：

kotlin
package com.ecommerce.main.config

import org.springframework.boot.autoconfigure.AutoConfigurationPackage
import org.springframework.context.annotation.Configuration

/**
 * 配置额外的自动配置包
 * 这对于扫描不在主应用包层次结构中的实体和存储库很有用
 */
@Configuration
@AutoConfigurationPackage(basePackages = [
    "com.ecommerce.shared.entities",  // 共享实体包
    "com.ecommerce.external.models"   // 外部模型包
])
class PackageConfiguration
kotlin
package com.ecommerce.main.config

import org.springframework.boot.autoconfigure.AutoConfigurationPackage
import org.springframework.context.annotation.Configuration
import com.ecommerce.shared.entities.SharedEntity
import com.ecommerce.external.models.ExternalModel

/**
 * 使用 basePackageClasses 更加类型安全
 * 通过指定类来确定包，避免字符串错误
 */
@Configuration
@AutoConfigurationPackage(basePackageClasses = [
    SharedEntity::class,    // 将扫描 SharedEntity 所在的包
    ExternalModel::class    // 将扫描 ExternalModel 所在的包
])
class PackageConfiguration

实际应用场景：多模块项目 ​

在多模块项目中，你可能需要扫描来自不同模块的实体和存储库：

kotlin
package com.ecommerce.main.config

import org.springframework.boot.autoconfigure.AutoConfigurationPackage
import org.springframework.boot.autoconfigure.domain.EntityScan
import org.springframework.context.annotation.Configuration
import org.springframework.data.jpa.repository.config.EnableJpaRepositories

/**
 * 多模块项目的配置
 * 确保所有模块中的实体和存储库都能被正确扫描
 */
@Configuration
@EntityScan(basePackages = [
    "com.ecommerce.user.entity",
    "com.ecommerce.product.entity",
    "com.ecommerce.order.entity",
    "com.ecommerce.shared.entity"
])
@EnableJpaRepositories(basePackages = [
    "com.ecommerce.user.repository",
    "com.ecommerce.product.repository",
    "com.ecommerce.order.repository"
])
@AutoConfigurationPackage(basePackages = [
    "com.ecommerce.user",
    "com.ecommerce.product",
    "com.ecommerce.order",
    "com.ecommerce.shared"
])
class MultiModuleConfiguration

自动配置的工作原理 ​

Spring Boot 的自动配置基于条件注解来工作：

NOTE

理解自动配置的条件机制有助于你更好地自定义和调试 Spring Boot 应用程序。当自动配置不按预期工作时，通常是因为某些条件没有满足。

最佳实践 ​

1. 合理使用排除 ​

WARNING

不要盲目排除自动配置类，除非你确实不需要它们或者要完全自定义替换。

2. 分层配置 ​

kotlin
/**
 * 推荐的配置方式：分层处理
 * - 保留大部分自动配置
 * - 只自定义必要的部分
 * - 使用配置属性进行调整
 */
@Configuration
class CustomConfiguration {

    // 自定义特定的 Bean，但保留其他自动配置
    @Bean
    @Primary
    fun customObjectMapper(): ObjectMapper {
        return ObjectMapper().apply {
            configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
            registerModule(JavaTimeModule())
        }
    }
}

3. 使用配置属性 ​

yaml
# 推荐：通过配置属性调整自动配置的行为
spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        format_sql: true
        use_sql_comments: true

总结 ​

Spring Boot 的自动配置是一个强大而灵活的特性，它通过智能的条件检查和约定来简化应用程序的配置。关键要点：

  1. 自动配置基于类路径依赖：Spring Boot 会根据检测到的依赖自动配置相应的功能
  2. 非侵入式：你可以随时通过自定义配置来覆盖自动配置
  3. 条件驱动：所有自动配置都基于特定条件，如类的存在、Bean 的缺失等
  4. 可调试：使用 --debug 开关可以查看详细的自动配置报告
  5. 灵活排除：提供多种方式来排除不需要的自动配置

TIP

掌握自动配置的原理和使用方法，能够让你更高效地开发 Spring Boot 应用程序，既享受自动配置带来的便利，又能在需要时进行精确的自定义。