CH 07工具调用（Tool Calling）

7.1工具调用的本质：模型只会「举手」，不会「动手」

先用一个比喻理解：模型像一位坐在办公室里的顾问，他知道很多东西，但不能出门。当需要查实时数据时，他会写一张便条（工具名 + 参数）递给你，你跑出去把事情办完，把结果写回来给他，他再基于结果给你最终答复。

为什么这么写（设计意图）：这个比喻不是修辞，而是对 Spring AI 工具调用架构的精确描述。模型的输出里只含「我要调用某个工具、参数是这些」，真正的执行发生在你的 Java 代码里。理解这一点，后面所有的权限、异常处理、成本控制才站得住脚。很多初学者把模型当成「安全边界」，根源就是没建立这个心智模型。

7.2完整时序：为什么一次问答会有两次模型调用

下面这张图描述一次「订单发货时间」问答在 Spring AI 2.0 内部的完整流转。注意：对调用方（你的 Controller）而言只写了一次 .call()，但底层发生了多次模型请求。

▌动手补充：模型返回的 tool_calls 到底长什么样

上面图里第 ① 步说「模型返回：我要调工具」。它返回的其实是一段结构化 JSON（不是自然语言）。看清它，你才能真正理解「模型只举手、不动手」：

# 第 ① 步：模型不直接回答，而是返回 tool_calls（注意 content 是 null）
{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "queryOrderStatus",
        "arguments": "{\"orderNo\":\"2024001\"}"
      }
    }
  ]
}

# 第 ③ 步：你的代码把工具结果包成一条 role=tool 消息回灌
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"status\":\"未发货\",\"promisedDate\":\"2024-03-08\"}"
}

▌运行验证：亲眼看「两次模型请求」——但别只看 DEBUG 日志

光看文字不直观，现在就让你在日志里看到循环。这一步有个坑必须先说清楚，否则你会白等半小时：

正确做法：显式挂一个 SimpleLoggerAdvisor。它是递归 advisor—— 工具循环每迭代一次，请求就会重新流经它一次，所以一次问答会打出两组 request/response：

ChatClient client = ChatClient.builder(chatModel)
        .defaultAdvisors(new SimpleLoggerAdvisor())   // ★ 排 ToolCallingAdvisor 下游，每轮都流经它
        .build();

# 触发一次带工具的问答（接口见 7.7）
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 什么时候发货？"}'

实测日志（一次 curl，节选，注意 request 出现两次）：

20:11:03.349  SimpleLoggerAdvisor : request:  ChatClientRequest[...SystemMessage, UserMessage]
20:11:03.894  SimpleLoggerAdvisor : response: {...}
[OrderTools] orderNo=2024001（模型传参）, userId=u1001（上下文注入）   ← 工具在这一步执行
20:11:03.927  SimpleLoggerAdvisor : request:  ChatClientRequest[... 多了一段工具结果]
20:11:04.306  SimpleLoggerAdvisor : response: {...}

第 2 次请求的 messages 里，能直接看到教材 7.2 那两段 JSON 的真实对应物： AssistantMessage[toolCalls=[ToolCall[id=call_00_..., name=queryOrderStatus, arguments={"orderNo":"2024001"}]]] 以及随后的 ToolResponseMessage。

看到什么算通过（可数，不用猜）：一次 curl 对应的日志里，同一线程 request: 出现 2 次即为通过——1 次是「模型直接回答」，2 次才是「调了工具又问了一遍」。 配合 curl 返回了真实的发货说明（不是报错、不是空串），两条一起过才算真的跑通。

7.3@Tool 注解：把 Java 方法暴露给模型

把一个普通 Java 方法变成模型可用的工具，核心就是 @Tool 注解（包 org.springframework.ai.tool.annotation.Tool）。下面这个例子包含本章最重要的三个安全要点：描述怎么写、参数怎么描述、身份怎么取。

▌动手：创建 OrderTools 类

1. 在 IDEA 左侧 Project 视图，展开 src/main/java/com/example/springai。若没有 ch07 包，右键 com.example.springai → New → Package，输入 ch07 回车。
2. 右键 ch07 包 → New → Java Class，名字精确填 OrderTools，回车。
3. 清空自动生成的内容，把下方整段代码粘贴进去（含 import），按 Ctrl/Cmd+S 保存。
4. 确认 IDEA 没有红色波浪线：@Tool、@ToolParam 能从 org.springframework.ai.tool.annotation 解析到（若报红，多半是依赖或版本不对，回头对照 ch00 版本表）。

package com.example.springai.ch07;

import org.springframework.ai.chat.model.ToolContext;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;

@Component                              // 必须是 Spring bean，Spring AI 才能扫描到它
public class OrderTools {

    /** 演示用假数据；真实项目换成 Repository / Mapper。key = 订单号 */
    private static final Map<String, Order> DB = Map.of(
            "2024001", new Order("2024001", "u1001", "未发货", LocalDate.of(2026, 10, 28)),
            "2024002", new Order("2024002", "u1001", "已发货", LocalDate.of(2026, 10, 19)),
            "2024003", new Order("2024003", "u2002", "已发货", LocalDate.of(2026, 10, 20)));

