Spring AI 源码解析（一）：自动配置与核心启动流程

经过前面四篇文章的学习，我们已经能够熟练使用 Spring AI 进行开发。但从今天开始，我们将深入源码层面，探究 Spring AI 背后的实现原理。本文作为源码解析系列的第一篇，将重点分析 Spring AI 的自动配置机制和核心启动流程。

概述：从 Starter 到 Bean 的完整链路

当我们在项目中引入 spring-ai-openai-spring-boot-starter 时，Spring Boot 会在启动时自动完成以下工作：

1. 加载自动配置类：通过 spring.factories 或 AutoConfiguration.imports 发现配置类
2. 条件装配：根据 Classpath 中的依赖和配置属性决定是否创建 Bean
3. 创建核心客户端：初始化 OpenAiApi HTTP 客户端
4. 创建 Model Bean：构建 OpenAiChatModel、OpenAiEmbeddingModel 等核心 Bean
5. 注入高阶 API：构建 ChatClient.Builder 供开发者使用

源码入口：自动配置类

OpenAiAutoConfiguration

所有的自动配置都始于 OpenAiAutoConfiguration 类，位于 spring-ai-openai 模块：

@AutoConfiguration
@ConditionalOnClass(OpenAiApi.class)
@EnableConfigurationProperties(OpenAiConnectionProperties.class)
public class OpenAiAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public OpenAiApi openAiApi(
            OpenAiConnectionProperties connectionProperties,
            OpenAiChatOptions chatOptions) {
        return new OpenAiApi(
            connectionProperties.getBaseUrl(),
            connectionProperties.getApiKey(),
            connectionProperties.getApiVersion(),
            chatOptions);
    }
}

关键点解析：

• @AutoConfiguration：标记为自动配置类
• @ConditionalOnClass(OpenAiApi.class)：仅当 OpenAiApi 类在 Classpath 中存在时才生效
• @EnableConfigurationProperties：绑定以 spring.ai.openai 为前缀的配置属性

ChatModel 的自动装配

@Configuration
@ConditionalOnBean(OpenAiApi.class)
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat", name = "enabled",
    havingValue = "true", matchIfMissing = true)
public class OpenAiChatAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public OpenAiChatModel openAiChatModel(
            OpenAiApi openAiApi,
            OpenAiChatOptions chatOptions,
            List<FunctionCallback> toolFunctions) {
        return new OpenAiChatModel(openAiApi, chatOptions)
            .withToolFunctions(toolFunctions);
    }

    @Bean
    @ConditionalOnMissingBean
    public ChatClient.Builder chatClientBuilder(
            List<ChatModel> chatModels) {
        return ChatClient.builder(chatModels.get(0));
    }
}

配置属性绑定

属性类层次

@ConfigurationProperties(prefix = "spring.ai.openai")
public class OpenAiConnectionProperties {

    private String baseUrl = "https://api.openai.com";
    private String apiKey;
    private String apiVersion;
    private OpenAiChatOptions chat = new OpenAiChatOptions();
    private OpenAiEmbeddingOptions embedding = new OpenAiEmbeddingOptions();
}

public class OpenAiChatOptions implements ChatOptions {

    private String model = "gpt-4o";
    private Double temperature;
    private Integer maxTokens;
    private Double topP;
    private List<String> stop;
}

核心客户端：OpenAiApi

OpenAiApi 是 OpenAI HTTP 客户端的核心封装，它使用了 Spring 的 RestClient：

public class OpenAiApi {

    private final RestClient restClient;
    private final OpenAiChatOptions chatOptions;

    public OpenAiApi(String baseUrl, String apiKey, OpenAiChatOptions chatOptions) {
        this.restClient = RestClient.builder()
            .baseUrl(baseUrl)
            .defaultHeader("Authorization", "Bearer " + apiKey)
            .defaultHeader("Content-Type", "application/json")
            .build();
        this.chatOptions = chatOptions;
    }

    public ChatCompletionResult chatCompletion(ChatCompletionRequest request) {
        return restClient.post()
            .uri("/v1/chat/completions")
            .body(request)
            .retrieve()
            .body(ChatCompletionResult.class);
    }
}

启动流程

Spring Boot 启动
    |
    v
加载 AutoConfiguration.imports
    |
    +--- OpenAiAutoConfiguration
    |       |
    |       v
    |   创建 OpenAiApi Bean
    |
    +--- OpenAiChatAutoConfiguration
    |       |
    |       +--- 创建 OpenAiChatModel Bean
    |       +--- 创建 ChatClient.Builder Bean
    |
    +--- OpenAiEmbeddingAutoConfiguration
    |       |
    |       v
    |   创建 OpenAiEmbeddingModel Bean
    |
    v
应用启动完成，所有 AI Bean 就绪

条件装配的巧妙之处

Spring AI 大量使用了 Spring Boot 的条件注解来实现灵活的装配策略：

关键设计原则：Spring AI 始终优先使用用户自定义的 Bean，只有当用户未提供时才使用默认实现，这符合 Spring 生态的一贯理念。

总结：本文要点

• Spring AI 的自动配置入口是 OpenAiAutoConfiguration
• 条件装配 通过 @ConditionalOnClass、@ConditionalOnMissingBean 等注解实现灵活控制
• OpenAiApi 是对 OpenAI REST API 的 HTTP 客户端封装，使用 Spring 6 的 RestClient
• 配置属性绑定通过 @ConfigurationProperties 实现，前缀为 spring.ai.openai
• 自动配置的最终产物是 ChatModel、EmbeddingModel 等核心 Bean 以及 ChatClient.Builder