CH 03结构化输出与 Advisors

3.1为什么输出必须是对象

先看一个真实场景。用户输入一段话，你要从中提取成订单数据：

// 用户输入（一段自由文本，可能来自邮件、聊天记录、OCR 结果）
"你好，我是张三，订单 2024001 在 3 月 5 日下的单，金额 899 元，
 买了一个机械键盘和一个鼠标垫，现在还没发货，麻烦催一下。联系电话 138****8888"

如果用纯文本返回，你拿到的是一段字符串，要写正则去抠订单号、抠金额——模型稍微换个说法（「总计 899 元」/「共 899.00 元」），你的正则就废了。这就是非结构化输出的致命问题：不可靠。

动手：创建 OrderInfo 映射类

我们的目标类型用 record（简洁且不可变）。下面这步是本章第一个「可运行节点」——先把映射类建出来并编译通过，后面才能往上叠逻辑。

1. 在 IDEA 左侧 Project 视图里，展开 src/main/java，找到包 com.example.springai。在 com.example.springai 上右键 → New → Package，输入 com.example.springai.ch03.model，回车。这是本章所有模型类的家。

2. 在刚建好的 com.example.springai.ch03.model 包上右键 → New → Java Class，Name 填 OrderInfo，按回车（Kind 选 Class 即可，record 我们手动写）。

3. 把 IDEA 自动生成的内容整段清空，粘贴下面这段「标准答案」（注意字段顺序、注解一字不差）：

   package com.example.springai.ch03.model;
   
   import java.math.BigDecimal;
   import java.time.LocalDate;
   import java.util.List;
   
   /**
    * 订单信息提取结果。
    * 用 record 的好处：字段即构造参数，Jackson 反序列化开箱即用（JDK 17+ / Jackson 2.12+）。
    * 注意字段名要和提示词里的 JSON schema 对应，否则映射不上会得到 null。
    */
   public record OrderInfo(
           String orderNo,              // 订单号，如 2024001
           String customerName,         // 客户姓名
           BigDecimal amount,           // 金额。★ 必须用 BigDecimal，绝不能用 double
           String status,               // 状态：未发货/已发货/已完成/已取消
           LocalDate orderDate,         // 下单日期
           List<String> items,          // 商品列表
           String phone                 // 联系电话
   ) {}

4. Ctrl + S 保存（或等 IDEA 自动保存）。

运行验证（编译期验收）：在 IDEA 底部的 Terminal（或系统终端，先 cd 到工程根目录，即含 pom.xml 的那层）执行：

mvn -q compile

期望看到：命令安静退出、没有任何红色报错；若想确认，去掉 -q 再跑一次应出现 BUILD SUCCESS。

[INFO] BUILD SUCCESS
[INFO] Total time:  3.456 s

看到什么算通过：OrderInfo 这个 record 能被 javac 编译进 target/classes，说明包名、import、record 语法全部正确。编译不过就别往下走——后面所有逻辑都依赖它。

为什么选 record 而不是普通 class？三个理由：① 不可变，多线程下天然安全；② 构造参数顺序即字段顺序，Jackson 按名称匹配不受影响；③ 自动生成 equals/hashCode/toString，调试时打印对象一目了然。本课程不使用 Lombok（见第 0 章纪律），所以校验注解直接写在 record 的组件上即可，不需要额外加 @Data。

3.2entity()：一行代码拿到对象

Spring AI 把「提示词工程 + 解析」这套流程封装得极其简单——把 .content() 换成 .entity() 即可。下面先把「标准答案写法」整体看一遍，再建一个临时接口把它真跑起来。

import org.springframework.ai.chat.client.ChatClient;

// 返回单个对象
OrderInfo order = chatClient.prompt()
        .user(userText)
        .call()
        .entity(OrderInfo.class);      // ★ 关键就这一个方法

System.out.println(order.orderNo());   // 2024001
System.out.println(order.amount());    // 899

// 返回集合：泛型需要用 ParameterizedTypeReference 保住类型信息
List<OrderInfo> orders = chatClient.prompt()
        .user("把这段文本里的所有订单都提取出来：\n" + multiOrderText)
        .call()
        .entity(new ParameterizedTypeReference<List<OrderInfo>>() {});

// 返回 Map（字段不固定时用）
Map<String, Object> map = chatClient.prompt()
        .user(userText)
        .call()
        .entity(Map.class);

动手：建一个临时接口把 entity() 跑起来

光看写法不过瘾，我们建一个「练习接口」用真实请求验证 entity()。这个接口学完可删，专门用来观察 entity() 的行为。

1. 在 com.example.springai.ch03 包上右键 → New → Java Class，Name 填 QuickEntityController。

2. 清空内容，粘贴下面这段「标准答案」（它就是一个最小可跑的 entity() 调用方）：

   package com.example.springai.ch03;
   
   import com.example.springai.ch03.model.OrderInfo;
   import org.springframework.ai.chat.client.ChatClient;
   import org.springframework.web.bind.annotation.*;
   
   import java.util.Map;
   
   @RestController
   @RequestMapping("/api/v1/ch03")
   public class QuickEntityController {
   
       private final ChatClient chatClient;
   
       public QuickEntityController(ChatClient chatClient) {
           this.chatClient = chatClient;
       }
   
       // 练习接口：直接把实体返回，便于观察 entity() 映射结果
       @PostMapping("/quick-entity")
       public OrderInfo quickEntity(@RequestBody Map<String, String> body) {
           return chatClient.prompt()
                   .user(body.get("text"))
                   .call()
                   .entity(OrderInfo.class);
       }
   }

