当前位置：首页 > news >正文

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

news 2026/5/31 1:13:29

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

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

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

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

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

源码入口：自动配置类

OpenAiAutoConfiguration

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

@AutoConfiguration@ConditionalOnClass(OpenAiApi.class)@EnableConfigurationProperties(OpenAiConnectionProperties.class)publicclassOpenAiAutoConfiguration{@Bean@ConditionalOnMissingBeanpublicOpenAiApiopenAiApi(OpenAiConnectionPropertiesconnectionProperties,OpenAiChatOptionschatOptions){returnnewOpenAiApi(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)publicclassOpenAiChatAutoConfiguration{@Bean@ConditionalOnMissingBeanpublicOpenAiChatModelopenAiChatModel(OpenAiApiopenAiApi,OpenAiChatOptionschatOptions,List<FunctionCallback>toolFunctions){returnnewOpenAiChatModel(openAiApi,chatOptions).withToolFunctions(toolFunctions);}@Bean@ConditionalOnMissingBeanpublicChatClient.BuilderchatClientBuilder(List<ChatModel>chatModels){returnChatClient.builder(chatModels.get(0));}}

配置属性绑定

属性类层次

@ConfigurationProperties(prefix="spring.ai.openai")publicclassOpenAiConnectionProperties{privateStringbaseUrl="https://api.openai.com";privateStringapiKey;privateStringapiVersion;privateOpenAiChatOptionschat=newOpenAiChatOptions();privateOpenAiEmbeddingOptionsembedding=newOpenAiEmbeddingOptions();}publicclassOpenAiChatOptionsimplementsChatOptions{privateStringmodel="gpt-4o";privateDoubletemperature;privateIntegermaxTokens;privateDoubletopP;privateList<String>stop;}

核心客户端：OpenAiApi

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

publicclassOpenAiApi{privatefinalRestClientrestClient;privatefinalOpenAiChatOptionschatOptions;publicOpenAiApi(StringbaseUrl,StringapiKey,OpenAiChatOptionschatOptions){this.restClient=RestClient.builder().baseUrl(baseUrl).defaultHeader("Authorization","Bearer "+apiKey).defaultHeader("Content-Type","application/json").build();this.chatOptions=chatOptions;}publicChatCompletionResultchatCompletion(ChatCompletionRequestrequest){returnrestClient.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 的条件注解来实现灵活的装配策略：

注解	用途	示例场景
@ConditionalOnClass	检查 Classpath 中是否存在某个类	OpenAiApi.class
@ConditionalOnMissingBean	仅当不存在自定义 Bean 时才创建	允许用户替换默认实现
@ConditionalOnProperty	检查配置属性	可开关的模块

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