时间戳：2026年4月10日 | 阅读时长：约8分钟 | 适用读者：Java开发者、AI应用工程师、面试备考者

一、开篇引入

在大模型技术爆发式发展的今天，将AI能力快速集成到企业级应用中已成为开发者的核心诉求。Spring AI作为Spring官方团队主导开发的开源项目，正是为解决这一诉求而生的Java生态AI应用开发框架-5。然而许多开发者在实际项目中仍面临“只会调用API、不懂底层原理、概念易混淆、面试答不出”的困境——有人纠结于Prompt到底应该放在system还是user里，有人分不清ChatClient和EmbeddingClient的使用场景，更有人被问及RAG原理时只能含糊其辞。本文将从痛点切入，系统讲解Spring AI的核心概念ChatClient与Prompt、二者关系、代码实战、底层原理及高频面试题，帮你建立完整知识链路。

二、痛点切入：为什么需要Spring AI？

先看一个传统场景：假设你要在Spring Boot应用中调用OpenAI的GPT-4模型。

// 传统方式：直接调用HTTP API，代码冗长且与具体厂商强绑定
public String callOpenAI(String userMessage) {
    // 1. 构建HTTP请求，处理认证头
    HttpHeaders headers = new HttpHeaders();
    headers.setBearerAuth(apiKey);
    // 2. 构造请求体JSON，序列化消息
    Map<String, Object> requestBody = new HashMap<>();
    requestBody.put("model", "gpt-4");
    requestBody.put("messages", List.of(Map.of("role", "user", "content", userMessage)));
    // 3. 发送请求，处理异常、超时、重试
    // 4. 解析响应JSON，提取content字段
    // 5. 如果后续要换到Anthropic Claude或本地Ollama，以上所有代码全部要重写
}

这段代码暴露了传统集成的三大痛点：供应商锁定——业务代码与OpenAI API深度耦合，切换模型成本极高；配置复杂——API密钥、超时设置、重试逻辑、异常处理都要重复编写；非声明式编程——大量样板代码充斥业务逻辑层，维护成本陡增-25。

Spring AI的出现正是为了解决这些问题——它提供统一的抽象接口，让开发者像使用RestTemplate或WebClient一样调用AI能力，真正实现“一次编写，随处运行”-5-25。

三、核心概念讲解：ChatClient

3.1 什么是ChatClient？

ChatClient 是 Spring AI 中用于与大语言模型（LLM）交互的核心API。它采用了流式（Fluent）API设计，类似于Spring生态中的WebClient或RestClient，提供了一套链式调用的编程体验-14。

3.2 生活化类比

你可以把 ChatClient 想象成“手机上的语音助手”——你对着它说出你的问题（用户消息），它就会给出回答。不同的是，你可以提前告诉它“你是一个专业的Java技术顾问”（系统消息），让它以特定身份和风格来回应你。

3.3 作用与价值

ChatClient解决了三个核心问题：

• 统一抽象：屏蔽不同AI厂商（OpenAI、Claude、Ollama、DeepSeek等）的API差异

• 声明式调用：通过Fluent API链式构建请求，代码简洁直观

• 深度Spring集成：自动配置、依赖注入、可观测性开箱即用

四、关联概念讲解：Prompt

4.1 什么是Prompt？

Prompt（提示词） 是我们与AI沟通的唯一方式——可以理解为“给AI下达的指令或提出的问题”-31。在Spring AI中，Prompt由消息集合构成，主要包括四种消息类型-31：

4.2 Prompt与ChatClient的关系

这是最容易混淆的一组概念。二者的逻辑关系可以这样概括：

ChatClient是“通道”和“执行器”，Prompt是“通道里传输的指令内容”。

更形象地说：ChatClient好比一个“邮递员”，Prompt则是“邮递员手里拿的信”。邮递员（ChatClient）负责把信（Prompt）送达AI模型，再把回信带回来。你换一个邮递员（比如从OpenAI换到Ollama），信的内容（Prompt结构）基本不变。

4.3 二者的差异对比

五、代码实战：从零搭建一个Spring AI应用

5.1 依赖配置（Maven）

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

5.2 配置文件（application.yml）

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}   从环境变量读取
      chat:
        options:
          model: gpt-4
          temperature: 0.7

5.3 基础使用示例

@RestController
public class AIController {
    private final ChatClient chatClient;
    
