Spring Boot 集成分析

请关注微信公众号：阿呆-bot

1. 工程结构概览

Spring AI 通过 Spring Boot Starter 和 Auto Configuration 机制，实现了零配置的 AI 应用开发。开发者只需要添加依赖和配置属性，就能使用各种 AI 能力。

spring-ai-spring-boot-starters/  # Starter 模块
├── spring-ai-starter-model-openai/      # OpenAI Starter
├── spring-ai-starter-model-ollama/        # Ollama Starter
├── spring-ai-starter-vector-store-pgvector/  # PGVector Starter
└── ... (50+ 个 Starter)

auto-configurations/              # 自动配置模块
├── models/                      # 模型自动配置
│   ├── spring-ai-autoconfigure-model-openai/
│   ├── spring-ai-autoconfigure-model-ollama/
│   └── ...
├── vector-stores/               # 向量存储自动配置
│   ├── spring-ai-autoconfigure-vector-store-pgvector/
│   └── ...
├── common/                      # 通用自动配置
│   ├── spring-ai-autoconfigure-retry/
│   └── spring-ai-autoconfigure-model-tool/
└── mcp/                         # MCP 自动配置

2. 技术体系与模块关系

Spring Boot 集成采用 Starter + Auto Configuration 模式：

3. 关键场景示例代码

3.1 最简单的使用

只需要添加依赖和配置：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4

@RestController
public class ChatController {
    @Autowired
    private ChatModel chatModel;  // 自动注入
    
    @GetMapping("/chat")
    public String chat(String message) {
        return chatModel.call(message);
    }
}

3.2 配置属性

所有配置都通过 application.yml 或 application.properties：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com
      chat:
        options:
          model: gpt-4
          temperature: 0.7
          max-tokens: 1000
      embedding:
        options:
          model: text-embedding-3-small

3.3 条件装配

自动配置会根据条件决定是否启用：

@AutoConfiguration
@ConditionalOnClass(OpenAiChatModel.class)
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = true
)
public class OpenAiChatAutoConfiguration {
    // ...
}

3.4 自定义 Bean

可以覆盖自动配置的 Bean：

@Configuration
public class CustomConfig {
    @Bean
    @Primary
    public ChatModel customChatModel() {
        // 自定义实现
        return new CustomChatModel();
    }
}

4. 核心实现图

4.1 自动配置流程

5. 入口类与关键类关系

6. 关键实现逻辑分析

6.1 Starter 设计

Starter 是一个空的 Maven 模块，只包含依赖：

<dependencies>
    <!-- 核心实现 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai</artifactId>
    </dependency>
    
    <!-- 自动配置 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-model-openai</artifactId>
    </dependency>
    
    <!-- 通用自动配置 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-retry</artifactId>
    </dependency>
</dependencies>

Starter 的优势：

• 简化依赖管理：用户只需要添加一个依赖
• 版本统一：所有相关依赖版本统一管理
• 功能完整：包含所有必需的依赖

6.2 自动配置类实现

自动配置类使用条件注解：

@AutoConfiguration
@ConditionalOnClass(OpenAiChatModel.class)
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = true
)
@EnableConfigurationProperties(OpenAiChatProperties.class)
public class OpenAiChatAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    public OpenAiChatModel chatModel(
        OpenAiChatProperties properties,
        RetryTemplate retryTemplate,
        RestClient.Builder restClientBuilder
    ) {
        // 1. 构建 API 客户端
        OpenAiApi openAiApi = new OpenAiApi(
            properties.getBaseUrl(),
            properties.getApiKey(),
            restClientBuilder,
            retryTemplate
        );
        
        // 2. 创建 ChatModel
        return new OpenAiChatModel(
            openAiApi,
            properties.getChat().getOptions()
        );
    }
    
    @Bean
    @ConditionalOnMissingBean
    public OpenAiChatOptions chatOptions(OpenAiChatProperties properties) {
        return properties.getChat().getOptions();
    }
}

关键注解说明：

• @AutoConfiguration：标记为自动配置类
• @ConditionalOnClass：只有当类路径存在指定类时才启用
• @ConditionalOnProperty：只有当配置属性满足条件时才启用
• @ConditionalOnMissingBean：只有当容器中不存在指定 Bean 时才创建
• @EnableConfigurationProperties：启用配置属性绑定

6.3 配置属性绑定

配置属性类使用 @ConfigurationProperties：

@ConfigurationProperties(prefix = "spring.ai.openai")
public class OpenAiChatProperties {
    private String apiKey;
    private String baseUrl = "https://api.openai.com";
    
    private Chat chat = new Chat();
    
    public static class Chat {
        private boolean enabled = true;
        private OpenAiChatOptions options = new OpenAiChatOptions();
        
        // getters and setters
    }
    
    // getters and setters
}

配置属性支持：

• 类型安全：强类型绑定
• IDE 提示：通过 spring-boot-configuration-processor 生成元数据
• 验证：支持 JSR-303 验证注解

6.4 自动配置注册

自动配置类通过 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 注册：

org.springframework.ai.model.openai.autoconfigure.OpenAiChatAutoConfiguration
org.springframework.ai.model.openai.autoconfigure.OpenAiEmbeddingAutoConfiguration
org.springframework.ai.model.openai.autoconfigure.OpenAiImageAutoConfiguration

Spring Boot 3.x 使用 AutoConfiguration.imports 文件（替代了之前的 spring.factories）。

6.5 条件装配机制

