0Pricing
Spring Boot 4 Complete Guide · 课时

ChatClient、提示词与结构化输出

通过 ChatClient 调用聊天模型，使用提示词模板和类型化的结构化输出映射。

ChatClient、提示词与结构化输出 是 CoddyKit 上的免费 Spring Boot 4 Complete Guide 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Spring Boot 4 Complete Guide 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Spring Boot 4 Complete Guide 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why ChatClient?

Spring AI gives you a fluent, high-level API for talking to LLMs: the ChatClient. Instead of hand-building HTTP requests to OpenAI, Anthropic, or Ollama, you describe what you want and let the framework handle transport, retries, and message assembly.

  • ChatClient — fluent builder for one-shot or streaming calls.
  • Prompt — a list of messages (system, user, assistant) plus options.
  • Structured output — map the model's text reply directly into a typed Java object.

It is portable: swap the underlying ChatModel (OpenAI → Anthropic) and your ChatClient code stays the same.

Auto-configuration and dependencies

Add a Spring AI model starter and Spring Boot auto-configures a ChatModel bean plus a ChatClient.Builder you can inject.

  • The starter (e.g. spring-ai-starter-model-openai) reads your API key and model from properties.
  • You never construct ChatClient directly — you inject the builder and call .build().

Typical configuration in application.yml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o
          temperature: 0.2

Creating a ChatClient

Inject the auto-configured ChatClient.Builder and build a client once, usually in your service constructor. You can attach default system prompts or options here so every call inherits them.

Building per-service (not per-request) keeps configuration in one place and is cheap.

@Service
public class AssistantService {

    private final ChatClient chatClient;

    public AssistantService(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("You are a concise Spring expert. Answer in one sentence.")
            .build();
    }
}

A first call: prompt().user().content()

The fluent chain reads like a sentence. Start with prompt(), add a user(...) message, then terminate with call() for a blocking response and content() to get the plain text.

  • call() — synchronous request/response.
  • content() — extracts the assistant's text.
  • chatResponse() — returns metadata (token usage, finish reason) instead.
public String ask(String question) {
    return chatClient.prompt()
        .user(question)
        .call()
        .content();
}

System vs user messages

An LLM prompt is a sequence of messages with roles:

  • System — instructions and persona; sets behavior.
  • User — the actual request from the end user.
  • Assistant — prior model replies (for multi-turn context).

You can override the default system message per call. Keep untrusted user input in user(...), never inside the system instruction, to reduce prompt-injection risk.

String answer = chatClient.prompt()
    .system("You are a senior Java reviewer. Be blunt and specific.")
    .user("Review this code: " + snippet)
    .call()
    .content();

Prompt templates with variables

Hard-coding strings does not scale. Spring AI uses template placeholders (default {name} syntax via StringTemplate) that you fill with param(...). The framework substitutes values before the request is sent.

  • Define the template text once with {placeholders}.
  • Bind values with .user(u -> u.text(...).param(...)).

This separates wording from data and keeps user values clearly bound.

String reply = chatClient.prompt()
    .user(u -> u
        .text("Summarize the topic {topic} for a {level} audience.")
        .param("topic", "reactive streams")
        .param("level", "beginner"))
    .call()
    .content();

How template substitution works

Under the hood Spring AI builds a PromptTemplate and renders it. You can also use the template directly when you want to reuse it or load it from a resource file.

Here is the same idea as a plain Java program you can run to see substitution — no Spring needed, just string formatting that mirrors what the renderer does:

import java.util.Map;

public class TemplateDemo {
    static String render(String tmpl, Map<String, String> vars) {
        String out = tmpl;
        for (var e : vars.entrySet()) {
            out = out.replace("{" + e.getKey() + "}", e.getValue());
        }
        return out;
    }

    public static void main(String[] args) {
        String t = "Summarize {topic} for a {level} audience.";
        System.out.println(render(t, Map.of("topic", "reactive streams", "level", "beginner")));
    }
}

Structured output: entity()

