本文定位Spring AI 原理 / Function Calling / Java 源码思路示例环境Java 21、Spring Boot 3.3、Spring AI 1.0.x。不同版本的类名和自动配置可能变化本文重点放在稳定的调用模型和工程边界。摘要很多 Java 开发者第一次使用 Spring AI 的工具调用能力时会觉得模型“自己执行了 Java 方法”。实际上模型从来没有直接运行代码它只是根据工具描述返回一个结构化的调用请求真正的工具查找、参数反序列化、权限校验、方法执行和结果回传都由应用程序完成。理解这条调用链很重要一旦把工具当作普通函数直接暴露就会出现参数不可信、权限缺失、重复执行和异常不可控等问题。本文从消息结构、工具注册、执行循环、结构化结果和安全校验五个层面拆解一个简化的 Java 实现。一、模型输出的不是“执行结果”而是调用意图一次典型对话包含三类消息用户消息、助手的工具调用消息、工具结果消息。模型决定调用getWeather时只会返回类似下面的结构{role:assistant,tool_calls:[{id:call-123,name:getWeather,arguments:{city:天津,date:2026-08-10}}]}应用收到这个结果后才会根据name找到工具、校验arguments、执行 Java 逻辑再把结果作为tool消息发回模型。模型随后可能继续调用其他工具也可能生成最终回答。Java ToolToolRouter模型ChatClient用户Java ToolToolRouter模型ChatClient用户问题问题 工具Schematool_call工具名 参数Schema/权限/限流校验执行方法结构化结果tool_result原问题 工具结果最终回答或下一次tool_call二、工具注册描述和执行器要分离一个可靠的工具注册表至少包含工具描述和执行函数两个部分。描述会发给模型执行函数只存在于后端。不能把 Java 方法名、数据库连接或内部异常直接暴露出去。publicrecordToolSpec(Stringname,Stringdescription,JsonNodeinputSchema,SetStringpermissions,RiskLevelriskLevel){}publicinterfaceToolExecutor{ToolSpecspec();ToolResultexecute(JsonNodearguments,AuthContextauth);}publicfinalclassToolRegistry{privatefinalMapString,ToolExecutorexecutors;publicToolExecutorrequire(Stringname){ToolExecutorexecutorexecutors.get(name);if(executornull){thrownewUnknownToolException(name);}returnexecutor;}}工具描述应当准确表达用途、输入格式和限制。例如“查询工单”要说明时间范围、最大数量和返回字段而不是使用“负责查询所有工单”这种过大的描述。描述越模糊模型越容易选择错误工具。三、参数解析不能只靠 JacksonJSON 能被反序列化成 Java 对象不代表参数就是合法业务输入。校验需要分三层结构校验字段类型、必填项、长度和枚举。安全校验路径、URL、表达式、SQL、脚本等危险输入。业务校验对象归属、状态、额度和调用者权限。publicFindTicketInputparseAndValidate(JsonNodenode,AuthContextauth){FindTicketInputinputmapper.convertValue(node,FindTicketInput.class);beanValidator.validate(input);if(input.limit()50){thrownewIllegalArgumentException(单次最多查询50条);}if(!ticketRepo.belongsToTenant(input.ticketId(),auth.tenantId())){thrownewAccessDeniedException(工单不属于当前租户);}returninput;}不要用模型返回的tenantId、operatorId或role覆盖认证上下文。工具的执行身份必须由服务端注入。四、执行循环与最大步数工具调用流程需要有最大轮次、总超时和结果大小上限否则模型可能在错误条件下反复调用。一个简化的执行器如下publicChatResultrun(StringuserText,AuthContextauth){ListMessagemessagesnewArrayList();messages.add(newUserMessage(userText));InstantdeadlineInstant.now().plus(Duration.ofSeconds(30));for(intround0;round6;round){if(Instant.now().isAfter(deadline)){returnChatResult.degraded(任务执行超时);}AssistantMessageassistantmodel.call(messages,registry.specs());messages.add(assistant);if(assistant.toolCalls().isEmpty()){returnChatResult.answer(assistant.text());}for(ToolCallcall:assistant.toolCalls()){ToolResultresultrouter.execute(call,auth);messages.add(newToolMessage(call.id(),result.truncatedView()));}}returnChatResult.degraded(工具调用次数超过限制);}这里的new ArrayList只属于一次请求的消息集合不应该把跨请求的对话对象共享在全局。每次调用都要把模型、Prompt 模板、工具版本和参数哈希写入 Trace方便后续复盘。五、工具结果要结构化和可控工具结果越自由模型越难稳定处理。建议统一成包含状态、数据、来源和是否截断的结构publicrecordToolResult(Stringstatus,Objectdata,Stringsource,booleantruncated,StringsafeErrorCode){publicToolResulttruncatedView(){Stringjsonserialize(data);if(json.length()12000)returnthis;returnnewToolResult(status,json.substring(0,12000),source,true,safeErrorCode);}}工具异常不要把数据库堆栈、内部地址和密钥信息传给模型。可以返回statusERROR、safeErrorCodeTIMEOUT和用户可理解的摘要详细错误保存在服务端日志。工具输出中的自然语言也可能包含 Prompt Injection需要和系统指令分层传递。六、并行工具调用与一致性模型可能在一次响应里返回多个工具调用。只有在工具之间没有依赖且都是只读操作时才适合并行执行。涉及写操作、库存、余额或顺序依赖时应强制串行。publicListToolResultexecuteBatch(ListToolCallcalls,AuthContextauth){if(calls.stream().anyMatch(call-registry.require(call.name()).spec().riskLevel().compareTo(RiskLevel.HIGH)0)){returncalls.stream().map(call-router.execute(call,auth)).toList();}returncalls.parallelStream().map(call-router.execute(call,auth)).toList();}并行不是默认优化。数据库连接池、第三方限流和日志顺序都可能受到影响。需要给单个请求设置并发数上限工具自身还要有超时和熔断。七、结构化输出和工具调用的区别结构化输出解决“最终回答要符合 JSON Schema”的问题Function Calling 解决“模型请求应用执行某个函数”的问题。两者可以一起使用工具调用获取数据最终回答用结构化 DTO 表达。publicrecordDiagnosticAnswer(Stringconclusion,ListStringevidence,ListStringnextActions,booleanneedsHumanReview){}不要把所有内容都做成工具调用。工具应该表达真实动作或外部数据访问纯粹的文本格式要求应该由结构化输出约束。职责清晰后测试和错误处理都会更简单。八、安全与审计每次 ToolCall 需要关联用户、租户、请求、模型、工具版本、输入哈希、权限结果、执行耗时、结果状态和重试次数。高风险工具要额外记录确认人和确认时间。工具调用审计不能记录完整敏感内容。建议保存哈希和脱敏摘要必要时把原始数据放到受控存储并设置访问审批。模型调用日志也不能绕过企业数据保留策略。九、测试清单模型选择不存在的工具时是否安全失败。工具参数缺失、类型错误、超长时是否被拦截。当前用户无权限时执行器是否完全不调用业务方法。工具超时后是否按错误类别重试且有最大次数。同一个幂等键重复执行是否返回同一个业务结果。工具返回超长文本或恶意指令时是否截断并隔离。达到最大轮次或总超时时是否给出可理解的降级结果。模型升级后工具 Schema 变化是否能被评测集发现。十、总结Function Calling 的本质是“模型提出结构化调用意图应用负责决定是否执行”。Spring AI 可以减少消息拼装和客户端适配工作但工具注册、权限、幂等、超时和审计仍然属于业务后端。理解调用链之后很多问题就会变得清晰Prompt 不是权限模型不是执行器Schema 不是业务校验重试不是可靠性能调用也不代表应该调用。把这些边界写进代码和测试才是 Java 接入 Agent 的真正价值。读者讨论你更关心工具调用的 API 使用还是工具在生产环境中的权限、幂等和审计建议先画出调用链再决定需要引入哪些框架能力。