    /**
     * 一个工具方法。三个要素决定模型能不能用好它：
     * ① 方法名     → 模型看到的工具名（尽量用动词+名词，语义清晰）
     * ② description → ★ 最重要！模型靠它决定"什么时候用这个工具、不用那个"
     * ③ 参数描述    → 模型靠它知道"这个参数从用户的话里怎么抽"
     */
    @Tool(description = """
            查询指定订单号的当前状态与预计发货时间。
            使用时机：当用户询问某个订单的发货情况、物流状态、是否已发货时调用。
            不要用于：查询商品信息、退款进度、账户余额。
            参数约束：orderNo 为纯数字订单号，例如 2024001。
            """)                          // 文本块（Java 15+），多行描述更清晰
    public OrderStatus queryOrderStatus(
            @ToolParam(description = "订单号，纯数字字符串，例如 2024001")
            String orderNo,                   // ← 模型能看见、能填的参数
            ToolContext toolContext) {        // ← 模型看不见的上下文（7.5 详讲）

        // ★★★ 这里就是安全边界！身份只从服务端上下文取，绝不作为工具参数让模型填
        String currentUser = (String) toolContext.getContext().get("userId");
        if (currentUser == null || currentUser.isBlank()) {
            // 工具内部的 null 检查是最后一道防线：调用方忘了传 toolContext 时，这是唯一的兜底
            return new OrderStatus(orderNo, "ERROR", null, "缺少登录身份，无法查询订单");
        }

        Order order = DB.get(orderNo);
        if (order == null || !order.ownerId().equals(currentUser)) {
            // 返回明确错误，而不是抛异常——让模型能理解并礼貌回复用户；
            // 越权时也回"不存在"，不透露"这单存在但不是你的"（少给攻击者一分确认信息）
            return new OrderStatus(orderNo, "NOT_FOUND", null,
                    "系统中不存在该订单，或该订单不属于当前用户");
        }
        return new OrderStatus(order.orderNo(), order.status(), order.promisedDate(), "查询成功");
    }

    /** 无参工具也可以（模型不需要传任何参数）。典型场景：获取"今天日期"这类模型自己不知道的信息。 */
    @Tool(description = """
            获取当前的真实日期与时间。
            使用时机：用户说"今天""本周""最近""现在"等相对时间时必须先调用，否则模型会算错日期。
            不要用于：查询订单、商品等业务数据。
            """)
    public String currentDateTime() {
        return LocalDateTime.now()
                .format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss EEEE"));
    }

    /** 工具的返回类型：建议用 record，字段名会进入模型的上下文 */
    public record OrderStatus(String orderNo, String status,
                                LocalDate promisedDate, String message) {}

    /** 内部数据载体，不暴露给模型 */
    private record Order(String orderNo, String ownerId, String status, LocalDate promisedDate) {}
}

为什么这么写：@Tool 的 description 不是给人看的注释，而是会被序列化进发给模型的「工具定义」里——模型完全靠它来决策。所以描述要写成「给模型的说明书」：做什么、何时用、何时不用、参数长什么样。返回类型用 record 是因为它的字段名天然成为 JSON 的 key，进入模型上下文后语义清晰。

写工具描述的「四要素」模板

▌运行验证：编译通过只是「必要条件」，不是通过判据

# 在 pom.xml 所在目录执行（只编译，不运行，最快的反馈）
mvn -q compile

期望输出：命令结束、无红色报错（-q 下成功时几乎无输出）。

真正的判据（装好 ChatClient 之后，见 7.7）：看一次请求的「底层产物」。最省事的做法是在工具方法第一行打一行日志：

// OrderTools.queryOrderStatus 第一行
System.out.println("[OrderTools] orderNo=" + orderNo + ", userId=" + currentUser);

然后问一句「订单 2024001 什么时候发货？」——

• 通过：控制台出现 [OrderTools] orderNo=2024001, userId=u1001，且回答里是真实的发货日期；
• 没通过：没有这行日志 = 模型压根没调工具（这时别去改工具内部逻辑，去查 description 和是否注册上了）；
• 更进一步可以打印 ChatResponse 的 finishReason，工具调用那一轮应是 TOOL_CALLS、text 为空串（见 7.7 的 trace 入口）。

7.4注册工具的三种方式

工具类（带 @Tool 的 bean）写好后，还要把它「挂到」某个 ChatClient 上，模型才能用到。注意：标题虽写「三种方式」，但生产里实际有六种粒度可选——前三种是注册入口的区别，后三种是 2.0 新增或进阶能力，都讲清楚，方便你按场景选。

▌动手：创建 AssistantConfig 装配 ChatClient