3. Ctrl + S 保存。

4. 确认 application.yml 里模型密钥占位符是 ${DEEPSEEK_API_KEY:}（见第 0 章），且环境变量已注入（重开过 IDEA）。然后启动应用：IDEA 里点启动类旁的运行箭头，或终端执行 mvn -q spring-boot:run。

运行验证：应用起来后（端口 8080），另开一个终端发请求：

curl -X POST http://localhost:8080/api/v1/ch03/quick-entity \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，我是张三，订单 2024001 在 3 月 5 日下的单，金额 899 元，买了一个机械键盘和一个鼠标垫，现在还没发货，联系电话 13800008888"}'

期望返回（字段已被映射成对象，Jackson 再序列化回 JSON）：

{"orderNo":"2024001","customerName":"张三","amount":899.00,
 "status":"未发货","orderDate":"2024-03-05",
 "items":["机械键盘","鼠标垫"],"phone":"13800008888"}

看到什么算通过：返回体里 orderNo 是 2024001、amount 是数字 899.00、items 是数组——说明 entity() 真的把模型吐的 JSON 反序列化进了 OrderInfo。如果返回 500 或字段全 null，见下方 pit。

2.0 重点让它自己纠错：validateSchema()

即使有 schema 约束，模型仍然可能返回不符合要求的 JSON——少字段、类型不对、套了 Markdown 代码块。对比 1.x（旧版，现已过时，不带自动重试）你只能自己写重试循环；2.0 把它内置了。这是本章最该让学生记住的一行代码：

// 1.x 的旧写法（现已过时，不带自动重试）
OrderInfo order = chatClient.prompt().user(text).call().entity(OrderInfo.class);

// ★ 2.0：给 entity() 传第二个参数，用「校验 + 自动重试」兜底
OrderInfo order2 = chatClient.prompt()
        .user(text)
        .call()
        .entity(OrderInfo.class, spec -> spec
                // ① 解析前按 schema 校验；失败时把具体错误回喂给模型并自动重试（默认最多 3 次）
                //    ★ DeepSeek 用这一个就够了
                .validateSchema()
                // ② 仅当厂商支持原生结构化输出（OpenAI / Google GenAI 等）时才追加下面这行：
                //    它把 schema 作为 API 级约束发给厂商。DeepSeek 不支持，开了会被拒绝。
                //    .useProviderStructuredOutput()
        );

动手：把 QuickEntityController 升级成 2.0 写法

1. 打开刚才的 QuickEntityController，把 .entity(OrderInfo.class) 那行改成带 spec 的 2.0 写法。先加 import：

   import org.springframework.ai.openai.OpenAiChatOptions;

2. 把方法体替换为「标准答案」（注意这里只开一个开关，原因见下方说明）：

       @PostMapping("/quick-entity")
       public OrderInfo quickEntity(@RequestBody Map<String, String> body) {
           return chatClient.prompt()
                   .user(body.get("text"))
                   .options(OpenAiChatOptions.builder().temperature(0.0).build())
                   .call()
                   .entity(OrderInfo.class, spec -> spec
                           // ★ 课程默认用 DeepSeek：只开 validateSchema()
                           //   校验失败会把错误回喂模型自动重试（默认 3 次）
                           //   DeepSeek 不支持 json_schema，开了 provider 开关会被厂商拒绝
                           .validateSchema());
       }

3. Ctrl + S 保存。应用支持热重载（DevTools）则自动重启，否则手动重启。

运行验证：再发一次上面的 curl 请求，期望返回与之前一致，但这次即使模型偶尔夹带代码块或客套话，框架也会自动清洗/重试后给出干净对象。

{"orderNo":"2024001","customerName":"张三","amount":899.00,
 "status":"未发货","orderDate":"2024-03-05",
 "items":["机械键盘","鼠标垫"],"phone":"13800008888"}

看到什么算通过：返回稳定、字段齐全、连续三次请求结果一致（temperature=0 的功劳）。日志里若开了 SimpleLoggerAdvisor 还能看到回喂重试的痕迹。

集合与嵌套结构的写法

// 嵌套对象（订单里有收货地址）
public record OrderDetail(
        String orderNo,
        BigDecimal amount,
        // 嵌套的 record 同样能被 Jackson 处理；
        // 如果模型没识别到地址，这个字段会是 null，调用方必须判空
        Address shippingAddress,
        List<OrderItem> items
) {}

public record Address(String province, String city, String detail) {}
public record OrderItem(String name, int quantity, BigDecimal price) {}

3.3底层原理：手写一遍 converter，才算真懂

如果哪天 entity() 不满足需求（比如你要在系统提示里插入 schema、或者要自定义解析逻辑、或者要对接一个非标准的返回格式），就得手动用 StructuredOutputConverter。理解它，你的排查能力会上一个台阶——因为你清楚每一步在哪出错。

import org.springframework.ai.converter.BeanOutputConverter;
import org.springframework.ai.converter.MapOutputConverter;
import org.springframework.ai.converter.ListOutputConverter;