    // 通过构造函数注入ChatClient.Builder并创建ChatClient
    public AIController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }
    
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return this.chatClient.prompt()
            .user(message)           // 用户消息
            .call()                  // 阻塞式调用
            .content();              // 获取响应文本
    }
    
    // 高级示例：系统角色 + 结构化输出
    @GetMapping("/chat-structured")
    public Map<String, Object> chatStructured(@RequestParam String topic) {
        return this.chatClient.prompt()
            .system("你是一个专业的科普作家，请用幽默风趣的语气回答问题。")
            .user(u -> u.text("请用通俗易懂的方式解释：{topic}").param("topic", topic))
            .call()
            .entity(new ParameterizedTypeReference<Map<String, Object>>() {});
    }
}

代码关键点说明：

• prompt()：开始构建一个请求，返回流畅API的构建器-14

• user(String)：设置用户消息，可以带占位符参数（{topic}）

• call()：阻塞式调用，等待完整响应

• entity(Class)：自动将AI的文本回复解析为Java对象，基于JSON Schema映射-

运行效果：

• 请求 GET /chat?message=你是谁？ → 返回：“你好！我是AI助手，很高兴为你服务”

• 请求 GET /chat-structured?topic=量子纠缠 → 返回JSON：{"topic":"量子纠缠","explanation":"两只神奇袜子……","funny_note":"..."}-14

六、底层原理与技术支撑

6.1 核心依赖技术

Spring AI的底层能力建立在以下几个技术支柱之上：

6.2 设计精髓：模型解耦

Spring AI的核心理念在于 “模型解耦” ——使业务逻辑与底层AI模型彻底分离，增强系统可维护性与技术选型灵活性-6。当你需要在OpenAI和Ollama之间切换时，只需修改配置文件，业务代码一行都不用改：

 切换到本地Ollama模型
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3

这便是Spring AI带给Java开发者的最大价值——让AI能力像数据库连接池一样可配置、可替换。

七、高频面试题与参考答案

面试题1：请简要介绍Spring AI项目，它的核心目标是什么？

参考答案：
Spring AI是一个基于Spring生态系统的开源项目，其核心目标是简化AI功能在Java应用中的集成过程。它将各种AI提供商的复杂API进行统一封装，为开发者提供一套一致、声明式、符合Spring风格的编程模型-25。具体而言，它解决了三大痛点：

1. 供应商锁定：通过ChatClient、EmbeddingClient等统一接口实现模型切换零代码改动

2. 配置复杂：深度集成Spring Boot自动配置，开箱即用

3. 学习曲线：开发者无需分别学习各厂商SDK，一套API走遍天下

面试题2：ChatClient和Prompt的区别是什么？

参考答案：
ChatClient是Spring AI中与LLM交互的核心API和执行通道，采用Fluent API设计，负责连接模型、发送请求、接收响应。而Prompt是发送给AI的具体指令内容，由SystemMessage、UserMessage、AssistantMessage等消息组成，定义AI的角色、任务和约束。
一句话概括：ChatClient是“邮递员”，Prompt是“邮递员手里的信”。二者相互配合缺一不可——没有ChatClient，Prompt无法送达；没有Prompt，ChatClient不知道要执行什么任务。

面试题3：Spring AI中如何实现Tool Calling（工具调用）？

参考答案：
Tool Calling（也称Function Call）允许AI模型调用外部API或执行业务逻辑，常用于信息检索（如获取实时天气）和执行操作（如发送邮件）-40。在Spring AI中实现很简单：

@Component
class MyTools {
    @Tool(description = "获取当前时间")
    String getCurrentTime() {
        return LocalDateTime.now().toString();
    }
}
// 使用时将工具注册到ChatClient
chatClient.prompt("现在几点？").tools(new MyTools()).call().content();

核心机制是：Spring AI通过反射扫描@Tool注解的方法，自动生成JSON Schema注入到Prompt中，AI模型决定何时调用以及传入什么参数。

面试题4：Spring AI的架构分层是怎样的？

参考答案：
Spring AI的架构可分为三层：

• 顶层——抽象接口层：定义了ChatClient、EmbeddingClient、VectorStore等核心接口

• 中间层——适配实现层：为OpenAI、Ollama、Claude等各厂商提供具体实现

• 底层——基础设施层：整合Spring Boot自动配置、可观测性（Micrometer）、重试机制等-24

八、总结与进阶预告

核心知识点回顾

进阶方向预告

掌握了ChatClient和Prompt的基础知识后，下一篇文章我们将深入探讨：

• RAG（检索增强生成） ：如何让AI基于私有知识库回答专属问题

• Spring AI Alibaba Graph：基于图的工作流编排与多智能体协作-2

• MCP协议：Model Context Protocol的集成与应用-57

💡 学习建议：本文所有代码示例均可直接运行。建议你亲手敲一遍，感受ChatClient Fluent API带来的简洁体验，这是理解Spring AI最好的方式。