// 工具函数自定义注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ToolFunction {
    String name();
    String description();
}

// 函数执行核心组件
@Component
public class FunctionCallHandler {
    private final Map<String, Method> functionRegistry = new ConcurrentHashMap<>();

    // 启动时扫描注册所有工具函数
    @PostConstruct
    public void registerFunctions() {
        // 扫描Spring容器中所有带@ToolFunction的方法，存入注册表
    }

    // 执行函数调用
    public Object invoke(String funcName, Map<String, Object> args) {
        Method method = functionRegistry.get(funcName);
        if (method == null) {
            throw new BizException("工具函数不存在：" + funcName);
        }
        // 参数校验 + 类型转换逻辑
        Object targetBean = SpringContextUtils.getBean(method.getDeclaringClass());
        try {
            return method.invoke(targetBean, args.values().toArray());
        } catch (Exception e) {
            // 统一异常包装，返回大模型可理解的错误信息
            return "工具执行失败：" + e.getMessage();
        }
    }
}

🚀 典型业务场景

智能客服：调用订单、物流、用户中心接口，自动解答用户问题
数据分析师助手：自然语言转 SQL，执行查询后生成分析报告
企业办公助手：对接 OA、飞书 / 钉钉，自动查考勤、约会议、走审批
代码助手：调用沙箱执行代码、查询 API 文档、排查报错

⚠️ 生产踩坑与优化方案（面试加分项）

问题场景	落地解决方案
大模型生成错误参数、虚构函数	入参强校验 + 枚举值约束 + 默认值兜底，非法输入直接拦截
工具调用有副作用（扣款、审批）	增加人工确认节点 + 幂等设计 + 细粒度权限管控
多工具调度逻辑混乱	引入 ReAct 思考模式，让大模型分步规划调用顺序
工具数量多、上下文超限	按需挂载工具，根据用户问题先做工具召回，只传相关工具
第三方接口超时失败	配置重试机制 + 降级策略，异常时友好告知用户

✅ 一句话总结

Function Calling 是大模型从 “聊天玩具” 走向 “生产级智能体” 的核心基础，Java 侧落地的核心就是做好注册、调度、校验、兜底四层封装，在享受大模型能力的同时，守住业务的稳定性和安全性。

真实面试模拟

面试官👨‍💼：

“我看你简历上写了有 AI 集成经验，那咱们聊聊 Function Calling 工具调用吧。你先用一句话说说它是干啥的，然后再展开。”

我🙋‍♂️：

好的。一句话：大模型负责决策调哪个函数、参数是什么，真正的执行由我们 Java 应用来完成，相当于给模型装上了能干事儿的“手”。

面试官🤔：

“这个‘手’具体怎么互动？能画个流程让我快速理解吗？”

我🙋‍♂️：

没问题，我画个时序图，一看就明白👇

核心就是 结构化决策 + 应用执行，大模型不直接碰外部系统，安全又可控。

面试官🧐：

“那你再拆解细一点，这个“决策”到底怎么发生的？”

我🙋‍♂️：

分三步走，我把它类比成餐厅点菜 🍽️

1️⃣ 给菜单 – 函数定义

我们用 JSON Schema 描述工具，就像给模型一张菜单：

{
  "name": "getWeather",
  "description": "根据城市名获取实时天气",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "城市名，例如'北京'" }
    },
    "required": ["city"]
  }
}

2️⃣ 模型点菜 – function_call 响应

当用户问“北京热不热”，模型不会瞎编，而是返回一个结构化的“点单”：

{
  "function": "getWeather",
  "arguments": "{\"city\": \"北京\"}"
}

3️⃣ 厨房上菜 – 应用执行并反馈

Java 代码收到这个 JSON，真实调 API，再把结果包成 role: "tool" 的消息塞回对话，模型最后用自然语言端给用户。

这三步环环相扣，模型从来不去碰数据库或网络，安全性天然就有保障。

面试官💻：

“Java 里具体怎么落地？总不能每次都手写 JSON 解析吧。”

我🙋‍♂️：

确实不用，现在 Spring AI 之类的框架封装得特别干净。比如这样：

// 1. 定义一个工具 Bean，就是普通 Service
@Component
public class WeatherService {
    @Tool(description = "获取指定城市的天气")
    public String getWeather(@ToolParam(description = "城市名") String city) {
        // 这里调真实天气接口，省略细节
        return "温度36℃，晴天";
    }
}

// 2. 调用时把工具注入进去，全程自动
@Autowired
private ChatClient chatClient;
@Autowired
private WeatherService weatherService;

public String chat(String userMessage) {
    return chatClient.prompt()
        .user(userMessage)
        .tools(weatherService)  // 👈 就这一行，工具接入了
        .call()
        .content();
}

框架在背后做了三件事：

把 @Tool 方法转成函数定义发给模型
解析模型返回的 function_call，反射调用真实方法
把返回值喂回模型，拿到最终回复

我们只写业务逻辑，交互细节全透明，代码量少而且不容易出错。

面试官🕵️：

“听起来很顺，那实际项目里碰到过哪些坑？挑几个重要的说说。”

我🙋‍♂️：

这几个是高频踩坑点，整理了一下：

坑 🕳️	对策 ✅
🔄 多轮工具调用（比如先查航班再订票）	用 while 循环检查 `finishReason == "tool_calls"`，持续把结果塞回，直到模型不再要求调用
🧩 参数幻觉（城市名瞎编）	代码里加校验，参数非法直接返回明确错误信息，让模型根据提示重试
⏱️ 外部接口超时	必须加超时、重试、熔断降级，返回兜底信息别让对话卡死
💰 Token 成本	函数定义只传最必要的字段，描述尽量精简，减少上下文消耗
🔒 安全权限	用户相关操作一定要从当前会话传真实的 userId，绝不能信任模型传过来的标识

这些坑补好了，Agent 在生产环境才能稳得住。

面试官😊：

“不错，把为什么用、怎么用、哪里会踩坑都讲透了，而且例子接地气，实战感很强。今天就到这，谢谢你。”

我🙋‍♂️：

谢谢面试官，我收获也很多 🤝