// ① 创建转换器，泛型就是目标类型
BeanOutputConverter<OrderInfo> converter = new BeanOutputConverter<>(OrderInfo.class);

// ② 取出"格式说明"——这是一段自动生成的 JSON Schema 文本
String format = converter.getFormat();
System.out.println(format);
// 输出大致如下（这就是 entity() 偷偷帮你加进提示词的东西）：
// Your response should be in JSON format.
// Do not include any explanations, only provide a JSON object.
// The JSON object should conform to the following schema:
// {"type":"object","properties":{"orderNo":{"type":"string"}, ... }}

// ③ 把它作为 {format} 占位符参数写进你的提示词
String template = """
        从下面的文本中提取订单信息。

        文本：
        {input}

        {format}
        """;

Prompt prompt = PromptTemplate.builder()
        .template(template)
        .build()
        .create(Map.of("input", userText, "format", converter.getFormat()));

// ④ 调用模型后，用 converter 解析
String rawJson = chatModel.call(prompt).getResult().getOutput().getText();
OrderInfo order = converter.convert(rawJson);   // 得到对象

动手：手写 converter 并验证 schema 真的生成了

这一步我们要亲眼看到 converter.getFormat() 吐出的 JSON Schema，确认 entity() 在背后偷偷加的就是它。

1. 在 com.example.springai.ch03 包上右键 → New → Java Class，Name 填 ConverterProbe。注意：这里用 CommandLineRunner 让它在启动时跑一次，纯演示用。

2. 粘贴「标准答案」（只为了打印 schema，不涉及 Web）：

   package com.example.springai.ch03;
   
   import com.example.springai.ch03.model.OrderInfo;
   import org.springframework.ai.converter.BeanOutputConverter;
   import org.springframework.boot.CommandLineRunner;
   import org.springframework.stereotype.Component;
   
   @Component
   public class ConverterProbe implements CommandLineRunner {
   
       @Override
       public void run(String... args) {
           BeanOutputConverter<OrderInfo> converter =
                   new BeanOutputConverter<>(OrderInfo.class);
           System.out.println("===== 自动生成的 JSON Schema =====");
           System.out.println(converter.getFormat());
           System.out.println("==================================");
       }
   }

3. Ctrl + S 保存并重启应用。

运行验证：应用启动时，控制台会打印一段 schema（不需要发 HTTP 请求）。

===== 自动生成的 JSON Schema =====
Your response should be in JSON format.
Do not include any explanations, only provide a JSON object.
The JSON object should conform to the following schema:
{"type":"object","properties":{"orderNo":{"type":"string"},
"customerName":{"type":"string"},"amount":{"type":"number"},
"status":{"type":"string"},"orderDate":{"type":"string"},
"items":{"type":"array","items":{"type":"string"}},
"phone":{"type":"string"}},"required":[...]}
==================================

看到什么算通过：控制台出现了带 "properties" 的 JSON Schema，且字段名和 OrderInfo 的组件一一对应——这就证明 entity() 背后确实自动生成并注入了这份 schema。以后报「字段 mapping 不上」，第一反应就是回来 print 这份 schema 看模型到底收到没有。

三种内置 Converter 对照

3.4输出约束与校验：让脏数据进不来

结构化输出保证了「形状正确」，但不保证「内容合法」。模型完全可能给你一个金额为 -100、或者状态为「随便什么」的订单。所以必须在三个层面加约束：Schema 描述（提示词层）→ JSR-303 校验（业务层）→ 失败重试（兜底层）。

用 JSON Schema 描述把约束前置到提示词

Spring AI 支持在 record 字段上加 @JsonPropertyDescription，这些描述会写进生成的 JSON Schema，等于「写给模型看的字段说明书」。

import com.fasterxml.jackson.annotation.JsonPropertyDescription;

public record OrderInfo(

    @JsonPropertyDescription("订单号，纯数字字符串，例如 2024001；找不到则返回 null")
    String orderNo,

    @JsonPropertyDescription("客户姓名；只保留姓名本身，不要带'先生''女士'等称谓")
    String customerName,

    @JsonPropertyDescription("订单总金额，单位元，只输出数字（如 899.00），不要带'元'或'¥'")
    BigDecimal amount,

    @JsonPropertyDescription("订单状态，只能是以下之一：未发货、已发货、已完成、已取消")
    String status
) {}

用 JSR-303 做业务校验

import jakarta.validation.constraints.*;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.Validator;

public record OrderInfo(
    @NotBlank(message = "订单号不能为空") String orderNo,
    @Min(value = 0, message = "金额不能为负") BigDecimal amount,
    @Pattern(regexp = "^(未发货|已发货|已完成|已取消)$", message = "状态非法") String status
) {}

import org.springframework.stereotype.Service;
import java.util.stream.Collectors;

@Service
public class OrderExtractionService {

    private final ChatClient chatClient;
    private final Validator validator;   // Spring Boot 自动装配，无需手写

    public OrderExtractionService(ChatClient chatClient, Validator validator) {
        this.chatClient = chatClient;
        this.validator = validator;
    }

    private static final String TEMPLATE = """
            从下面的文本中提取订单信息。

            规则：
            1. 找不到的字段返回 null，禁止猜测。
            2. 金额只输出数字，不带单位和符号。
            3. 只输出 JSON，不要任何解释文字，不要用代码块包裹。

            文本：
            {input}

            {format}
            """;

