夜雨聆风一、ChatClient 是什么
ChatClient是Spring AI 核心入口API，是对大模型对话能力的统一抽象，屏蔽了 OpenAI、智谱、通义千问、Ollama、DeepSeek 等各大模型厂商的接口差异。
一句话：用同一套代码，随便切换任意大模型，不用改业务代码。
它替代了原生底层的 ChatModel，提供流式链式调用、Prompt 组装、结构化输出、拦截器、默认配置等更优雅的 Builder 编程风格，是 Spring AI 推荐首选使用方式。
二、ChatClient 核心定位
上层应用直接使用，不用对接各模型原生 API
封装：提示词、模型参数、多轮对话、工具调用、返回值解析
完全适配 Spring Boot 自动配置，自动注入、开箱即用
支持同步返回 + 流式 SSE 返回
三、两种创建 ChatClient 方式
1. 自动注入
Spring AI 自动根据配置文件，创建好 ChatClient Bean，直接注入即可
@RestControllerpublic classAiController{@Autowiredprivate ChatClient chatClient;}
2. 手动构建
// 先注入底层 ChatModel@Autowiredprivate ChatModel chatModel;// 手动构建 ChatClientChatClient customChatClient = ChatClient.builder(chatModel).defaultSystem("你是一名Java架构师，回答简洁专业").build();
四、ChatClient 完整链式调用结构
标准语法结构：
chatClient.prompt() // 开始构建请求.system("系统角色") // 系统提示词.user("用户问题") // 用户提问.options(模型参数) // 温度、最大token等.call() // 同步调用.content(); // 获取文本结果
核心链路节点说明
.prompt() | 开启一次对话请求构建器 |
.system() | 设置系统角色、人设、规则 |
.user() | 设置用户输入 |
.assistant() | 拼接历史助手回复，做多轮对话 |
.options(ChatOptions) | 配置模型参数：temperature、maxTokens、topP 等 |
.call() | 同步阻塞调用 |
.stream() | 流式响应（逐字返回，适合前端SSE） |
.content() | 获取纯文本字符串 |
.entity(Class<T>) | 自动把返回JSON转Java实体类 |
.chatResponse() | 获取完整响应对象（含Token消耗、元数据） |
五、常用实战用法
1. 最简单问答
String res = chatClient.prompt().user("介绍一下Spring AI").call().content();
2. 带系统人设
String res = chatClient.prompt().system("你是资深Java工程师，只用3句话回答").user("讲下Spring Boot核心特性").call().content();
3. 自定义模型参数
var options = ChatOptions.builder().temperature(0.7f) // 随机性 0~1.maxTokens(1024) // 最大输出token.build();String res = chatClient.prompt().user("写一个Redis分布式锁代码").options(options).call().content();
4. 流式输出（SSE 实时打字效果）
Flux<String> flux = chatClient.prompt().user("写一篇500字程序员文案").stream().content();
返回 Flux 可直接给前端 SSE 推送，实现聊天机器人实时输出。
5. 结构化输出 自动转POJO
定义实体：
public class Article {private String title;private String content;// getter/setter}
ChatClient 直接映射：
Article article = chatClient.prompt().user("生成一篇Java技术文章，返回JSON格式").call().entity(Article.class);
不用手动解析JSON，框架自动处理
6. 多轮上下文对话
String res = chatClient.prompt().system("你是聊天助手").user("我叫张三").assistant("好的张三，我记住了").user("我叫什么名字？").call().content();
手动拼接历史会话，实现记忆对话。
六、全局默认配置（统一人设、全局参数）
可以在构建时设置全局默认 system 提示词、默认参数，所有调用都生效：
@Beanpublic ChatClient chatClient(ChatModel chatModel) {return ChatClient.builder(chatModel)// 全局默认人设.defaultSystem("你是企业智能客服，语气礼貌简洁")// 全局默认模型参数.defaultChatOptions(ChatOptions.builder().temperature(0.5f).maxTokens(800).build()).build();}
七、ChatClient 和 ChatModel 区别
组件 | 层级 | 特点 | 使用场景 |
ChatModel | 底层 | 原生接口、偏底层、调用繁琐 | 底层自定义开发 |
ChatClient | 上层封装 | 链式调用、优雅、自带模板/结构化/拦截器 | 业务开发99%用这个 |
八、ChatClient 核心优势总结
统一接口：一套代码跑通所有大模型
链式Builder：代码可读性极高
内置结构化输出：自动转POJO，免手动JSON解析
支持同步+流式：适配聊天、文案生成等场景
全局默认配置：统一人设、统一模型参数
无缝整合Spring：自动配置、依赖注入、AOP、拦截器扩展
