别再正则抠 JSON 了:用 Spring AI 的 entity() 把模型输出变成对象

0 阅读4分钟

别再正则抠 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」的时候,差异很实在。

上线前必须处理的坑

  1. 模型不保证吐合法 JSON。加 try/catch,解析失败要有兜底(返回空对象或走规则分支),别让一次坏响应拖垮整个接口。
  2. 枚举别指望模型拼对。能枚举的值,解析后用 switch 归一,匹配不到默认归到「未知」,而不是把脏字符串直接落库。
  3. 中文标点与全角括号会被模型随手带进来,校验时一并清洗,否则下游比较永远对不上。
  4. maxTokens 要留够。结构化字段多,输出天然更长,太小会截断,截断的 JSON 必然解析失败。
  5. schema 即契约。record 字段一改,prompt 里的 schema 自动改,但下游消费方要同步——把它当一次接口变更来管。

结构化输出把「和模型博弈格式」这件事从业务代码里拿掉了。剩下要管的,是字段语义和失败兜底,这两件才是你该花时间的地方。

这个系列后面还会写会话记忆:多人多会话怎么隔离,内存版和 JDBC 版怎么选。

你在项目里用结构化输出踩过什么坑?后台告诉我。


以上是在 Java 系统里落地这套能力时的做法,欢迎在评论区补充你踩过的坑。