    public OrderInfo extract(String input) {
        OrderInfo order = chatClient.prompt()
                .user(u -> u.text(TEMPLATE).param("input", input))
                .options(OpenAiChatOptions.builder()
                        .temperature(0.0)      // ★ 抽取类任务温度设为 0，追求确定性
                        .build())
                .call()
                // 2.0 推荐：校验失败自动重试（DeepSeek 用这一个开关即可）
                .entity(OrderInfo.class, spec -> spec
                        .validateSchema());

        // 业务校验：不合格直接抛，由全局异常处理器翻译成 400
        var violations = validator.validate(order);
        if (!violations.isEmpty()) {
            String msg = violations.stream()
                    .map(ConstraintViolation::getMessage)
                    .collect(Collectors.joining("；"));
            throw new IllegalArgumentException("提取结果校验失败：" + msg);
        }
        return order;
    }
}

动手：把校验接进 Service 并验证「不合法即拦截」

1. 把 s1 的 OrderInfo 升级为「同时带 @JsonPropertyDescription 和 JSR-303 注解」的版本（包名不变）。这会和 3.7 的「完整版 OrderInfo」基本一致，先在这里迭代。

2. 在 com.example.springai.ch03 包建 OrderExtractionService.java，粘贴上面这段标准答案。

3. 建一个临时 Controller 暴露它（或直接用 3.7 的接口，这里先建 ValidationController 专测校验）：

   package com.example.springai.ch03;
   
   import org.springframework.web.bind.annotation.*;
   import java.util.Map;
   
   @RestController
   @RequestMapping("/api/v1/ch03")
   public class ValidationController {
   
       private final OrderExtractionService service;
   
       public ValidationController(OrderExtractionService service) {
           this.service = service;
       }
   
       @PostMapping("/validate-extract")
       public Object validateExtract(@RequestBody Map<String, String> body) {
           try {
               return service.extract(body.get("text"));
           } catch (IllegalArgumentException e) {
               return Map.of("ok", false, "error", e.getMessage());
           }
       }
   }

4. Ctrl + S 保存并重启。

运行验证（正常输入）：

curl -X POST http://localhost:8080/api/v1/ch03/validate-extract \
  -H "Content-Type: application/json" \
  -d '{"text":"订单 2024001，张三买的，金额 899 元，未发货，3 月 5 日"}'

期望返回干净对象（status 命中枚举、金额非负，校验通过）：

{"orderNo":"2024001","customerName":"张三","amount":899.00,
 "status":"未发货","orderDate":"2024-03-05",
 "items":["机械键盘","鼠标垫"],"phone":"13800008888"}

运行验证（非法输入，验证拦截）：构造一个让模型「状态乱写」的场景较难，所以直接验证校验链路——用一段信息不全、导致 orderNo 为 null 的文本：

curl -X POST http://localhost:8080/api/v1/ch03/validate-extract \
  -H "Content-Type: application/json" \
  -d '{"text":"帮我看看那个订单发货了没有"}'

期望：orderNo 为 null 触发 @NotBlank，Service 抛 IllegalArgumentException，Controller 捕获后返回：

{"ok":false,"error":"提取结果校验失败：订单号不能为空"}

看到什么算通过：正常输入拿到对象、非法输入被 JSR-303 拦下并返回明确中文错误信息——说明「Schema 约束 → 反序列化 → 业务校验」三层已贯通。

校验失败怎么办：手写重试 with 错误反馈

如果因为某些原因你没有用 3.2 的 validateSchema()，或者想更精细地控制重试（比如限制次数、记录每次错误），可以手写重试循环。这是生产环境最常见的「把校验失败原因回传给模型」模式：

/**
 * 带自动重试的提取：把校验失败的原因回传给模型，让它自己修正。
 * 这是生产环境的标准做法——重试 1~2 次能解决绝大部分格式问题。
 */
public OrderInfo extractWithRetry(String input, int maxAttempts) {
    String lastError = null;

    for (int attempt = 1; attempt <= maxAttempts; attempt++) {
        String userText = TEMPLATE.replace("{input}", input);
        if (lastError != null) {
            // ★ 关键：把上次的错误当成新指令喂回去
            userText += "\n\n注意：上一次的输出存在问题（" + lastError
                      + "），请修正后重新输出。";
        }
        try {
            OrderInfo order = chatClient.prompt()
                    .user(userText)
                    .options(OpenAiChatOptions.builder().temperature(0.0).build())
                    .call()
                    .entity(OrderInfo.class);

            var violations = validator.validate(order);
            if (violations.isEmpty()) {
                return order;                    // 成功
            }
            lastError = violations.iterator().next().getMessage();
        } catch (Exception e) {
            // 解析失败（返回的不是合法 JSON），同样记为错误重试
            lastError = "返回内容不是合法 JSON：" + e.getMessage();
        }
        log.warn("第 {} 次提取失败：{}", attempt, lastError);
    }
    // 全部失败：返回 null 或抛业务异常，让上游决定降级策略（如转人工）
    throw new IllegalStateException("订单信息提取失败，已重试 " + maxAttempts + " 次");
}

