别再正则抠 JSON 了:用 Spring AI 的 entity() 把模型输出变成对象
模型返回 JSON,手工抠字段迟早崩。用 Spring AI 1.0 的 entity() 把输出直接映射成 Java 对象:单对象、List、自定义 schema、字段描述注解四种写法,外加 5 个上线前必须处理的坑。
你说要让模型「返回一段结构化数据」:审核结论、抽取字段、分类标签。最常见的写法是拿到模型返回的字符串,再用正则抠、用 split 切、最后 JSON.parseObject 喂进 map。我这么写过。三个月后对方模型换了措辞,字段名悄悄漂移,线上开始成片吐空值,查了一下午才发现是解析层先跪了。
字段是模型「猜」的,不是你定义的契约。这一篇就讲怎么把解析这件事从业务代码里彻底拿掉——用 Spring AI 1.0 的 entity(),让模型输出直接变成你的 Java 对象。
版本前提:本文基于 Spring AI 1.0.x + Spring Boot 3.3 + JDK 17。结构化输出在 0.8 到 1.0 之间改过命名(
OutputConverter→BeanOutputConverter等),网上不少老文章的写法已失效,请先核对版本。文中类名与方法以官方文档为准。
结论先说
别再手写 JSON 解析了。用 ChatClient 的 .call().entity(YourClass.class),模型返回的内容会按你给的类型直接映射成对象。字段缺失给默认值,类型不对抛异常,比正则稳得多。
有人问,这不就是 Jackson 吗?不一样。Jackson 是「我给你字符串你帮我映射」,schema 得你自己保证对得上;entity() 是「我把类型给你,你连提示词里的格式约束一起生成」,模型从一开始就按这个 schema 生成。出错面从「解析」前移到了「生成」,而生成端你可控,解析端才是真正的黑盒。
手工抠 JSON 的三道坎
| 方式 | 遇到字段漂移 | 类型转换 | 维护成本 |
|---|---|---|---|
| 正则 / substring | 立刻崩 | 自己写 | 高 |
| Jackson 手动 parse | 改字段名就改代码 | 自己写 | 中 |
entity() 映射 | 字段不变就稳 | 框架做 | 低 |
真正的问题在于:模型吐的 JSON 不是你写的契约,是它「猜」的格式。越靠手工解析,越脆弱——你每加一个字段,就可能改三处正则和两处取值代码。
最小可用:entity(Class)
一个普通 record 就够了,不需要任何注解:
record Review(String risk, int score,
List<String> items) {}
Review r = chatClient.prompt()
.user("审查这段 SQL 的风险:" + sql)
.call()
.entity(Review.class);
框架会在底层生成 JSON Schema 并注入 prompt,再解析回传内容。你拿到的就是强类型的 Review,可以直接进业务代码,不用任何中间 map。
集合怎么拿:ParameterizedTypeReference
要模型一次返回一组对象,用 ParameterizedTypeReference 包一层:
List<Review> list = chatClient.prompt()
.user("给出 3 条风险点")
.call()
.entity(new ParameterizedTypeReference
<List<Review>>() {});
注意那个匿名内部类的 {} 不能省——它承载泛型信息,少了这层 List 会拿不到,编译虽过、运行却空。
想自己控 schema:BeanOutputConverter
需要把格式说明拼进自定义提示词时,用 BeanOutputConverter 显式拿格式串:
var conv = new BeanOutputConverter<>(
new ParameterizedTypeReference
<List<Review>>() {});
String ans = chatClient.prompt()
.user(u -> u.text("审查风险,按格式输出")
.param("format", conv.getFormat()))
.call().content();
List<Review> rs = conv.convert(ans);
getFormat() 返回的就是 JSON Schema 片段,直接当占位符塞进 prompt。convert() 负责把字符串变对象。它和上面的 entity() 走的是同一套映射,只是把「生成提示词」这一步交还给你。
让模型少犯字段错:加描述
类型字段名是给程序看的,模型不一定懂 risk 是高危还是高围。用 Jackson 的描述注解给它提示:
@JsonClassDescription("SQL 风险审查结果")
record Review(
@JsonPropertyDescription("高危/中危/低危")
String risk,
@JsonPropertyDescription("0-100 风险分")
int score) {}
这两行注解会进 schema,模型按描述填字段,枚举类字符串的乱填率明显下降。别小看它:字段一多,模型分不清「status / state / result」的时候,差异很实在。
上线前必须处理的坑
- 模型不保证吐合法 JSON。加 try/catch,解析失败要有兜底(返回空对象或走规则分支),别让一次坏响应拖垮整个接口。
- 枚举别指望模型拼对。能枚举的值,解析后用
switch归一,匹配不到默认归到「未知」,而不是把脏字符串直接落库。 - 中文标点与全角括号会被模型随手带进来,校验时一并清洗,否则下游比较永远对不上。
maxTokens要留够。结构化字段多,输出天然更长,太小会截断,截断的 JSON 必然解析失败。- schema 即契约。record 字段一改,prompt 里的 schema 自动改,但下游消费方要同步——把它当一次接口变更来管。
结构化输出把「和模型博弈格式」这件事从业务代码里拿掉了。剩下要管的,是字段语义和失败兜底,这两件才是你该花时间的地方。
这个系列后面还会写会话记忆:多人多会话怎么隔离,内存版和 JDBC 版怎么选。
你在项目里用结构化输出踩过什么坑?后台告诉我。
以上是在 Java 系统里落地这套能力时的做法,欢迎在评论区补充你踩过的坑。