Java开发者AI转型第六课！Spring AI 灵魂架构 Advisor 切面拦截与自定义实战

大家好我是直奔標杆欢迎各位Java同行来到《Spring AI 零基础到实战》专栏的第六课咱们继续并肩前行一起攻克Spring AI的核心知识点在前五节课的学习中咱们一步步让AI拥有了专属人设、实现了图片识别、完成了JSON映射还搞定了打字机式的Flux流式输出。到这里大家已经熟练掌握了单次AI调用的所有基础操作相信不少小伙伴已经能上手简单的AI接口开发了。但咱们做Java开发都清楚实际的AI应用开发远比Demo复杂工程中总会遇到各种棘手问题分享给大家我实际开发中踩过的坑也帮大家提前规避可观测性需求每次调用AI前后都需要打印完整日志还要统计Token消耗方便排查问题上下文记忆问题大模型本身没有长期记忆需要在每次请求前自动拼接前10轮的聊天记录到提示词中RAG检索增强遇到专业领域问题得先从本地知识库检索相关文档再把文档内容传给大模型提升回答准确性。难道要把这些重复的非业务逻辑硬编码到每一个Controller接口里吗相信大家和我一样都觉得这种方式又繁琐又难维护好在Spring团队给出了极其优雅的解决方案——不搞反直觉的语法糖回归咱们Java开发者最熟悉的底层哲学——AOP面向切面编程今天这节课咱们就一起深入拆解Spring AI的灵魂组件ChatClient与Advisors手把手教大家写出规范、可扩展的现代AI工作流共同进步本节学习目标建议收藏对照学习1. 认知重塑搞懂Spring AI为何抛弃复杂的管道语法选择咱们熟悉的AOP模式理解其设计初衷2. 源码解密吃透Advisor的核心接口定义、执行顺序控制以及请求/响应的载体结构知其然也知其所以然3. 手写实战一起动手写一个自定义的SimpleLoggerAdvisor兼顾同步与流式调用的拦截练熟实战技巧4. 官方武器库全面梳理Spring AI内置的开箱即用顾问掌握记忆、RAG、风控、重读提示等高频功能的使用方法。Advisor 拦截器链的逻辑处理核心重点在看源码之前咱们先通过架构图直观感受下当调用ChatClient的.call()方法时请求是如何穿过层层Advisor拦截器最终到达大模型的建议结合源码对照看理解更透彻执行流程拆解通俗易懂版当咱们执行.call()方法时请求会被封装成ChatClientRequest对象依次经过咱们配置的所有Advisor拦截器。每个Advisor都可以对请求进行修改上一节课咱们讲的结构化输出就是用ChatModelCallAdvisor拦截处理的大家可以回头回顾下之后请求会到达底层的ChatModel获取到ChatClientResponse响应对象。紧接着响应数据会原路返回再次穿过所有Advisor拦截器最终传递到咱们的业务代码中。这里重点提醒大家Advisor的执行采用经典的责任链模式通过getOrder()方法控制执行顺序——值越小请求阶段Pre-process越先执行而响应阶段Post-process则越后执行就像穿衣服和脱衣服的逻辑很好记大家多练两次就能掌握。AOP思想在AI调用中的投射新手必看Advisor顾问可以说是Spring AI的灵魂设计核心目的就是解决AI交互中大量重复出现的通用逻辑比如维护对话历史、检索文档、过滤敏感词等实现非业务逻辑与业务逻辑的解耦这也是咱们Java开发中最常用的设计思想之一。如果大家熟悉Spring MVC的Interceptor、Servlet的Filter或者Spring核心的Around环绕通知那么理解Advisor几乎没有门槛。我整理了一份对应关系表方便大家快速对应记忆一起吃透AOP概念Spring Web概念Spring AI概念作用说明通俗解读Target (目标)Controller逻辑ChatModel真正负责与OpenAI等大模型通信的底层客户端是最终执行AI调用的核心Proxy (代理)DispatcherServletChatClient咱们开发者直接调用的入口负责组装请求、触发拦截链简化调用流程Advice (通知)Filter/InterceptorAdvisor核心拦截请求与响应将日志、记忆、检索等非业务逻辑抽离实现解耦便于维护Join Point接口被调用的瞬间call()/stream()触发大模型调用的具体动作也是Advisor拦截的核心节点Advisor 核心接口解构源码级解析想要自定义Advisor首先得吃透它的基础骨架这部分内容建议大家结合Spring AI源码一起看我会尽量讲得通俗避免晦涩新手也能跟上。2.1 核心接口规范必掌握- Advisor所有顾问的顶层基接口继承了Spring的Ordered接口必须实现getName()和getOrder()两个方法- getOrder()重中之重决定Advisor的执行顺序值越小请求阶段越先执行响应阶段越后执行大家一定要注意规划顺序- CallAdvisor专门用于拦截.call()同步请求核心方法是adviseCall()处理同步调用的拦截逻辑- StreamAdvisor专门用于拦截.stream()流式请求核心方法是adviseStream()处理流式调用的拦截逻辑。2.2 数据传输载体 (DTO)高频使用- ChatClientRequest请求载体包含即将发给大模型的Prompt、系统指令、参数配置等咱们可以根据需求自由修改- ChatClientResponse响应载体包含大模型返回的原始响应、文本内容、Token消耗等元数据方便咱们获取调用详情- AdvisorContext本质是一个Map用于在不同Advisor之间共享数据比如传递对话ID、用户信息等非常实用。实战案例手写日志拦截器新手可直接复用相信大家在开发中都遇到过这样的问题AI回答不符合预期排查半天发现是传给大模型的Prompt拼接错了。为了方便调试今天咱们就一起手写一个日志拦截器在请求发出前打印请求参数响应返回后打印完整响应大家可以直接复制到项目中使用。这里分享一个最佳实践亲测有效如果业务允许Advisor建议同时实现CallAdvisor和StreamAdvisor确保同步和流式两种调用模式下都能正常工作避免出现兼容问题。下面开始动手创建SimpleLoggerAdvisor类代码如下每一行都加了注释大家看不懂的地方可以留言交流import lombok.extern.slf4j.Slf4j; import org.springframework.ai.chat.client.ChatClientMessageAggregator; import org.springframework.ai.chat.client.ChatClientRequest; import org.springframework.ai.chat.client.ChatClientResponse; import org.springframework.ai.chat.client.advisor.api.CallAdvisor; import org.springframework.ai.chat.client.advisor.api.CallAdvisorChain; import org.springframework.ai.chat.client.advisor.api.StreamAdvisor; import org.springframework.ai.chat.client.advisor.api.StreamAdvisorChain; import reactor.core.publisher.Flux; /** * 自定义日志拦截器顾问 * 直奔標杆 实战案例可直接复用 */ Slf4j public class SimpleLoggerAdvisor implements CallAdvisor, StreamAdvisor { Override public String getName() { // 返回当前类名作为顾问名称便于排查问题 return this.getClass().getSimpleName(); } /** * 顺序控制设为 0 表示优先级很高最外层执行 * 大家可根据实际业务调整顺序 */ Override public int getOrder() { return 0; } // 拦截同步调用 (.call) Override public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) { // 请求大模型前打印请求头和 Prompt便于调试 logRequest(request); // 放行请求交给链条中的下一个 Advisor 或底层 ChatModel ChatClientResponse response chain.nextCall(request); // 拿到大模型结果后打印返回信息确认响应是否符合预期 logResponse(response); return response; } // 拦截流式调用 (.stream) Override public FluxChatClientResponse adviseStream(ChatClientRequest request, StreamAdvisorChain chain) { // [Pre-process] 请求发出前打印和同步调用保持一致的日志逻辑 logRequest(request); // 放行流式请求继续执行拦截链 FluxChatClientResponse responseFlux chain.nextStream(request); // 重点注意流式响应是分段返回的需要拼接完整后再打印 // 这里使用ChatClientMessageAggregator拼接所有响应片段 return new ChatClientMessageAggregator() .aggregateChatClientResponse(responseFlux, this::logResponse); } // 内部打印方法封装日志逻辑便于复用和修改 private void logRequest(ChatClientRequest request) { log.info([发往大模型的请求]: {}, request); } private void logResponse(ChatClientResponse response) { log.info( [大模型的完整响应]: {}, response); } }实战补充如何将自定义Advisor挂载到ChatClient很多新手写完Advisor后不知道怎么挂载使用其实非常简单只需在ChatClient构建时通过.advisors()方法挂载即可我给大家写了一个测试案例直接复制就能运行Test void testOllamaClient() { String result chatClient.prompt() .user(你好, 请介绍一下 Spring AI) // 挂载咱们刚刚手写的日志顾问直接new即可 .advisors(new SimpleLoggerAdvisor()) .call() .content(); System.out.println(最终结果 result); }运行测试后控制台就能看到拦截器打印的完整请求报文和响应体了大家可以亲自测试一下加深理解。这里贴一下控制台的大致输出供大家参考[发往大模型的请求]: ChatClientRequest[promptPrompt{messages[UserMessage{content你好, 请介绍一下 Spring AI....[大模型的完整响应]: ChatClientResponse[..., textContentSpring AI 是一个由 Spring 官方团队推出的项目旨在将人工智能能力....Spring AI 内置 Advisors高频实用建议收藏吃透了Advisor的原理咱们不仅能自己写拦截器还能直接复用Spring团队为咱们预置的强大内置顾问日常业务中90%的高级AI需求都能直接开箱即用节省大量开发时间这也是Spring AI的优势所在——遵循Spring风格统一抽象、易于集成让咱们用写Spring Boot应用的习惯开发AI功能。1. 聊天记忆顾问 (Memory)解决AI“失忆”问题大模型天生没有长期记忆这几个内置顾问能帮咱们轻松解决这个问题分享给大家我常用的3个- MessageChatMemoryAdvisor自动检索历史聊天记录以Message对象列表的形式追加到请求中适配大多数场景- PromptChatMemoryAdvisor将历史聊天记录直接拼接成文本放入System提示词中配置简单上手快- VectorStoreChatMemoryAdvisor将会话历史存入向量数据库对话时自动检索最相关的记忆片段适合复杂对话场景。2. 检索增强顾问 (RAG)企业级私有知识库核心做企业级AI应用RAG是必备功能这两个内置顾问能帮咱们快速实现检索增强不用自己从零开发- QuestionAnswerAdvisor结合向量数据库自动检索企业私有文档追加到Prompt中实现AI“外挂大脑”- RetrievalAugmentationAdvisor更高级的模块化RAG流程控制组件适合复杂的检索场景扩展性更强。3. 推理增强顾问 (Reasoning)提升AI回答准确率- ReReadingAdvisor基于著名的RE2论文实现自动让大模型“重读”问题能显著提升复杂逻辑题的回答准确率亲测有效。4. 内容安全顾问 (Safeguard)保障AI输出合规- SafeGuardAdvisor请求发送前、响应返回后自动检测并过滤有害内容、敏感词确保AI输出合规安全避免踩坑。Advisor开发最佳实践避坑指南亲测总结结合我实际开发中的经验给大家总结了4个Advisor开发的最佳实践避免大家走弯路一起写出高质量的代码1. 单一职责每个Advisor只负责一件事比如只做日志记录或只处理对话记忆不要在一个Advisor里写几千行代码否则后期难以维护2. 上下文共享多个Advisor之间需要传递数据比如当前用户ID、对话ID直接用ChatClientRequest.getAdviseContext()它本质是一个跨拦截链的Map非常方便3. 兼容双模式强烈建议同时实现CallAdvisor和StreamAdvisor确保拦截逻辑在同步和流式调用下都能生效避免出现兼容问题4. 严格控制顺序一定要认真规划getOrder()的返回值确保数据流正确。比如内容过滤的Advisor Order要尽量小外层拦截敏感词RAG的Advisor Order稍靠后处理完最终Query再检索。总结核心提炼快速回顾其实Spring AI的Advisor设计本质就是Spring AOP思想在AI领域的延伸Spring团队用咱们Java开发者最熟悉的方式完美解决了AI提示词工程的复杂度这也是Spring AI的核心哲学——把AI能力拆成可组合的稳定抽象再用Spring风格把它们工程化。通过Advisor咱们能将日志、记忆、RAG检索、内容过滤等非业务逻辑彻底解耦不仅降低了Java开发者的AI转型学习成本还让代码拥有极强的扩展性。这里给大家一个形象的比喻ChatClient就像一块精密的主板而所有的Advisor都是即插即用的显卡和内存条按需组合就能实现各种复杂的AI功能希望大家学完这节课能动手实践起来只有多写代码、多踩坑才能真正掌握Advisor的使用咱们一起在AI转型的路上稳步前行直奔標杆下节预告精彩不容错过理论武器已经装配完毕接下来就是真刀真枪的实战环节咱们在实际调用AI API时都会遇到一个头疼的问题——AI天生就是“失忆症患者”根本记不住上一秒说的话下一节第7课《AI失忆症克星ChatMemory 对话历史管理与上下文实战》咱们将深入剖析大模型失忆的本质原因结合本节课学到的MessageChatMemoryAdvisor搭配各种内存与分布式存储方案手把手教大家打造一个拥有“长久记忆”的完美AI客服实用性拉满精彩继续咱们下节见往期内容连贯学习循序渐进Java开发者AI转型第五课让AI懂规矩Spring AI 结构化输出 (DTO) 映射与 Flux 流式打字机极速响应关注我直奔標杆持续更新Spring AI零基础到实战系列和各位Java同行一起稳步实现AI转型少走弯路、直奔目标如有疑问欢迎在评论区留言交流一起探讨、共同进步