Spring AI 使用多种条件注解：

// 1. 类路径条件
@ConditionalOnClass(OpenAiChatModel.class)

// 2. 配置属性条件
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat",
    name = "enabled",
    havingValue = "true"
)

// 3. Bean 存在条件
@ConditionalOnMissingBean(ChatModel.class)

// 4. 资源条件
@ConditionalOnResource(resources = "classpath:openai-config.properties")

这些条件让自动配置变得智能：

• 按需加载：只加载需要的配置
• 避免冲突：不会覆盖用户自定义的 Bean
• 灵活配置：可以通过配置属性控制行为

6.6 重试机制自动配置

重试是 AI 应用的重要能力：

@AutoConfiguration
@ConditionalOnClass(RetryUtils.class)
@EnableConfigurationProperties(SpringAiRetryProperties.class)
public class SpringAiRetryAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    public RetryTemplate retryTemplate(SpringAiRetryProperties properties) {
        return RetryTemplate.builder()
            .maxAttempts(properties.getMaxAttempts())
            .retryOn(TransientAiException.class)
            .retryOn(ResourceAccessException.class)
            .exponentialBackoff(
                properties.getBackoff().getInitialInterval(),
                properties.getBackoff().getMultiplier(),
                properties.getBackoff().getMaxInterval()
            )
            .build();
    }
}

配置示例：

spring:
  ai:
    retry:
      max-attempts: 3
      backoff:
        initial-interval: 1s
        multiplier: 2.0
        max-interval: 10s

6.7 工具调用自动配置

工具调用自动配置：

@AutoConfiguration
@ConditionalOnClass({ToolCallingManager.class, ChatModel.class})
public class ToolCallingAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    public ToolCallingManager toolCallingManager(
        ObservationRegistry observationRegistry,
        ToolCallbackResolver toolCallbackResolver
    ) {
        return new DefaultToolCallingManager(
            observationRegistry,
            toolCallbackResolver,
            new DefaultToolExecutionExceptionProcessor()
        );
    }
    
    @Bean
    @ConditionalOnMissingBean
    public ToolCallbackResolver toolCallbackResolver(ApplicationContext context) {
        return new DelegatingToolCallbackResolver(
            new SpringBeanToolCallbackResolver(context),
            new StaticToolCallbackResolver()
        );
    }
}

7. 配置属性管理

7.1 配置属性层次

Spring AI 的配置属性采用层次结构：

spring:
  ai:
    openai:                    # 提供商级别
      api-key: xxx
      chat:                     # 功能级别
        enabled: true
        options:                # 选项级别
          model: gpt-4
          temperature: 0.7

7.2 配置属性验证

支持 JSR-303 验证：

@ConfigurationProperties(prefix = "spring.ai.openai")
@Validated
public class OpenAiChatProperties {
    @NotBlank
    private String apiKey;
    
    @Min(0)
    @Max(2)
    private Double temperature;
}

7.3 配置属性提示

通过 additional-spring-configuration-metadata.json 提供 IDE 提示：

{
  "properties": [{
    "name": "spring.ai.openai.chat.options.model",
    "type": "java.lang.String",
    "description": "The model to use for chat completions.",
    "defaultValue": "gpt-3.5-turbo"
  }]
}

8. Bean 创建流程

8.1 Bean 创建顺序

自动配置的 Bean 创建顺序：

1. 配置属性 Bean：首先创建配置属性 Bean
2. 依赖 Bean：创建依赖的 Bean（如 RetryTemplate）
3. 核心 Bean：创建核心功能 Bean（如 ChatModel）
4. 增强 Bean：创建增强功能 Bean（如 Advisor）

8.2 Bean 覆盖机制

用户可以通过 @Primary 或 @ConditionalOnMissingBean 覆盖自动配置的 Bean：

@Configuration
public class CustomConfig {
    @Bean
    @Primary  // 优先使用
    public ChatModel customChatModel() {
        return new CustomChatModel();
    }
}

9. 外部依赖

9.1 Spring Boot

• spring-boot-starter：核心 Starter
• spring-boot-autoconfigure：自动配置支持
• spring-boot-configuration-processor：配置属性处理

9.2 Spring Framework

• spring-context：IoC 容器
• spring-beans：Bean 管理
• spring-core：核心功能

10. 工程总结

Spring AI 的 Spring Boot 集成设计有几个亮点：

零配置理念。通过 Starter 和 Auto Configuration，用户只需要添加依赖和配置属性，就能使用 AI 能力，无需编写任何配置代码。想用 OpenAI？加个依赖，配个 API Key，就能用了。

条件装配。使用 @ConditionalOn* 注解，让自动配置变得智能，只加载需要的配置，避免不必要的 Bean 创建

配置属性驱动。所有配置都通过 application.yml 或 application.properties，支持类型安全和 IDE 提示。写配置时有自动补全，写错了编译期就能发现。

可扩展性。用户可以轻松覆盖自动配置的 Bean，实现自定义行为。想自定义 ChatModel？加个 @Primary 注解就行。

模块化设计。每个功能都有独立的 Starter 和 Auto Configuration，用户可以选择性地添加需要的功能。想用向量存储？加个 spring-ai-starter-vector-store-pgvector 就行。

总的来说，Spring AI 的 Spring Boot 集成既简单又强大。简单的使用方式降低了学习成本，强大的自动配置机制让系统可以适应各种场景。这种设计让开发者可以快速构建 AI 应用，同时也能根据需求进行深度定制。