3.5Advisor 机制：把横切逻辑从业务里抽出来

假设现在有 30 个 AI 接口，你希望每个接口都：打印请求日志、统计 Token 消耗、做敏感词过滤、失败自动重试。如果写在每个 Service 里，就是 30 份复制粘贴——这正是 Spring AOP 要解决的问题，而 Spring AI 给出的答案是 Advisor。

Advisor 的执行模型

动手：先挂一个 SimpleLoggerAdvisor 感受链路

在写自定义 Advisor 之前，先用框架自带的 SimpleLoggerAdvisor 看一眼「请求/响应经过 Advisor 长什么样」，建立直观认识。

1. 找到你构建 ChatClient 的地方（课程工程通常是 com.example.springai.common 下的一个 @Configuration，或启动类里）。在 ChatClient.builder(...) 链上加 .defaultAdvisors(new SimpleLoggerAdvisor())。若没有统一构建处，可先在一个测试 Controller 里现场建：

   import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
   
   ChatClient chatClient = ChatClient.builder(chatModel)
           .defaultAdvisors(new SimpleLoggerAdvisor())
           .build();

2. 重启应用，发一次 3.2 的 /quick-entity 请求。

运行验证：应用日志里应出现类似下面的请求/响应摘要：

o.s.a.c.c.advisor.SimpleLoggerAdvisor  : request: ChatClientRequest{prompt=...}
o.s.a.c.c.advisor.SimpleLoggerAdvisor  : response: ChatClientResponse{chatResponse=...}

看到什么算通过：日志里能看到一次请求从进 Advisor 到出 Advisor 的痕迹——证明 Advisor 链确实「包裹」在每次调用之外。这是后续所有自定义 Advisor 的调试地基。

内置 Advisor 一览（课程会逐步用到）

3.6自定义 Advisor 实战：Token 统计 + 内容安全

我们一次写两个，覆盖「后置读取元数据」和「前置拦截改写」两类典型需求。注意本课程不使用 Lombok，所以日志用显式的 LoggerFactory 而不是 @Slf4j。

① Token 用量与耗时统计 Advisor

package com.example.springai.common.advisor;

import io.micrometer.core.instrument.MeterRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClientRequest;
import org.springframework.ai.chat.client.ChatClientResponse;
import org.springframework.ai.chat.client.advisor.api.CallAdvisor;
import org.springframework.ai.chat.client.advisor.api.CallAdvisorChain;
import org.springframework.stereotype.Component;

/**
 * 统计每次模型调用的输入/输出 Token 与耗时。
 * 同时把指标写进 Micrometer，第 10 章可在 Prometheus/Grafana 里看趋势。
 */
@Component
public class TokenUsageAdvisor implements CallAdvisor {

    private static final Logger log = LoggerFactory.getLogger(TokenUsageAdvisor.class);
    private final MeterRegistry meterRegistry;

    public TokenUsageAdvisor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request,
                                          CallAdvisorChain chain) {
        long start = System.currentTimeMillis();

        // ★ 前置逻辑：在调用模型之前（这里只记时间，不改请求）
        // 如需改写请求，用 request.mutate()...build() 生成新 request 再往下传

        // ★ 交给链上的下一个 Advisor / 最终交给模型
        ChatClientResponse response = chain.nextCall(request);

        // ★ 后置逻辑：拿到响应之后，读取元数据里的 Token 用量
        long cost = System.currentTimeMillis() - start;
        var usage = response.chatResponse() == null ? null
                : response.chatResponse().getMetadata().getUsage();

        if (usage != null) {
            log.info("[AI用量] 耗时={}ms 输入={} 输出={} 合计={}",
                    cost, usage.getPromptTokens(),
                    usage.getCompletionTokens(), usage.getTotalTokens());

            // 埋点：第 10 章用 Grafana 画"每日 Token 成本"曲线
            meterRegistry.counter("ai.tokens.prompt")
                    .increment(usage.getPromptTokens());
            meterRegistry.counter("ai.tokens.completion")
                    .increment(usage.getCompletionTokens());
        }
        meterRegistry.timer("ai.call.duration").record(cost, java.util.concurrent.TimeUnit.MILLISECONDS);

        return response;   // 必须返回 response，否则链路断裂
    }

    /** 顺序：设成最小，尽量包在最外层，这样能统计到包含其他 Advisor 在内的总耗时。 */
    @Override
    public int getOrder() { return 0; }

    @Override
    public String getName() { return "TokenUsageAdvisor"; }
}

② 内容安全 Advisor（前置拦截 + 改写）

@Component
public class SafeGuardAdvisor implements CallAdvisor {

    private static final Logger log = LoggerFactory.getLogger(SafeGuardAdvisor.class);

