Spring AI项目中ChatClient配置下AdvisedRequest.userText的注意事项

在Spring AI项目的实际开发中，开发者可能会遇到一个关于ChatClient配置的典型问题：当使用特定方式构建Prompt时，AdvisedRequest.userText字段未能正确填充，导致系统抛出"Content must not be null"的异常。这个问题看似简单，却揭示了Spring AI框架中消息处理机制的一个重要设计原则。

问题本质

这个问题的核心在于Spring AI框架对Prompt中消息顺序的敏感性。框架内部在处理ChatClient请求时，会默认将Prompt中最后一个Message作为userText的来源。当开发者将UserMessage放在SystemMessage之前构建Prompt时，框架会错误地将SystemMessage识别为用户输入，而SystemMessage本身没有content内容，这就导致了空指针异常。

技术原理

Spring AI的消息处理机制遵循特定的对话流程逻辑：

1. 消息顺序决定对话流程：Prompt中的消息顺序实际上模拟了真实对话的时序，SystemMessage代表系统预设，UserMessage代表用户输入
2. 自动填充机制：当未显式指定userText时，框架会自动选择最后一个Message作为用户输入
3. 类型安全校验：框架会严格检查Message类型与内容的匹配性，SystemMessage必须有系统指令，UserMessage必须有用户输入

最佳实践

为了避免这类问题，开发者应该遵循以下实践准则：

1. 正确的Prompt构建顺序：始终将SystemMessage置于UserMessage之前

// 正确写法
Prompt prompt = new Prompt(systemMessage, userMessage);

2. 显式指定用户输入：当需要更精确控制时，可以直接设置userText

chatClient.prompt(prompt)
    .userText("明确的用户输入")
    .call()

3. 理解框架设计哲学：Spring AI通过这种设计强制开发者明确区分系统指令和用户输入，这有助于构建更健壮的对话系统

深入思考

这个问题实际上反映了对话系统设计中的一个重要原则：对话状态的明确分离。SystemMessage代表系统角色和能力的定义，UserMessage代表具体的用户请求，二者在对话流程中具有不同的语义和时序要求。Spring AI通过这种强制性的顺序要求，实际上是在帮助开发者建立正确的对话系统设计思维。

对于更复杂的对话场景，开发者还可以考虑：

1. 使用ChatMemory来管理多轮对话状态
2. 通过自定义Advisor实现更灵活的消息处理逻辑
3. 结合PromptTemplate实现动态消息构建

理解这些底层机制，将帮助开发者更好地利用Spring AI构建稳定、高效的AI对话应用。