大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



 
  
    
     
很多 Java 工程师第一次接 Spring AI，写 Prompt 的方式和写配置文件很像：
 

• 一大段字符串
• 所有要求全塞进去
• 变量、JSON、角色、输出格式堆在一起
• 最后再补一句“请严格按照以上要求执行”

这种写法短期能跑，长期很容易失控。你会遇到这些现象：

• 某些变量替换错位
• JSON 模板和占位符打架
• Advisor 拼进来的上下文和你预期不一致
• 系统指令、用户输入、业务上下文糊成一团

Spring AI 的 Prompt 体系其实比“拼字符串”讲究得多。你如果还把 Prompt 当配置文件来堆内容，后面越写越难调。

在 Spring AI 里，Prompt 更像“结构化输入”，不是“静态配置文本”。

官方文档里对 Prompt 的定义很明确：它是由多条 Message 组成的容器，每条消息有不同角色，比如 user、system 等。也就是说，从框架视角看，Prompt 本来就不是一个大字符串。

这篇我只拆最容易把 Prompt 写崩的 5 个原因。

String result = chatClient.prompt() .system("You are a careful Java architect. Reply in concise Chinese.") .user(u -> u.text(""" 请帮我分析一个 Spring AI Agent 项目结构。 约束： 1. 只讨论 Java 项目 2. 优先给出最小可运行方案 项目背景：{context} """) .param("context", "团队已经有 Spring Boot 基础，没有 Graph 和 MCP 经验")) .call() .content(); 

这段代码至少把 3 件事拆开了：

• 全局行为放在 system
• 用户任务放在 user
• 运行时上下文通过 .param() 注入

如果你现在项目里的 Prompt 还全靠一大段手写拼接字符串，下面这些坑你多半已经踩过。

这是最常见的第一步错误。

Spring AI 官方文档说得很清楚，Prompt 由多条带角色的消息组成。system 和 user 不是装饰性的，它们就是不同语义层。

如果你把这些东西都塞进一段 user 文本里，短期也许模型还能猜到你的意思，但随着 Prompt 变长，边界会越来越乱：

• 哪些是长期规则
• 哪些是这次请求的任务
• 哪些只是业务背景

模型并不是完全分不清，但你自己会先分不清。

尤其当你后面引入：

• Chat Memory
• RAG
• MCP
• Tool Calling

这些能力都会继续往 Prompt 或消息链里塞东西。你原来那种“所有要求一段写完”的风格，很快就会把自己绕进去。

更稳的做法是：

• system 放长期行为边界
• user 放当前任务
• 运行时背景放参数或 advisor

别为了图省事，把三层语义写成一层文本。

很多人写 Prompt 时喜欢加这种句子：

• “请保持稳定输出”
• “请不要太发散”
• “请回答简洁”
• “不要超过 200 字”

这些话不是完全没用，但如果你已经在 Spring AI 里工作，就不该只靠文字描述去压模型行为。

官方的 Prompt Engineering Patterns 和 ChatClient 文档都强调了一点：像 temperature、maxTokens 这类控制生成行为的参数，本来就应该走 ChatOptions。

例如：

String result = chatClient.prompt() .user("请把这段 Spring Boot 代码解释成面向初学者的版本") .options(ChatOptions.builder() .temperature(0.1) .maxTokens(300) .build()) .call() .content(); 

如果你把“稳定”“简洁”“少发散”全写在 Prompt 里，但配置层的温度还很高，那最后失控也不奇怪。

一句话说透：

Prompt 负责表达意图，Options 负责约束生成行为。别拿自然语言去替代本来就有的控制参数。

这个坑在 Java 项目里非常常见，因为很多人喜欢让模型输出 JSON、SQL、DSL，甚至直接输出配置片段。

Spring AI 官方文档提到，ChatClient 默认使用 StTemplateRenderer，变量默认用 {} 语法。

问题来了。你一旦在 Prompt 里同时写：

• JSON 示例
• 模板变量

那两边都在用大括号，冲突就很自然。

官方文档甚至直接给了解法：如果 Prompt 里要包含 JSON，可以改模板分隔符，比如改成 < 和 >：

String answer = ChatClient.create(chatModel).prompt() .user(u -> u .text(""" 请输出一个 JSON： { "topic": " 
     
       " } """ 
     ) .param("topic", "Spring AI")) .templateRenderer(StTemplateRenderer.builder() .startDelimiterToken('<') .endDelimiterToken('>') .build()) .call() .content(); 