1. 右键 ch07 包 → New → Java Class，名字填 AssistantConfig。
2. 粘贴下方「方式三（默认挂载）」代码（它最贴近生产写法），保存。
3. 确认 OrderTools、DateTimeTools 能注入——即这两个类都已用 @Component 标注且被 Spring 扫描到。

// ---------- 方式一：直接传对象（最简，适合手工指定） ----------
String answer = chatClient.prompt()
        .user("订单 2024001 发货了吗？")
        .tools(new OrderTools(), new DateTimeTools())   // 传实例
        .call()
        .content();

// ---------- 方式二：用 ToolCallbacks 显式转换（可控性更强） ----------
import org.springframework.ai.support.ToolCallbacks;

ToolCallback[] callbacks = ToolCallbacks.from(new OrderTools(), new DateTimeTools());

String answer2 = chatClient.prompt()
        .user("订单 2024001 发货了吗？")
        .toolCallbacks(callbacks)
        .call()
        .content();

// ---------- 方式三：默认挂载（推荐，业务代码最干净） ----------
@Bean
public ChatClient orderChatClient(ChatModel chatModel,
                                    OrderTools orderTools,
                                    DateTimeTools dateTimeTools) {
    return ChatClient.builder(chatModel)
            // 所有通过这个 client 发起的请求都能用这些工具
            .defaultTools(orderTools, dateTimeTools)
            .defaultSystem("你是订单助手。涉及订单数据时必须调用工具查询，禁止凭记忆回答。")
            .build();
}

三种方式的选择

方式四（2.0 新增重点）：函数式工具用 FunctionToolCallback

如果你要暴露的不是一个带 @Tool 的 POJO 方法，而是一个现成的 Function、lambda 或方法引用， 2.0 用 FunctionToolCallback。这是 1.x 里 FunctionCallback + toolNames() 的替代品：

// ❌ 1.x 的写法（2.0 已删除，编译不过）
// @Bean @Description("Get the weather in location")
// Function currentWeather() { return weatherService::getWeather; }
// chatClient.prompt().toolNames("currentWeather");   ← toolNames 没了

// ✅ 2.0：注册成显式的 ToolCallback bean
@Configuration(proxyBeanMethods = false)
class WeatherToolsConfig {

    @Bean
    ToolCallback currentWeather(WeatherService weatherService) {
        return FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
                .description("查询指定城市的当前天气")
                // ★ inputType 决定生成的 JSON Schema，必须给，否则模型不知道该传什么
                .inputType(WeatherRequest.class)
                .build();
    }
}

// 注入后按名字使用（不再靠字符串解析）
@Autowired ToolCallback currentWeather;

chatClient.prompt()
        .user("北京现在天气怎么样？")
        .tools(currentWeather)      // 直接传工具对象
        .call()
        .content();

三种定义风格最终都产出 ToolCallback，走同一条循环，可以随意混用：

方式五：工具太多时，打开渐进式工具披露

这是 2.0 最实用的新能力之一。原理：不再把全部工具定义一次性塞给模型， 而是给模型一个内置的 toolSearchTool，让它用自然语言先"检索"出相关工具， 再只把这几个工具的定义发过去。

<!-- 加一个 starter 即可，不需要改任何 Java 代码 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-tool-search-advisor</artifactId>
</dependency>

# 打开开关
spring:
  ai:
    chat:
      client:
        tool-search-advisor:
          enabled: true
          # 索引类型：
          #   regex  —— 默认，零额外依赖，按关键词匹配
          #   lucene —— 需要 org.apache.lucene:lucene-core，检索质量更好
          #   vector —— 需要 classpath 上有 VectorStore，语义检索最准
          tool-index-type: regex

方式六：给工具调用加上次数上限（防失控）

2.0 的 DefaultToolCallingManager 内置了调用次数保护，默认就已生效： 单个工具每轮最多 40 次，所有工具合计最多 150 次。超过会抛 ToolCallLimitExceededException。

# 用配置调整
spring:
  ai:
    tools:
      limits:
        max-calls-per-tool-default: 40     # -1 表示不限制
        max-total-tool-calls: 150
        on-limit-exceeded: THROW           # 或 RETURN_ERROR_RESPONSE（把错误当结果回给模型）

// 或者编程式精细控制
ToolCallingManager manager = ToolCallingManager.builder()
        .maxCallsPerTool(40)
        .maxCallsPerTool("search", 10)              // 给某个工具单独设更小的上限
        .excludeToolFromLimit("getCurrentDateTime") // 这个工具不限制
        .maxTotalToolCalls(150)
        .build();

// 装到自己的 ToolCallingAdvisor 上（会替换掉自动注册的那个）
@Bean
ToolCallingAdvisor.Builder<?> toolCallingAdvisorBuilder() {
    return ToolCallingAdvisor.builder()
            .toolCallingManager(manager)
            .advisorOrder(Ordered.HIGHEST_PRECEDENCE + 300);
}

▌运行验证：ChatClient 装配成功（编译 + 启动自检）

