三十行跑通：ChatClient 与自动装配解剖 能跑起来不叫会了 —— 知道"哪个 Bean 替你干了什么"才算

一、最小可运行：30 行

1. 配置

# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com        # 换成任意 OpenAI 兼容网关即可
      chat:
        options:
          model: gpt-4o-mini                  //!hl
          temperature: 0.2                    //!hl
    retry:
      max-attempts: 3                         # 框架内置重试（版本不同可能是 spring.ai.retry.*）
      backoff:
        initial-interval: 500ms
        multiplier: 2

国内同学可换 spring-ai-starter-model-* 的其他厂商 Starter，或把 base-url 指向兼容网关，代码零改动 —— 这就是 Port/Adapter 的红利。

2. 代码

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {      //!hl
        this.chatClient = builder                            //!hl
                .defaultSystem("你是资深 Java 架构师，回答简洁、有代码、有取舍分析。") //!hl
                .build();                                    //!hl
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String q) {
        return chatClient.prompt()
                .user(q)
                .call()
                .content();
    }

    // 流式：把 .call().content() 换成 .stream().content()
    @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestParam String q) {
        return chatClient.prompt().user(q).stream().content();   //!hl
    }
}

二、解剖：ChatClient.Builder 到底是谁注册的？

@AutoConfiguration
@ConditionalOnClass(ChatModel.class)
public class ChatClientAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    @Scope(BeanDefinition.SCOPE_PROTOTYPE)     //!hl
    ChatClient.Builder chatClientBuilder(ChatModel chatModel) {   //!hl
        return ChatClient.builder(chatModel);   //!hl
    }
}

三、ChatResponse 里到底装了什么

.content() 只是给你一个字符串的糖。真正的信息全在 ChatResponse 里：

ChatResponse response = chatClient.prompt().user(q).call().chatResponse();   //!hl

AssistantMessage out = response.getResult().getOutput();   //!hl
String text = out.getText();

// 1) 用量与计费（做成本核算必拿）
Usage usage = response.getMetadata().getUsage();           //!hl
long promptTokens     = usage.getPromptTokens();
long completionTokens = usage.getCompletionTokens();

// 2) 停止原因：STOP / LENGTH(被截断!) / TOOL_CALLS / CONTENT_FILTER
String finishReason = response.getResult().getMetadata().getFinishReason();  //!hl

// 3) 厂商原始信息、速率限制
String model = response.getMetadata().getModel();
RateLimit rl = response.getMetadata().getRateLimit();

四、两种 API 风格：什么时候退回 ChatModel

// 退回底层：手动拼 Prompt，精确控制每一条 Message
Prompt prompt = new Prompt(List.of(
        new SystemMessage("你是 SQL 审核专家"),
        new UserMessage("审核这段 SQL：" + sql)
), OpenAiChatOptions.builder().withTemperature(0.0).build());

ChatResponse r = chatModel.call(prompt);   //!hl

五、多模型共存与路由

@Configuration
class ModelConfig {
    // 廉价模型：做分类、摘要、路由
    @Bean @Qualifier("fast")
    ChatModel fastModel(OpenAiChatModel m) { return m; }

    // 你自己的公司网关 / 另一家厂商
    @Bean @Qualifier("strong")
    ChatModel strongModel(/* 另一套 properties 绑定的 ChatModel */ ...) { ... }

    @Bean
    ChatClient router(@Qualifier("fast") ChatModel fast,
                      @Qualifier("strong") ChatModel strong) {
        var fastClient   = ChatClient.builder(fast).build();
        var strongClient = ChatClient.builder(strong).build();
        // 由业务代码决定用哪个（第 09 话的 Routing 模式）
        return strongClient;
    }
}

六、超时、重试与降级（上线前必配）

• 重试：框架内置 spring.ai.retry.*（或各 Starter 自己的 retry 属性），处理 429/5xx 与网络抖动。
• 超时：走底层 HTTP Client 的 connect/read timeout（Starter 通常暴露对应属性），或用 Resilience4j 在外层包一层 TimeLimiter。
• 熔断降级：模型不可用时应返回"兜底话术 + 人工入口"，而不是把异常堆栈抛给用户。
• 幂等：重试意味着同一次用户输入可能被处理两次。所有写操作工具必须做幂等设计（第 06 话详述）。