Often you do not want prose — you want a typed object. Spring AI's structured output converters do three things: inject a format instruction into the prompt, receive the model's text, and deserialize it into your type.

Define a plain Java record, then call .entity(MyType.class) instead of .content().

public record MovieReview(String title, int year, double rating, String verdict) {}

public MovieReview review(String movie) {
    return chatClient.prompt()
        .user("Give a short structured review of the movie: " + movie)
        .call()
        .entity(MovieReview.class);
}

Generic types with ParameterizedTypeReference

For collections or generic containers, Java erases the type parameter at runtime, so List.class is not enough. Pass a ParameterizedTypeReference so Spring AI knows the element type and generates the right JSON schema instruction.

import org.springframework.core.ParameterizedTypeReference;
import java.util.List;

public record Actor(String name, List<String> films) {}

public List<Actor> castOf(String movie) {
    return chatClient.prompt()
        .user("List the main cast of " + movie)
        .call()
        .entity(new ParameterizedTypeReference<List<Actor>>() {});
}

What entity() does to the prompt

It is worth understanding the mechanism: entity() uses a BeanOutputConverter that generates a JSON Schema from your record and appends a format instruction telling the model to reply with matching JSON only.

  • The model returns JSON text.
  • The converter parses it (via Jackson) into your record.
  • If the model adds stray prose, parsing can fail — lower temperature and keep records flat for reliability.

You can call the converter yourself to inspect the injected instruction:

import org.springframework.ai.converter.BeanOutputConverter;

record Weather(String city, double celsius) {}

var converter = new BeanOutputConverter<>(Weather.class);
String formatInstruction = converter.getFormat();
// This text is appended to your user prompt by entity()
System.out.println(formatInstruction);

Streaming and response metadata

For long answers, stream tokens as they arrive using stream() instead of call(), which returns a reactive Flux<String>. For observability, grab the full ChatResponse to read token usage and the finish reason.

  • .stream().content() — Flux<String> of incremental chunks.
  • .call().chatResponse().getMetadata().getUsage() — prompt/completion tokens.
import reactor.core.publisher.Flux;

public Flux<String> streamAnswer(String question) {
    return chatClient.prompt()
        .user(question)
        .stream()
        .content();
}

Quick Check

You need the model's reply mapped into a List<Actor>. Which terminal call is correct?

Recap

You learned to call LLMs the Spring way with ChatClient:

  • Inject ChatClient.Builder, set defaultSystem, and build() once per service.
  • Use the fluent chain: prompt().system(...).user(...).call().content().
  • Keep system instructions and untrusted user input in separate messages.
  • Use {placeholder} templates with .param(...) to separate wording from data.
  • Map replies to typed records with .entity(Type.class), and use ParameterizedTypeReference for generics like List<T>.
  • Stream with .stream().content() and inspect token usage via chatResponse().getMetadata().

For reliable structured output, keep records flat and lower the temperature.

常见问题解答

「ChatClient、提示词与结构化输出」课时是免费的吗？

是的 — 「ChatClient、提示词与结构化输出」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Spring Boot 4 Complete Guide 课程的其余内容，请升级到 CoddyKit PRO。 Spring Boot 4 Complete Guide 课程共包含 4 节课。

「ChatClient、提示词与结构化输出」这节课中我会学到什么？

通过 ChatClient 调用聊天模型，使用提示词模板和类型化的结构化输出映射。 你通过在浏览器中直接运行的动手代码来练习 Spring Boot 4 Complete Guide，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Spring Boot 4 Complete Guide 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Spring Boot 4 Complete Guide 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「ChatClient、提示词与结构化输出」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Spring Boot 4 Complete Guide 课中编写并运行代码吗？

能。每节 Spring Boot 4 Complete Guide 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. ChatClient、提示词与结构化输出
  2. 嵌入与向量存储检索
  3. 检索增强生成流水线
  4. 工具调用与代理顾问
← 返回 Spring Boot 4 Complete Guide