# 先确认编译通过（最便宜的反馈）
mvn -q compile

# 再启动，看 ChatClient bean 能不能装配起来
mvn spring-boot:run

期望启动日志（节选）：

...
2025-xx-xx INFO  ... Started SpringaiLabApplication in 3.x seconds
...

看到什么算通过：控制台出现 Started ... in X seconds 且无 APPLICATION FAILED TO START；特别地，没有出现 Consider defining a bean of type 'org.springframework.ai.chat.client.ChatClient' 这类提示。此时还没有 HTTP 接口，curl 会报连接拒绝，这是正常的——这一步只验证「装配对不对」。

7.5返回值、ToolContext 与「结果直出」

工具返回值怎么设计

工具返回什么，直接决定了模型能「看懂」多少。原则一句话：返回值是写给模型看的，不是写给数据库看的。

// ❌ 不好：返回一个复杂的内部实体，字段名模型看不懂
public OrderEntity query(String no) { return repo.find(no); }
// 返回 {"id":1,"ordNo":"2024001","sta":2,"gmtCreate":1709...}
// 模型看到 sta=2 完全不知道是什么意思

// ✅ 好：返回语义清晰的 DTO，字段名自解释，必要时附带说明文本
public record OrderStatus(
        String orderNo,          // 订单号
        String status,           // 已翻译成中文：未发货/已发货/已完成
        String promisedDate,     // 预计发货日期 yyyy-MM-dd
        String message           // 一句话说明，便于模型组织语言
) {}

ToolContext：把上下文信息传进工具（不经过模型）

ToolContext 是工具安全设计的核心机制。它让你把「不能也不应该让模型看到/控制」的信息（当前用户 ID、租户 ID、请求追踪 ID）在调用时注入，模型既看不到也无法伪造。

import org.springframework.ai.chat.model.ToolContext;

/**
     * ★★ ToolContext 是一个非常重要的机制：
     * 它允许你把「不能也不应该让模型看到/控制」的信息传给工具，
     * 例如：当前登录用户的 ID、租户 ID、请求追踪 ID。
     *
     * 这些值由你的代码在调用时注入，模型无法伪造——这是安全性的关键。
     */
    @Tool(description = "查询当前用户自己的全部订单列表")
    public List<OrderStatus> queryMyOrders(ToolContext toolContext) {
        // 从上下文取当前用户，而不是从模型的参数里取！
        String userId = (String) toolContext.getContext().get("userId");
        if (userId == null || userId.isBlank()) {
            // 兜底：调用方没注入上下文时，宁可回错误，也不要"查所有人"
            return List.of(new OrderStatus("-", "ERROR", null, "缺少登录身份，无法查询订单列表"));
        }

        // 越权在这里天然不可能发生：过滤条件来自上下文，模型干预不了
        return DB.values().stream()
                .filter(o -> o.ownerId().equals(userId))
                .map(o -> new OrderStatus(o.orderNo(), o.status(), o.promisedDate(), ""))
                .toList();
    }

调用时由服务端把上下文注入进去（这一步发生在你的 Service 里，模型无感）：

// 模拟"已登录用户"。真实项目里换成从登录态取（JWT / Session / 网关透传），
// 本章是纯 Spring AI 工程，没有引入 Spring Security，所以用一个常量占位——
// 关键是：这个值【从服务端代码流向 ToolContext】，而不是从 HTTP 请求体里读。
private static final String CURRENT_USER_ID = "u1001";
private static final String CURRENT_TENANT_ID = "t1001";

String answer = chatClient.prompt()
        .user("帮我看看我有哪些订单")
        // ★ 由服务端注入，模型看不到也改不了
        .toolContext(Map.of(
                "userId", CURRENT_USER_ID,
                "tenantId", CURRENT_TENANT_ID))
        .call()
        .content();

returnDirect：让工具结果直接返回给用户

/**
 * 有些工具的返回值本身就是最终答案，不需要模型再加工一遍。
 * 例如"导出一份明细报表"——加工反而会改动数据、增加成本。
 * returnDirect = true 时，工具结果会跳过第二次模型调用，直接返回。
 */
@Tool(description = "导出指定订单的完整明细报表（CSV 文本）", returnDirect = true)
public String exportOrderDetail(@ToolParam(description = "订单号") String orderNo) {
    return reportService.toCsv(orderNo);
}

▌运行验证：ToolContext 有两种失败形态，必须分清

mvn -q compile

编译只算必要条件。ToolContext 真正的判据在运行期，而且失败不是一种，是两种完全不同的形态——这是本章最容易记混的地方：

看到什么算通过：三种情况各跑一次，结果与上表逐行对上。特别注意第二行——很多人以为「忘传」会静默取到 null， 实测是直接 500；真正静默的只有第三行（key 拼错）。把这两个混为一谈，排错时就会往错的方向找。

7.6参数校验、异常处理与安全边界

工具里的错误：返回给模型，而不是抛给用户