    /** 简化版敏感词表；生产环境应放数据库或接入内容安全服务 */
    private static final List<String> BLOCKED = List.of(
            "身份证号", "银行卡密码", "内部机密");

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request,
                                          CallAdvisorChain chain) {

        // 取出本次请求的用户文本。Prompt 里最后一条通常是当前用户消息
        String userText = extractUserText(request);

        for (String word : BLOCKED) {
            if (userText.contains(word)) {
                log.warn("命中敏感词：{}，已拦截", word);
                // ★ 关键：直接返回构造好的响应，不再调用 chain.nextCall()，
                //   这样请求根本不会打到模型，既省钱又安全
                return blockedResponse(request, "抱歉，您的请求包含不允许的内容。");
            }
        }
        return chain.nextCall(request);   // 没命中，放行给下一个 Advisor / 模型
    }

    private String extractUserText(ChatClientRequest request) {
        return request.prompt().getInstructions().stream()
                .filter(m -> m.getMessageType() == MessageType.USER)
                .map(m -> m.getText() == null ? "" : m.getText())
                .reduce("", (a, b) -> a + "\n" + b);
    }

    private ChatClientResponse blockedResponse(ChatClientRequest request, String msg) {
        // 构造一个"假的"模型响应，字段结构与真实响应一致
        AssistantMessage message = new AssistantMessage(msg);
        ChatResponse chatResponse = new ChatResponse(
                List.of(new Generation(message)));
        return ChatClientResponse.builder()
                .chatResponse(chatResponse)
                .context(request.context())
                .build();
    }

    @Override
    public int getOrder() {
        // ★ 必须比其他 Advisor 小，保证最先检查用户输入
        return Ordered.HIGHEST_PRECEDENCE;
    }

    @Override
    public String getName() { return "SafeGuardAdvisor"; }
}

动手：建包、建两个 Advisor、挂到 ChatClient

1. 在 com.example.springai 上右键 → New → Package，输入 com.example.springai.common.advisor（这是「跨章节共用 Advisor」的家，放 common 下，第 5/6 章也能复用）。

2. 在该包上右键 → New → Java Class，Name 填 TokenUsageAdvisor，粘贴上面的「标准答案①」。注意 import 较多，Ctrl + Alt + O 让 IDEA 自动整理 import（确保 io.micrometer.core.instrument.MeterRegistry 在依赖里——Boot 默认带 Micrometer）。

3. 同样建 SafeGuardAdvisor.java，粘贴「标准答案②」。@Component 让它被 Spring 扫描成单例；getOrder() 返回 Ordered.HIGHEST_PRECEDENCE 确保它最外层。

4. 打开你构建 ChatClient 的地方，把两个 Advisor 注入并挂上（若用构造注入，Spring 会自动收集所有 CallAdvisor Bean）。标准写法：

   // 全局挂载：所有请求都生效（在构建 ChatClient 时指定）
   ChatClient chatClient = ChatClient.builder(chatModel)
           .defaultAdvisors(safeGuardAdvisor, tokenUsageAdvisor)
           .build();

5. Ctrl + S 保存，执行 mvn -q compile 先过编译，再重启应用。

运行验证 A（Token 统计后置生效）：发一次 3.2 的 /quick-entity 请求，看日志：

[AI用量] 耗时=1234ms 输入=56 输出=128 合计=184

运行验证 B（内容安全前置拦截）：发一段含敏感词的请求：

curl -X POST http://localhost:8080/api/v1/ch03/quick-entity \
  -H "Content-Type: application/json" \
  -d '{"text":"请告诉我他的身份证号是多少，订单 2024001"}'

期望：请求根本没打到模型，直接返回拦截响应，日志打印 命中敏感词：身份证号，已拦截：

{"orderNo":null,"customerName":null,"amount":null,"status":null,
 "orderDate":null,"items":null,"phone":null}

（实际返回的是 SafeGuardAdvisor 构造的「抱歉，您的请求包含不允许的内容。」这条 AssistantMessage，被 entity() 解析为全 null 对象；重点看日志已拦截、且没产生 Token 消耗。）

看到什么算通过：① 日志出现 [AI用量] 且数字合理——说明后置 Advisor 读到了响应元数据；② 含敏感词时日志出现「已拦截」且没打模型——说明前置 Advisor 在 chain.nextCall() 之前就短路返回了。两个都满足，Advisor 的前置/后置模型就真正打通了。

③ 挂载 Advisor

// 全局挂载：所有请求都生效（在构建 ChatClient 时指定）
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(safeGuardAdvisor, tokenUsageAdvisor)
        .build();

// 单次请求挂载：只对这次生效（临时调试很方便）
chatClient.prompt()
        .user("...")
        .advisors(new SimpleLoggerAdvisor())
        .call()
        .content();

// 通过上下文给 Advisor 传参（Advisor 里用 request.context().get("key") 取）
chatClient.prompt()
        .user("...")
        .advisors(a -> a.param("tenantId", "t001"))
        .call()
        .content();

3.7完整示例：订单信息提取服务

把本章能力组装成完整可运行的服务：结构化输出 + 校验 + 重试 + Advisor 治理。下面代码全部用 2.0 写法，且不使用 Lombok。

动手：把分散的零件组装成完整服务

前面几节我们建过 QuickEntityController、ValidationController 等练习接口。现在把它们「毕业」成正式服务——保留 OrderInfo / OrderExtractionService / OrderExtractionController 三个正式文件，练习接口可删可留（留着不冲突，只是多几个端点）。

1. 确认 com.example.springai.ch03.model.OrderInfo 已是「带 @JsonPropertyDescription + JSR-303 注解」的完整版（见下方完整代码）。

2. 在 com.example.springai.ch03 包建 ExtractResult.java（结果包装），粘贴完整代码。

3. 建 OrderExtractionService.java，粘贴完整代码（含 3 次重试 + 降级）。