很多“怎么变量没替进去”“怎么 JSON 结构乱了”的问题，根因不是模型不行，而是模板层先把你坑了。

这个点很容易想错，而且 Spring AI 官方文档专门提醒了。

文档明确说，配置在 ChatClient 上的 .templateRenderer()，只影响你在 builder 链里直接写的 .user()、.system() 等内容。

它不会影响 advisor 内部使用的模板。

这意味着，如果你项目里同时用了：

• QuestionAnswerAdvisor
• PromptChatMemoryAdvisor
• 其他自定义 advisor

那你在 ChatClient 上配好的模板渲染规则，不会自动传进去。

很多人以为“我都统一改成 < > 了，为什么某个 advisor 还是按 {} 在渲染？”

答案很简单：因为那不是同一个模板层。

这也是为什么我说 Prompt 不是配置文件。你不能指望在一个地方改一个模板设置，系统里所有 Prompt 相关行为都自动统一。

Spring AI 的 Prompt Engineering Patterns 文档里专门讲了：

• system prompting
• role prompting
• contextual prompting

这里最容易被低估的是 contextual prompting。

很多 Java 项目一开始为了快，会把业务背景直接写死在 Prompt 文本里，比如：

• 目标用户是谁
• 行业背景是什么
• 当前环境限制是什么

短期当然能用，但一旦场景变多，你就会开始复制 Prompt、改版本、加分支，最后 Prompt 文件越来越像一份难维护的配置仓库。

更稳的做法是把变化的信息参数化：

String answer = chatClient.prompt() .system("你是一名擅长做 Java Agent 架构设计的工程师") .user(u -> u.text(""" 请给出 3 个适合写成技术博客的主题。 背景：{context} 目标读者：{audience} """) .param("context", "团队有 Spring Boot 经验，刚接触 Spring AI") .param("audience", "中高级 Java 后端工程师")) .call() .content(); 

这样做的好处不是“更高级”，而是以后你调试时知道哪部分是固定规则，哪部分是运行时输入。

如果是我自己做 Spring AI 项目，我一般会按这几层拆：

1. system 放角色、边界、输出原则
2. user 放当前任务
3. .param() 放运行时上下文
4. ChatOptions 放温度、长度等生成参数
5. advisor 负责它自己的模板和上下文增强

这个拆法的好处不是“优雅”，而是你后面排障时知道去哪里改。

• 你是不是把 system、user、上下文写成了一大段字符串？
• 你是不是用 Prompt 文本去替代 ChatOptions？
• Prompt 里既有 JSON 又有 {} 占位符吗？
• 你是否需要改模板分隔符，或者改用 NoOpTemplateRenderer？
• 你是不是误以为 ChatClient.templateRenderer() 会影响 advisor 内部模板？
• 那些变化频繁的背景信息，是否已经参数化？

很多 Prompt 失控，不是因为提示词工程有多玄学，而是因为你用错了抽象层。Spring AI 已经把消息角色、模板渲染、运行时参数和生成配置分开了。如果你还把它们糊成一团，后面越写越难救。

下一篇我继续写 用 Spring Boot + Spring AI 接 MCP，我踩过的 6 个连接坑。那个坑和 Prompt 不一样，它经常不是“写得不优雅”，而是“明明接上了却用不起来”。

• Spring AI Chat Client API: https://docs.spring.io/spring-ai/reference/api/chatclient.html
• Spring AI Prompts Reference: https://docs.spring.io/spring-ai/reference/api/prompt.html
• Spring AI Prompt Engineering Patterns: https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/chat/prompt-engineering-patterns.html

文中的以下结论直接来自 Spring AI 官方文档：

• Prompt 本质上是由多条带角色的消息构成
• ChatClient 默认使用 StTemplateRenderer
• 默认模板变量语法是 {}，可以改分隔符避免和 JSON 冲突
• .templateRenderer() 只影响 ChatClient builder 链里直接定义的 prompt 内容，不影响 advisor 内部模板
• system prompting、role prompting、contextual prompting 都是官方文档明确给出的实践模式

文中的这些表述属于我的工程归纳，不是官方原句：

• “Prompt 更像结构化输入，不是静态配置文本”
• “别拿自然语言去替代本来就有的控制参数”
• “很多 Prompt 失控不是模型的问题，而是抽象层没拆开”