工具执行失败时的处理，决定了用户体验的成败。下面的代码把「参数校验 → 权限校验 → 业务兜底」三段都写成「返回结构化错误对象」而不是抛异常，这样模型能把错误翻译成人话。

/**
 * 工具执行失败时的两种处理方式，效果差别巨大：
 *
 * ❌ 抛异常 → Spring AI 会把异常信息带回给模型（或直接失败），
 *           用户看到的是"系统错误"，体验极差。
 *
 * ✅ 返回结构化的错误对象 → 模型能"读懂"错误，并组织成礼貌的话回复用户，
 *           例如："没有找到订单 2024001，请确认订单号是否正确？"
 */
@Tool(description = """
        查询指定订单号的当前状态与预计发货时间。
        使用时机：用户询问某个订单是否已发货、什么时候发货时调用。
        不要用于：查询商品信息、退款进度、账户余额。
        参数约束：orderNo 为纯数字订单号，例如 2024001。
        """)
public OrderStatus queryOrderStatus(
        @ToolParam(description = "订单号，纯数字字符串，例如 2024001") String orderNo,
        ToolContext toolContext) {              // ← 身份从上下文取，不从参数取

    // ---------- ① 参数格式校验：模型可能传 "订单2024001"、全角数字或空值 ----------
    if (orderNo == null || !orderNo.matches("\\d{6,20}")) {
        return new OrderStatus(orderNo, "INVALID", null,
                "订单号格式不正确，应为 6~20 位数字。请向用户确认订单号后重试。");
    }

    // ---------- ② 权限校验：绝不接受模型传来的用户身份 ----------
    String userId = (String) toolContext.getContext().get("userId");
    if (userId == null || userId.isBlank()) {
        return new OrderStatus(orderNo, "ERROR", null, "缺少登录身份，无法查询订单");
    }

    // ---------- ③ 业务异常兜底：把技术异常翻译成业务语言 ----------
    try {
        Order order = DB.get(orderNo);
        // ★ 越权时按"查不到"返回——不告诉对方"这单存在，只是不是你的"
        if (order == null || !order.ownerId().equals(userId)) {
            return new OrderStatus(orderNo, "NOT_FOUND", null,
                    "未查询到该订单。请确认订单号是否正确。");
        }
        return new OrderStatus(order.orderNo(), order.status(), order.promisedDate(), "");
    } catch (Exception e) {
        // 内部异常详情记日志，返回给模型的是"可读的错误说明"
        log.error("查询订单 {} 失败", orderNo, e);
        return new OrderStatus(orderNo, "ERROR", null,
                "订单系统暂时不可用，请稍后重试或转人工客服。");
    }
}

全局异常处理器：统一决定「异常要不要抛」

import org.springframework.ai.tool.execution.ToolExecutionException;
import org.springframework.ai.tool.execution.ToolExecutionExceptionProcessor;

/**
 * 只有当默认策略不满足需求时，才需要自定义。
 * 它是一个函数式接口，只有一个方法，所以可以直接写成 lambda。
 */
@Configuration
public class ToolConfig {

    @Bean
    public ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
        return exception -> {
            // exception 里带着原始异常、工具定义等信息
            log.error("工具执行失败：工具={} 原因={}",
                    exception.getToolDefinition().name(), exception.getMessage());

            // ★★ 关键：这里【绝不发回异常原文】。
            //   实测默认策略会把异常消息（含内部 IP / 库名 / 账号）发给模型，
            //   模型会一字不差地复述给用户（见上面那个 pit）。自定义处理器必须堵住这条路。
            return "该功能暂时不可用（内部错误已记录）。请告知用户稍后重试，本次不要重复调用此工具。";
        };
    }
}

@Bean
public ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
    return exception -> {
        Throwable cause = exception.getCause();
        log.error("工具执行失败：工具={}，原因={}",
                exception.getToolDefinition().name(), cause);

        // ★ 受检异常（IOException / SQLException 这类程序性错误）不吞，继续向上抛 → 500 + 监控告警
        if (cause != null && !(cause instanceof RuntimeException)) {
            throw exception;
        }

        // 业务可自愈的错误才翻译成人话，且绝不带内部细节
        return "该功能暂时不可用（内部错误已记录）。请告知用户稍后重试。";
    };
}

工具的安全边界 Checklist

▌运行验证：三条判据都要在「运行期」验，编译过不算

mvn -q compile

先自查代码里这三段在不在：① 参数格式校验（matches("\\d{6,20}")）、 ② 权限校验（从 ToolContext 取身份，不是从方法参数取）、③ 异常兜底（try/catch 返回错误对象）。 三条齐了，才谈得上「工具不裸奔」。

真正的判据要跑起来看（三条，逐条可证伪）：

7.7完整示例：订单与天气查询助手

下面把前面所有点串成一个可运行的示例：一个订单 + 天气查询助手。先看工程结构，再逐文件讲解，最后给出可复制的验证步骤。本章无配套 lab 代码，请按「自建」口径在 com.example.springai.ch07 包下依次创建这些文件。