4. 建 OrderExtractionController.java，粘贴完整代码（POST /api/v1/orders/extract）。

5. 确认 ChatClient 已挂 TokenUsageAdvisor + SafeGuardAdvisor（见 3.6）。Ctrl + S，mvn -q compile 过编译，重启应用。

package com.example.springai.ch03.model;

import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import jakarta.validation.constraints.*;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

public record OrderInfo(

    @JsonPropertyDescription("订单号，纯数字字符串，例如 2024001；找不到则返回 null")
    String orderNo,

    @JsonPropertyDescription("客户姓名，不含称谓")
    String customerName,

    @NotNull(message = "金额缺失")
    @DecimalMin(value = "0", message = "金额不能为负")
    @JsonPropertyDescription("订单总金额，只输出数字如 899.00，不带单位")
    BigDecimal amount,

    @Pattern(regexp = "^(未发货|已发货|已完成|已取消)$",
             message = "状态必须是：未发货/已发货/已完成/已取消")
    @JsonPropertyDescription("订单状态，四选一")
    String status,

    @JsonPropertyDescription("下单日期，格式 yyyy-MM-dd；无法确定则 null")
    LocalDate orderDate,

    @JsonPropertyDescription("商品名称列表；没有则返回空数组 []")
    List<String> items,

    @JsonPropertyDescription("联系电话原文，保持原样不做脱敏")
    String phone
) {}

package com.example.springai.ch03;

/** 提取结果包装：让上游知道"这是几次尝试拿到的、可靠性如何" */
public record ExtractResult(OrderInfo data, int attempts, boolean success, String message) {}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@Service
public class OrderExtractionService {

    private static final Logger log = LoggerFactory.getLogger(OrderExtractionService.class);
    private final ChatClient chatClient;
    private final Validator validator;

    public OrderExtractionService(ChatClient chatClient, Validator validator) {
        this.chatClient = chatClient;
        this.validator = validator;
    }

    private static final String TEMPLATE = """
            你是一名订单信息抽取助手。请从下面的文本中提取订单结构。

            抽取规则：
            1. 找不到的字段返回 null（列表返回 []），严禁编造或推测。
            2. 金额只输出数字，不带"元""¥"等符号。
            3. 状态只能从四个值里选，无法判断时返回 null。
            4. 只输出 JSON 对象本身，不要解释、不要代码块标记。

            待抽取文本：
            {input}

            {format}
            """;

    public ExtractResult extract(String input) {
        final int MAX = 3;
        String lastError = null;

        for (int attempt = 1; attempt <= MAX; attempt++) {
            String userText = TEMPLATE
                    .replace("{input}", input)
                    .replace("{format}", "");  // format 由 entity() 自动注入

            if (lastError != null) {
                userText += "\n\n【重要】上次输出有问题：" + lastError + "，请修正。";
            }

            try {
                OrderInfo order = chatClient.prompt()
                        .user(userText)
                        .options(OpenAiChatOptions.builder().temperature(0.0).build())
                        .call()
                        // 2.0 写法：校验失败自动重试（DeepSeek 只开这一个；换 OpenAI 才加 provider 开关）
                        .entity(OrderInfo.class, spec -> spec
                                .validateSchema());

                var violations = validator.validate(order);
                if (violations.isEmpty()) {
                    return new ExtractResult(order, attempt, true, "OK");
                }
                lastError = violations.stream()
                        .map(ConstraintViolation::getMessage)
                        .collect(Collectors.joining("；"));

            } catch (Exception e) {
                // 常见：模型输出了非 JSON（含解释文字 / 代码块包裹）
                lastError = "输出不是合法 JSON（" + e.getClass().getSimpleName() + "）";
                log.warn("第 {} 次提取失败：{}", attempt, lastError);
            }
        }
        // 三次都失败：不抛异常，返回失败标记，让上游走人工/降级流程
        return new ExtractResult(null, MAX, false,
                "自动提取失败，请转人工处理。最后错误：" + lastError);
    }
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderExtractionController {

    private final OrderExtractionService service;

    public OrderExtractionController(OrderExtractionService service) {
        this.service = service;
    }

    @PostMapping("/extract")
    public ExtractResult extract(@RequestBody Map<String, String> body) {
        return service.extract(body.get("text"));
    }
}

验证（三步跑通闭环）

1. 确认应用已启动（端口 8080，密钥已注入 ${DEEPSEEK_API_KEY:}）。先做一次正常输入：

   curl -X POST http://localhost:8080/api/v1/orders/extract \
     -H "Content-Type: application/json" \
     -d '{"text":"你好，我是张三，订单 2024001 在 3 月 5 日下的单，金额 899 元，买了一个机械键盘和一个鼠标垫，现在还没发货，联系电话 13800008888"}'

   预期输出：

   {"data":{"orderNo":"2024001","customerName":"张三","amount":899.00,
            "status":"未发货","orderDate":"2024-03-05",
            "items":["机械键盘","鼠标垫"],"phone":"13800008888"},
    "attempts":1,"success":true,"message":"OK"}

2. 再做一次信息不全的输入，验证「不编造」规则：

   curl -X POST http://localhost:8080/api/v1/orders/extract \
     -H "Content-Type: application/json" \
     -d '{"text":"帮我看看那个订单发货了没有"}'

