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

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模块AutoConfigurationConditionalOnClass(OpenAiApi.class)EnableConfigurationProperties(OpenAiConnectionProperties.class)publicclassOpenAiAutoConfiguration{BeanConditionalOnMissingBeanpublicOpenAiApiopenAiApi(OpenAiConnectionPropertiesconnectionProperties,OpenAiChatOptionschatOptions){returnnewOpenAiApi(connectionProperties.getBaseUrl(),connectionProperties.getApiKey(),connectionProperties.getApiVersion(),chatOptions);}}关键点解析AutoConfiguration标记为自动配置类ConditionalOnClass(OpenAiApi.class)仅当 OpenAiApi 类在 Classpath 中存在时才生效EnableConfigurationProperties绑定以spring.ai.openai为前缀的配置属性ChatModel 的自动装配ConfigurationConditionalOnBean(OpenAiApi.class)ConditionalOnProperty(prefixspring.ai.openai.chat,nameenabled,havingValuetrue,matchIfMissingtrue)publicclassOpenAiChatAutoConfiguration{BeanConditionalOnMissingBeanpublicOpenAiChatModelopenAiChatModel(OpenAiApiopenAiApi,OpenAiChatOptionschatOptions,ListFunctionCallbacktoolFunctions){returnnewOpenAiChatModel(openAiApi,chatOptions).withToolFunctions(toolFunctions);}BeanConditionalOnMissingBeanpublicChatClient.BuilderchatClientBuilder(ListChatModelchatModels){returnChatClient.builder(chatModels.get(0));}}配置属性绑定属性类层次ConfigurationProperties(prefixspring.ai.openai)publicclassOpenAiConnectionProperties{privateStringbaseUrlhttps://api.openai.com;privateStringapiKey;privateStringapiVersion;privateOpenAiChatOptionschatnewOpenAiChatOptions();privateOpenAiEmbeddingOptionsembeddingnewOpenAiEmbeddingOptions();}publicclassOpenAiChatOptionsimplementsChatOptions{privateStringmodelgpt-4o;privateDoubletemperature;privateIntegermaxTokens;privateDoubletopP;privateListStringstop;}核心客户端OpenAiApiOpenAiApi 是 OpenAI HTTP 客户端的核心封装它使用了 Spring 的RestClientpublicclassOpenAiApi{privatefinalRestClientrestClient;privatefinalOpenAiChatOptionschatOptions;publicOpenAiApi(StringbaseUrl,StringapiKey,OpenAiChatOptionschatOptions){this.restClientRestClient.builder().baseUrl(baseUrl).defaultHeader(Authorization,Bearer apiKey).defaultHeader(Content-Type,application/json).build();this.chatOptionschatOptions;}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.classConditionalOnMissingBean仅当不存在自定义 Bean 时才创建允许用户替换默认实现ConditionalOnProperty检查配置属性可开关的模块关键设计原则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