▌动手·前置 1：确认 pom.xml 依赖（自建工程的根基）

1. 打开工程根目录的 pom.xml，确认 <parent> 指向 spring-boot-starter-parent 且版本是 4.1.x（如 4.1.1）。
2. 在 <dependencyManagement> 里引入 spring-ai-bom，版本锁 2.0.1——这是全课程版本基准的开关。
3. 在 <dependencies> 里至少加入下面三个 starter：Web（提供 @RestController）、Spring AI 的 OpenAI 模型 starter（提供 ChatModel 与工具能力）、Lombok（可选，本示例用 @Slf4j 需要）。
4. 保存后，IDEA 右下角 Maven 面板点「刷新」，等依赖下载完、无红线。

<!-- 版本基准：Boot 4.1.x + Java 17 + Spring AI 2.0.1 -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.1.1</version>
  <relativePath/>
</parent>

<dependencyManagement>
  <dependencies>
    <!-- ★ 锁死 Spring AI 版本，避免混用 1.x -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
  <!-- 提供 ChatModel、工具调用、ToolCallingAdvisor 等全部能力 -->
  <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-model-openai</artifactId></dependency>
  <dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency>
</dependencies>

▌运行验证：依赖齐了，先编译一次

# 在 pom.xml 所在目录执行（最先、最便宜的反馈）
mvn -q compile

看到什么算通过：命令结束无 BUILD FAILURE；特别地，不会出现 Cannot resolve org.springframework.ai:spring-ai-starter-model-openai:2.0.1 这类「找不到依赖」报错。若报找不到，回头检查 spring-ai-bom 的版本与引入方式（必须是 import 作用域的 pom）。这一步把「工程地基」钉死，后面所有文件出问题才不会和依赖混在一起。

▌动手第 0 步：先配好 application.yml（密钥占位符）

1. 打开 src/main/resources/application.yml（没有就 New → File 创建）。
2. 粘贴下方配置，保存。注意 api-key 用的是 ${DEEPSEEK_API_KEY:} 占位符，绝不硬编码真实 key。
3. 确认环境变量 DEEPSEEK_API_KEY 已设置，且 IDEA 是在设置之后启动的（否则进程读不到，见 ch00 的「进程继承」说明）。

spring:
  ai:
    openai:
      base-url: https://api.deepseek.com   # DeepSeek 兼容 OpenAI 协议
      api-key: ${DEEPSEEK_API_KEY:}          # ★ 占位符，key 来自环境变量，不进源码
      chat:
        options:
          model: deepseek-chat              # 默认模型

server:
  port: 8080

logging:
  level:
    org.springframework.ai.chat.client: DEBUG   # ★ 实测对「看工具循环」没用，保留只为看 prompt 内容（原因见 7.2）

① 天气工具（演示外部 API 调用 + 超时保护）

1. 右键 ch07 包 → New → Java Class，名字填 WeatherTools，粘贴下方代码，保存。
2. 下面这版「本地就能跑」：不依赖任何外部天气 SDK，用一张假数据表模拟 API 返回。 真实项目里把 STUB.get(key) 换成一次 HTTP 调用即可——务必设连接/读取超时， 否则外部服务一卡，你的 Tomcat 线程池会跟着陪葬。

@Slf4j
@Component
public class WeatherTools {

    /** 本地假数据：城市 → 三天的 {天气, 最低温, 最高温, 湿度}。真实项目换成外部 API。 */
    private static final Map<String, List<String[]>> STUB = Map.of(
            "北京", List.of(new String[]{"晴", "12", "22", "45"},
                              new String[]{"多云", "14", "24", "50"},
                              new String[]{"小雨", "11", "19", "78"}),
            "上海", List.of(new String[]{"多云", "18", "25", "60"},
                              new String[]{"阴", "17", "23", "70"},
                              new String[]{"中雨", "16", "21", "85"}),
            "深圳", List.of(new String[]{"阵雨", "23", "29", "80"},
                              new String[]{"雷阵雨", "24", "30", "88"},
                              new String[]{"多云", "24", "31", "75"}));

