S22-B02 · 结构化返回与 Function Call

适用读者：要拿模型输出去写库/调接口的人。
前置：S22-B01、S21-B03。
口径：代码结构示意（未引入 Spring AI 依赖）。
覆盖旧文：655(70) 658(101) 771(11) = 182 点。
覆盖扩展：E-S22-002（输出 → Java 对象）、E-S22-008（工具幂等）。
上一篇：S22-B01 · Spring AI 入门：统一调用与流式输出
下一篇：S22-B03 · Advisor。

1. 一句话结论

结构化返回解决"解析文本"的脆弱性：让模型按 schema 输出，程序按类型接收。工具调用解决"模型能动手"：但执行权与校验权永远在你的代码里。

2. 结构化输出（E-S22-002）

record Answer(String summary, List<String> sources, double confidence) {}

Answer a = chatClient.prompt().user(q)
        .call().entity(Answer.class);       // ← 自动按 schema 约束

收益	代价
不用解析字符串	需模型支持结构化输出
字段缺失/类型错可被发现	schema 变更要同步改类
可做后置校验	复杂嵌套易失败

判据："这个输出要被程序用吗？" 是 → 结构化；只是给人看 → 文本即可。

"为什么比正则解析可靠"：模型被约束在 schema 内生成，而不是"生成后再猜格式"。

3. Function Call 的落地（E-S22-008）

@Tool(description = "按订单号查询状态")
OrderStatus queryOrder(@ToolParam String orderId) { ... }

要点	说明
description 写清"何时用"	S21-B03 的核心结论
参数校验	在方法内做（越权/注入）
幂等	重试会重复执行（S17-J03）
返回值要小	大对象会爆上下文（S20-J02）

4. 结构化 + 工具的组合陷阱

陷阱	后果
工具返回未结构化	模型要"读文本"，易误读
结构化字段与工具参数不一致	模型生成非法参数
一次要太多字段	输出质量下降

"让工具也返回结构化数据"：模型读 JSON 比读自然语言更稳——这是最容易提升成功率的一处改动。

5. 五个误区

误区	真相
"结构化输出一定准"	复杂嵌套仍会失败
"工具方法不用校验参数"	会越权
"工具可以随意重试"	需幂等
"工具返回越全越好"	会爆上下文
"schema 改了不用管"	要同步类与测试

6. 自检

结构化输出的收益与代价？
什么时候不需要结构化？
Function Call 的三条纪律？
为什么"工具返回结构化"更稳？
组合时的三个陷阱？

7. 下一篇

S22-B03 · Advisor：请求/响应日志与横切能力

工具讲完，下一篇讲"怎么在不改业务代码的前提下加日志/记忆/审计"。

本篇属于系列《S22 · AI 工程落地实战》。旧文来源：A-655/658/771；扩展点 E-S22-002/008。