Spring AI Tool 5 黄金法则

做 AI 面试平台到第七天，把 5 个 @Tool 注入 ChatClient，跑了一周才发现一件事：工具调用这件事，一行 Java 代码改不了，全靠几行注释。  

刚开始我用 description 等于"抽取面试题"这种最简版本，命中率只有六成。LLM 经常答得头头是道，但就是不调用工具，自己编一道题就丢出来。最严重一次，candidate 在面试里随口问"你有什么工具能用"，LLM 直接把 @Tool 返回的整张 Question 表念了出来，参考答案当场被套了出去。  

后来一条条法则填上去，命中率从 60% 一路爬到 95%，安全风险归零。把这一周踩过的坑摊平，就是下面这五条。  

法则一：description 必须写"触发场景关键词"  description 不是给同事看的，是给 LLM 看的。"抽取面试题"这种功能描述，LLM 完全猜不出该不该调。改成"当用户要求出题、抽题、刷题、考察某岗位时调用"，里面塞够触发场景的关键词，命中率直接从 60% 跳到 90%。description 还要写清前置依赖、参数边界、副作用，何时使用、依赖什么、参数范围、有何副作用，四要素一个不能少。 

 法则二：返回值严禁直接给 DO/VO，必须经 toToolView 脱敏  这是最重的一条，踩不好会出安全事故。@Tool 的返回值会被 LLM 拼回 Prompt，candidate 完全可能用 prompt injection 套出。我之前直接 return Question DO，里面 answer 字段就这么裸出去了。正确做法是单独写一层 toToolView 工厂方法，DO 进来，VO 出去，answer 这种敏感字段直接抹掉，只留题面、选项、知识点。ToolView 用 Map 隔离，做哪个工具就只暴露哪些字段，零交叉污染。  

法则三：入参校验抛 IllegalArgumentException 加自然语言提示  LLM 的入参经常乱填，count 给负数、岗位给空串都很常见。不要傻乎乎抛 NPE，那一抛 LLM 完全不知道怎么改。正确姿势是抛 IllegalArgumentException，message 写人话："count 必须是 1 到 50 的正整数，您传的是 -3，请改正后重试"。LLM 拿到这条信息会自己纠错重调，整个对话不需要再插人工补救。  

法则四：ChatClient.defaultTools 一次注入全场景复用  老教程喜欢 per-call 写 .tools(toolA, toolB)，每个接口都要罗列一遍。1.0 GA 的最佳实践是反射扫描所有 @Tool 方法，在 ChatClient 构造时一次性走 defaultTools 注入，全场景共用同一个工具池。代码量少一半，新加工具不需要改任何 Controller。  

法则五：System Prompt 必须加【可用工具】加【工具纪律】  光把 @Tool 注进去还不够，LLM 不知道纪律就会随心所欲调用。System Prompt 里要单列两段。【可用工具】列名字、列触发条件、列依赖关系。【工具纪律】写硬约束，比如"不准跳过 listQuestionBanks 直接 drawQuestions"、"调用任何工具前先在内心做一次需要性判断"。两段加上去，调用率再涨 35%。  

踩坑教训  

第一坑，老资料和 1.0 GA API 不匹配。@Bean Function 加 .functions() 是已经废弃的旧范式，所有视频和博客只要日期早于 2026 春，全部要按官网重新核对。starter 名字改了，RAG Advisor 包路径迁了，ChatMemory 接口换了，一边写一边查 docs.spring.io 是基本动作。 

 第二坑，JDK 11 升 17 是硬门槛，且 Nashorn 移除后 CalculatorTool 必须换 Aviator 或 MVEL。SpringBoot 3.x 加 SpringAI 1.0 GA 全要 JDK 17+，没有妥协空间。  

第三坑，description 写一遍不够，要边跑边调。这一周我至少改过 6 个版本才把命中率从 60% 拉到 95%。真实 candidate 怎么提问，永远比开发者想象的更跳跃，必须用真实对话回归。  

工程结论  Spring AI 1.0 GA 的工程师，核心能力不是写 Java，是写"给 LLM 看的 Java 注释"。description、@ToolParam description、System Prompt、IllegalArgumentException message，这四条自然语言才是真正的控制面板，代码只是骨架。  

下一步我会把这五条法则做成 code review checklist，每个 PR 强制对照五条逐条勾选，避免回归。也会把 1.0 GA 的 API 速查表沉淀成单页文档，避免被老资料反复带偏。Tool Calling 不是炫技，是工程纪律。