    @Tool(description = """
            查询指定城市未来 3 天（今天、明天、后天）的天气预报。
            使用时机：用户询问天气、气温、是否下雨、穿衣建议时调用。
            不要用于：查询历史天气（本工具只支持未来 3 天）、查询空气质量指数。
            参数约束：city 为中文城市名，不要带"市"字后缀。
            """)
    public WeatherInfo queryWeather(
            @ToolParam(description = "城市名称，中文，例如 北京、上海、深圳；不要带'市'字后缀")
            String city) {

        // ---------- ① 城市名做白名单/格式校验，防止把用户输入拼进 URL 造成注入 ----------
        if (city == null || city.isBlank() || city.length() > 20) {
            return new WeatherInfo(city, List.of(), "城市名不合法，请向用户确认城市名称。");
        }
        // 模型经常不听 description 而带上"市"，服务端顺手兜一下，提高命中率
        String key = city.endsWith("市") ? city.substring(0, city.length() - 1) : city;

        List<String[]> raw = STUB.get(key);
        if (raw == null) {
            // ★ 未收录也返回"人话结论"，不要抛异常——模型会把 message 如实转述给用户
            return new WeatherInfo(city, List.of(),
                    "天气服务暂未收录「" + city + "」，目前仅支持北京、上海、深圳。请如实告知用户。");
        }

        try {
            // ★★ 关键：把返回值"翻译"成模型友好的中文，而不是原样丢 JSON
            LocalDate today = LocalDate.now();
            String[] labels = {"今天", "明天", "后天"};
            List<DailyWeather> days = IntStream.range(0, Math.min(3, raw.size()))
                    .mapToObj(i -> new DailyWeather(
                            today.plusDays(i).format(DateTimeFormatter.ofPattern("MM-dd")),
                            labels[i],                                    // ★ 服务端算好"今天/明天/后天"
                            raw.get(i)[0],                                // "晴" / "小雨"
                            raw.get(i)[1] + "~" + raw.get(i)[2] + "℃",
                            raw.get(i)[3] + "%"))
                    .toList();

            return new WeatherInfo(city, days, "");
        } catch (Exception e) {
            log.error("查询 {} 天气失败", city, e);
            return new WeatherInfo(city, List.of(), "天气服务暂时不可用，请稍后重试。");
        }
    }

    public record WeatherInfo(String city, List<DailyWeather> days, String message) {}

    /** ★ dayLabel 是本章加的一个小设计：见下面的说明 */
    public record DailyWeather(String date, String dayLabel, String weather,
                                    String temperature, String humidity) {}
}

② 装配带工具的 ChatClient

1. 右键 ch07 包 → New → Java Class，名字填 AssistantConfig，粘贴下方代码，保存。
2. 确认它用 @Configuration 标注，且 OrderTools、WeatherTools 两个 bean 能被注入（它们都带 @Component）。

@Configuration
public class AssistantConfig {

    @Bean("orderAssistantClient")   // 用限定名区分多个 ChatClient
    public ChatClient orderAssistantClient(ChatModel chatModel,
                                             OrderTools orderTools,
                                             WeatherTools weatherTools) {
        return ChatClient.builder(chatModel)
                .defaultSystem("""
                        你是"智汇"公司的智能助手，可以查询订单状态和天气。

                        工作准则：
                        1. 凡是涉及订单数据、实时天气的问题，必须调用工具查询，
                           禁止凭已有知识或猜测回答。
                        2. 调用工具前如果缺少必要参数（如订单号、城市），
                           先向用户追问，不要编造参数。
                        3. 工具返回错误信息时，用友好、明确的语气告知用户，
                           并给出下一步建议。
                        4. 回答控制在 150 字以内。
                        """)
                .defaultTools(orderTools, weatherTools)   // 把工具挂到这个 client 上
                .build();
    }
}

③ 业务服务（注意 ToolContext 的注入）

1. 右键 ch07 包 → New → Java Class，名字填 OrderAssistantService，粘贴下方代码，保存。
2. 确认构造器注入了带 @Qualifier("orderAssistantClient") 的 ChatClient。

@Slf4j
@Service
public class OrderAssistantService {

    // 模拟"已登录用户"。真实项目里换成从登录态取（JWT / Session / 网关透传），
    // 关键在于：这个值从服务端代码流向 ToolContext，而不是从 HTTP 请求体里读。
    private static final String CURRENT_USER_ID = "u1001";
    private static final String CURRENT_TENANT_ID = "t1001";

    private final ChatClient orderAssistantClient;

    public OrderAssistantService(
            @Qualifier("orderAssistantClient") ChatClient orderAssistantClient) {
        this.orderAssistantClient = orderAssistantClient;
    }

    /** 带工具的问答。注意 ToolContext 里只放"服务端可信"的身份信息。 */
    public String ask(String question) {
        return orderAssistantClient.prompt()
                .user(question)
                // ★ 身份信息走 ToolContext，模型看不见也改不了
                .toolContext(Map.of(
                        "userId", CURRENT_USER_ID,
                        "tenantId", CURRENT_TENANT_ID))
                .call()
                .content();
    }

    /** 进阶：想手工拿到「模型这一轮调了哪些工具」——注意这条路在 2.0 里基本走不通，原因见下方 pit。 */
    public String askWithToolTrace(String question) {
        ChatResponse response = orderAssistantClient.prompt()
                .user(question)
                .toolContext(Map.of("userId", CURRENT_USER_ID))
                .call()
                .chatResponse();

        var output = response.getResult().getOutput();

        // 如果模型这一轮又发起了工具调用，会出现在这里（实测 2.0 通常是空的）
        if (output.getToolCalls() != null && !output.getToolCalls().isEmpty()) {
            output.getToolCalls().forEach(tc ->
                    log.info("模型请求调用工具：name={} arguments={} id={}",
                            tc.name(), tc.arguments(), tc.id()));
        } else {
            log.info("[trace] getToolCalls() 为空 —— 工具已在 ToolCallingAdvisor 内部执行完毕");
        }
        return output.getText();
    }
}