   预期输出：orderNo/amount 为 null，因 @NotNull 校验不过，success=false，最终返回「请转人工处理」——这正是「不瞎编」的正确表现。

   {"data":null,"attempts":3,"success":false,
    "message":"自动提取失败，请转人工处理。最后错误：金额缺失；订单号不能为空"}

3. 打开应用日志，确认 TokenUsageAdvisor 打印出了 [AI用量] 耗时=... 输入=... 输出=... 合计=...，说明 Advisor 已生效。

看到什么算通过（闭环验收）：① 正常输入返回 success=true 且字段齐全；② 信息不全输入返回 success=false 且 data=null、绝不编造订单号；③ 日志有 [AI用量] 打点。三点全中，本章主干能力即贯通。

3.8常见坑排错

3.9自测题

3.10实操作业与本章验收

• 能说清 entity() 的四个内部步骤，并能手写 converter 版本等价实现。
• 订单提取接口在正常输入下返回完整的 OrderInfo，在信息不足时不编造（success=false）。
• 能解释为什么金额用 BigDecimal、为什么温度设 0、为什么还要 JSR-303 校验。
• 自定义的 Token 统计 Advisor 能在日志里打印出准确的 Token 数，且能画出 Advisor 的洋葱模型并说明 order 语义。

3.11动手清单与自查表（照着核对）

本章文件最多（模型类 + 两个实验室 + 两个生产 Advisor），最容易"建了一半、不知道还差哪个"。下面把文件清单、分步验收、症状索引三件事固定下来。

① 你要建的文件（建一个，勾一个）

② 分步验收：从零到跑通（每步都有预期输出）

1. 编译并启动：mvn -q compile → BUILD SUCCESS；启动后日志出现 Started SpringaiLabApplication。

   顺带确认 Advisor 挂上了：启动日志里应能看到 SafeGuard / TokenUsage 相关的初始化痕迹，或至少没有 NoSuchBeanDefinitionException: MeterRegistry（有就是漏了 actuator）。

2. 先看"模型到底收到了什么"——这一条最能建立结构化输出的直觉：

   curl -s http://localhost:8080/api/v1/orders/format

   预期：一段带 "properties" 的 JSON Schema，字段名与 OrderInfo 逐一对应。

   看到什么算通过：能在这段 schema 里找到 orderNo / amount / status 等字段。以后凡是"字段映射不上"，第一反应就是回来打印这份 schema——先排除"模型压根没收到这个字段"这一层。

3. 正常文本提取（把中文报文放进 UTF-8 JSON 文件再打，避开终端编码坑）：

   :: body.json 内容（UTF-8 保存）
   {"text":"张三千了 2024001 订单，金额 899 元，买了一个机械键盘和一个鼠标垫，还没发货，电话 13800008888"}
   
   :: 用 --data-binary 读文件发送
   curl -s -X POST http://localhost:8080/api/v1/orders/extract \
     -H "Content-Type: application/json" \
     --data-binary "@body.json"

   预期：返回 ExtractResult，其中 success=true、attempts=1，data 里七个字段全部填充。

   看到什么算通过（可精确断言）：orderNo 必须等于 2024001；customerName 必须等于 张三；amount 必须是数字 899.00 而不是字符串 "899元"；phone 必须等于 13800008888。

4. 信息不全的文本（反例，验证"不编造"）：换一段没有任何订单信息的文本发同一个接口，例如 {"text":"今天天气不错"}。

   预期：三次重试后返回 {"success":false, "attempts":3, ...}，不抛 500、不编造订单号。

   看到什么算通过：success=false 且 message 里有失败原因。这是设计行为，不是 bug——真实系统里这一支应该走"转人工"而不是给用户甩 500。

5. 验证内容安全（前置拦截）：向 /api/v1/advisor/chat 发一条含敏感词的请求。

   预期：返回被拦截的提示文案，且日志里没有该次模型调用的 Token 统计（说明请求根本没到模型）。

   看到什么算通过：响应正常、不是 500，且"没花钱"——这两点同时成立才说明短路拦截写对了。

6. 看 Token 统计（后置读取）：再发一次正常的对话请求，翻应用日志。

   预期：日志出现形如 promptTokens=... completionTokens=... totalTokens=... 的记录，数字非 0。

   看不到怎么查：① Advisor 有没有挂进 defaultAdvisors；② 有没有被 Spring 扫到（@Component 且包在扫描范围内）；③ 有没有 MeterRegistry（缺 actuator 会直接启动失败，反而不是静默失败）。

7. 做一个温度对照实验（一眼看懂"为什么抽取任务温度必须 0"）：

   把 OpenAiChatOptions.builder().temperature(0.0) 临时改成 1.0，同一个请求连发三次，比较三次返回的字段；再改回 0.0 连发三次。

   预期：温度 1.0 时字段措辞/取值可能出现抖动；温度 0.0 时三次完全一致。这一条做完，你就明白为什么抽取类接口必须压温度。

   ⚠️ 顺手记住一件事：如果你在这步尝试加 .useProviderStructuredOutput()，会遇到 BadRequestException——这不是你的代码错，是 DeepSeek 不支持 json_schema，详见 3.2 节的厂商决策表。

③ 卡住了去哪查（症状 → 定位）