④ 接口与验证

1. 右键 ch07 包 → New → Java Class，名字填 OrderAssistantController，粘贴下方代码，保存。
2. 确认类上有 @RestController + @RequestMapping("/api/v1/assistant")，且注入了 OrderAssistantService。
3. 全部文件就位后，执行下面的「▌运行验证」把工程跑起来，再用 4 个 curl 场景逐一验证。

@RestController
@RequestMapping("/api/v1/assistant")
public class OrderAssistantController {

    private final OrderAssistantService service;

    public OrderAssistantController(OrderAssistantService service) {
        this.service = service;
    }

    @PostMapping("/ask")
    public Map<String, String> ask(@RequestBody Map<String, String> body) {
        String answer = service.ask(body.get("question"));
        return Map.of("answer", answer);
    }
}

▌运行验证：把工程跑起来

# 在 pom.xml 所在目录执行（先确认 application.yml 已配好 DeepSeek key 占位符）
mvn spring-boot:run

期望启动日志（节选）：

...
2025-xx-xx INFO  ... Started SpringaiLabApplication in 3.2 seconds
...

看到什么算通过：控制台最后出现 Started ... in X seconds，且没有红色 BUILD FAILURE / APPLICATION FAILED TO START；之后浏览器或 curl 访问 http://localhost:8080 不报「连接拒绝」。此时服务已就绪，可以进 4 个场景验证了。

▌运行验证：五个场景（①②③看「调通」，②④⑤才是真考点）

把示例跑起来，用 curl 逐个验证。场景 ①②③ 对应「能不能调通」，场景 ②（越权）、④（缺参）、⑤（不支持的城市）才是本章真正的考点—— 它们分别对应「安全」和「可靠性」，比「调通」重要得多。

# ① 明确引用订单号 → 应触发 queryOrderStatus 工具
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 什么时候发货？"}'

# 期望日志（工具方法内部那行，见 7.3）：
# [OrderTools] orderNo=2024001, userId=u1001
# 期望回答："订单 2024001 显示未发货，预计 2026-10-28 发出。"

# ② 越权测试：2024003 在库里【真实存在】，但属于另一个用户 u2002
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024003 发货了吗？"}'

# 期望：模型回答"未查询到该订单，或该订单不属于当前账号"
# ★ 关键：必须用 2024003 这种"存在但属于别人"的单号
#   用 9999999（根本不存在的号）验不到权限——它走的是"查不到"分支，
#   你把归属校验整段删掉，它照样返回"未查询到"

# ③ 混合任务：订单 + 天气（会触发两次工具调用）
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"我的订单 2024001 发货了吗？另外北京明天天气怎么样？"}'

# 期望：模型分别调用两个工具，最后合并成一段回答

# ④ 缺少参数 → 应追问而不是编造
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"我的订单发货了吗？"}'

# 期望：模型回答"请提供订单号"
# 如果它随便编了一个订单号去查 → 你的系统提示约束不够强

# ⑤ 工具不支持的城市 → 应如实转述，不许自己编天气
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"成都今天天气如何？"}'

# 期望："暂未收录「成都」，目前仅支持北京、上海、深圳"
# ★ 这一步验的是【工具返回的 message 字段】：把"查不到"写成人话，模型才会照实转述。
#   如果模型自己编了个"成都晴 20 度"，说明工具返回得太模糊（比如只回了个空列表）。

看到什么算通过（逐条）：

• ① 日志出现 [OrderTools] orderNo=2024001, userId=u1001，且回答里是真实发货日期（不是「我不知道」）。
• ② 返回「未查询到该订单，或不属于当前账号」，且绝不出现 u2002 的任何字段——这一条没过就是越权事故。
• ③ 一次回答里同时有订单状态和天气，日志里同时出现 [OrderTools] 与 [WeatherTools] 两行。
• ④ 模型回问「请提供订单号」之类，没有凭空编一个号去查。
• ⑤ 回答里明确说「暂未收录成都 / 仅支持北京、上海、深圳」，没有编造天气。

7.8常见坑排错

7.9自测题

7.10实操作业与本章验收

• 能口述工具调用完整时序，说清为什么会有两次（或多次）模型调用，以及它对成本/延迟的影响。
• 能写出一个带「四要素描述」的 @Tool 方法，并知道用 FunctionToolCallback 注册函数式工具、toolNames() 已在 2.0 删除。
• 越权查询返回友好提示（不返回他人数据、不抛 500）；参数缺失时模型会追问而非编造。
• 能说出至少四条工具安全设计原则，并解释为什么身份类信息必须走 ToolContext 而非工具参数。