工程实践 on 吾爱主机

Spring AI 2.0 结构化输出实战：让大模型返回可验证的 Java 对象

Tue, 30 Jun 2026 01:15:52 +0000

在企业应用里，调用大模型最怕的不是“它会说错话”，而是下游系统把一段不稳定的自然语言当成了稳定数据：少一个字段、数组变成字符串、JSON 外面多一段解释，都可能让订单流转、风控判断、知识库入库或自动化工单发生不可预期的问题。

Spring AI 2.0 围绕结构化输出补上了两个很实用的工程开关：一个是在响应回来后做 schema 校验并自动重试的 validateSchema()，另一个是尽量使用模型供应商原生结构化输出能力的 useProviderStructuredOutput()。这篇文章把官方博客和参考文档整理成一份中文实战指南，重点讲清楚：什么时候用、怎么接入、哪些坑需要提前规避。

一、结构化输出解决的到底是什么问题

普通聊天接口返回的是文本。文本适合展示给人看，却不适合直接交给业务代码做分支判断。例如你希望模型返回演员和电影列表：

record ActorsFilms(String actor, List<String> movies) {}

如果模型严格返回：

{"actor":"Tom Hanks","movies":["Forrest Gump","Cast Away"]}

业务代码就能很自然地反序列化为 ActorsFilms。但真实模型输出经常会变成：

当然可以，下面是结果：
```json
{"actor":"Tom Hanks","movies":["Forrest Gump","Cast Away"]}


或者字段名、类型、嵌套结构发生漂移。Spring AI 的结构化输出能力，就是把“提示模型按格式回答”和“把回答转换成 Java 类型”封装进框架，让应用更接近普通 Java 对象编程，而不是到处写字符串解析逻辑。

## 二、最基础的用法：`.entity(...)`

在 Spring AI 的 `ChatClient` 中，最直接的结构化输出入口是 `.entity(...)`。它只适用于 `.call()` 同步调用链，因为类型转换需要拿到完整响应；流式 `.stream()` 返回的是文本片段，不能直接在流上变成对象。

```java
record ActorsFilms(String actor, List<String> movies) {}

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class);

System.out.println(films.actor());
System.out.println(films.movies());

背后大致会发生三件事：

Spring AI 根据目标 Java 类型生成 JSON Schema；
框架把格式要求加入提示词，让模型尽量按 schema 返回；
返回文本再交给 converter 转换成目标 Java 对象。

官方参考文档也明确提醒：这种方式本质上是 best effort。模型并不一定总能按要求返回结构化数据，所以生产环境不能只停留在“能跑通一次 demo”。

三、Spring AI 2.0 的第一个关键开关：`validateSchema()`

validateSchema() 解决的是响应侧校验与自修复问题。模型先正常回答，Spring AI 再用 schema 校验结果。如果校验失败，框架会把具体错误追加进下一轮请求，让模型基于错误信息重新生成，默认最多尝试 3 次。

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class, spec -> spec.validateSchema());

这比简单地“失败后再问一次”更可靠，因为第二次请求不是盲目重试，而是带着类似“缺少 required 字段 actor”“movies 期望 array 但收到 string”这样的校验反馈。

对业务代码来说，它的价值主要体现在三类场景：

返回对象会直接入库；
返回字段会影响自动化流程分支；
错误结构不会立刻报错，但会在后续链路中造成隐性数据污染。

如果默认 3 次不够，也可以显式注册 StructuredOutputValidationAdvisor 调整重试次数：

var validationAdvisor = StructuredOutputValidationAdvisor.builder()
 .outputType(ActorsFilms.class)
 .maxRepeatAttempts(5)
 .build();

ChatClient chatClient = ChatClient.builder(chatModel)
 .defaultAdvisors(validationAdvisor)
 .build();

需要注意：重试会增加延迟和 token 消耗，所以它适合关键链路，而不一定适合所有只用于展示的回答。

四、第二个关键开关：`useProviderStructuredOutput()`

validateSchema() 是“回来以后再检查”，而 useProviderStructuredOutput() 是“请求时就告诉供应商按结构化输出约束执行”。官方博客说明，Spring AI 2.0 支持把结构化输出 schema 通过模型供应商的 API 级能力发送出去，而不是只把格式要求塞进 prompt。

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class, spec -> spec.useProviderStructuredOutput());

这样做通常有三个好处：

system prompt 不再需要携带冗长 JSON 格式说明；
schema 通过供应商 API 字段传递，约束更靠近模型运行时；
对支持原生结构化输出的模型，格式稳定性通常更好。

截至 Spring AI 2.0 官方说明，支持面包括 OpenAI、Anthropic、Google GenAI、Mistral AI，以及按模型能力区分的 Ollama。Spring AI 会检查当前 chat options 是否实现 StructuredOutputChatOptions；如果不支持，这个开关会回退到基于 prompt 的默认方式，而不是强行让请求失败。

五、生产建议：两个开关一起用

如果你的下游系统不能容忍结构漂移，推荐把两个开关组合起来：

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class, spec -> spec
 .useProviderStructuredOutput()
 .validateSchema());

可以把它理解成两道防线：

useProviderStructuredOutput() 尽量在模型供应商侧减少非法输出；
validateSchema() 兜住供应商边界、模型差异和偶发异常。

这在“AI 结果要进入真实业务系统”的场景尤其重要，例如：

从客服对话中抽取投诉类型、订单号、处理建议；
从运维日志中归类故障级别和可能根因；
从合同文本中抽取主体、金额、日期、责任条款；
让智能体生成下一步工具调用参数前，先产出稳定中间对象。

如果只是把回答展示给用户阅读，单独使用 .content() 也可以；但只要结果要被程序消费，就应该优先考虑结构化输出。

六、泛型类型：`ParameterizedTypeReference`

.entity(Class) 适合普通类或 record。遇到 List<ActorsFilms>、Map<String, ActorsFilms> 这类泛型结构时，需要使用 ParameterizedTypeReference：

List<ActorsFilms> films = chatClient.prompt()
 .user("Generate filmographies for three random actors.")
 .call()
 .entity(new ParameterizedTypeReference<List<ActorsFilms>>() {});

同样可以追加参数配置：

List<ActorsFilms> films = chatClient.prompt()
 .user("Generate filmographies for three random actors.")
 .call()
 .entity(
 new ParameterizedTypeReference<List<ActorsFilms>>() {},
 spec -> spec.validateSchema()
 );

这里有一个重要兼容性坑：OpenAI 的 Structured Outputs API 不接受顶层数组。如果你在 OpenAI 上把 List<...> 和 useProviderStructuredOutput() 组合使用，可能会失败。更稳妥的方式是包一层 record：

record FilmographyList(List<ActorsFilms> films) {}

FilmographyList result = chatClient.prompt()
 .user("Generate filmographies for three random actors.")
 .call()
 .entity(FilmographyList.class, spec -> spec.useProviderStructuredOutput());

这也是面向多供应商开发时的通用经验：不要只按某一个模型的宽松行为设计数据结构，最好用显式对象包住列表、分页、错误码和元信息。

七、需要原始响应时，用 `.responseEntity(...)`

.entity(...) 只返回转换后的业务对象。如果你还需要 token 用量、模型元数据或原始 ChatResponse，可以使用 .responseEntity(...)：

ResponseEntity<ChatResponse, ActorsFilms> result = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .responseEntity(ActorsFilms.class);

ActorsFilms films = result.entity();
ChatResponse raw = result.response();
long totalTokens = raw.getMetadata().getUsage().getTotalTokens();

这对可观测性很有帮助。建议在生产系统中至少记录：模型名称、token 用量、重试次数、结构化校验是否失败过，以及最终转换耗时。这样当成本或延迟异常时，才能定位到底是模型调用慢、schema 过复杂，还是自修复重试过多。

八、内置 converter 与自定义 converter

Spring AI 参考文档列出了多个 converter，包括：

BeanOutputConverter<T>：把模型输出转换成指定 Java 类或 ParameterizedTypeReference，并使用符合 JSON Schema DRAFT_2020_12 的 schema；
MapOutputConverter：把 RFC8259 JSON 响应转换成 Map<String, Object>；
ListOutputConverter：面向逗号分隔列表输出转换；
AbstractConversionServiceOutputConverter 与 AbstractMessageOutputConverter：给更底层的转换扩展使用。

最常用的是 BeanOutputConverter。不过它也比较严格：如果模型在 JSON 前后加了解释文字，默认转换可能失败。对于历史模型、非原生结构化输出模型，或者你确实要兼容带代码块的 JSON，可以写一个轻量自定义 converter，先提取 JSON，再交给默认 converter：

public class LenientJsonOutputConverter<T> implements StructuredOutputConverter<T> {

 private static final Pattern FENCE = Pattern.compile("```(?:json)?\\s*([\\s\\S]*?)```");

 private final BeanOutputConverter<T> delegate;

 public LenientJsonOutputConverter(Class<T> targetType) {
 this.delegate = new BeanOutputConverter<>(targetType);
 }

 @Override
 public String getFormat() {
 return delegate.getFormat();
 }

 @Override
 public String getJsonSchema() {
 return delegate.getJsonSchema();
 }

 @Override
 public T convert(String source) {
 var matcher = FENCE.matcher(source);
 String json = matcher.find() ? matcher.group(1).trim() : source.trim();
 return delegate.convert(json);
 }
}

但要谨慎：宽松 converter 适合清理“JSON 外壳”，不应该悄悄吞掉业务字段错误。字段缺失、类型错误、枚举值非法，仍然应该交给 schema 校验或业务校验处理。

九、流式调用怎么处理结构化输出

Spring AI 文档说明，ChatClient 支持同步和流式模型。流式 .stream() 可以拿到 Flux<String> 或 Flux<ChatResponse>，但目前如果想把流式内容转成 Java 对象，需要先聚合完整文本，再显式调用结构化输出 converter。

示意代码如下：

var converter = new BeanOutputConverter<>(
 new ParameterizedTypeReference<List<ActorsFilms>>() {}
);

Flux<String> flux = chatClient.prompt()
 .user(u -> u.text("""
 Generate the filmography for a random actor.
 {format}
 """).param("format", converter.getFormat()))
 .stream()
 .content();

String content = flux.collectList()
 .block()
 .stream()
 .collect(Collectors.joining());

List<ActorsFilms> actorFilms = converter.convert(content);

如果你的业务既要“边生成边展示”，又要“最终写入结构化结果”，建议分成两个阶段：展示阶段走流式文本，落库阶段再触发一次非流式结构化调用，或者在流式完成后对完整文本做显式转换与校验。

十、工程落地清单

把 Spring AI 2.0 结构化输出接入生产系统时，可以按下面这份清单检查：

先定义稳定 DTO/record：字段名、类型、是否可为空要明确，不要把自然语言描述塞进一个大字符串字段里。
关键链路启用 validateSchema()：尤其是结果会入库、调用工具、影响流程分支的场景。
供应商支持时启用 useProviderStructuredOutput()：但要确认当前模型和 options 是否真的支持原生结构化输出。
避免顶层数组作为跨供应商公共协议：用包装 record 承载列表、分页和元信息。
记录观测指标：包括模型、token、耗时、重试次数、转换失败原因。
保留业务校验：schema 只能保证形状，不能保证“金额必须大于 0”“日期不能早于合同签署日”这类业务语义。
对失败路径设计降级策略：可以返回人工审核、重试队列、只展示原文，或者切换到更强模型，但不要静默写入脏数据。

总结

Spring AI 2.0 的结构化输出不是一个“让 JSON 更好看”的小功能，而是把大模型结果接入真实 Java 系统的重要基础设施。

.entity(...) 让模型回答直接进入 Java 类型；
validateSchema() 提供响应侧校验与自修复；
useProviderStructuredOutput() 尽量使用供应商原生结构化约束；
ParameterizedTypeReference、.responseEntity(...) 和自定义 converter 则覆盖了泛型、观测和兼容场景。

如果你正在把 LLM 从聊天窗口接进订单、工单、知识库、运维或智能体系统，建议尽早把“结构化输出 + schema 校验 + 业务校验”作为默认架构，而不是等线上出现一次脏数据事故后再补救。

Spring Boot 3.5.16 发布后，团队现在该怎么做：升级、验证与 3.5 生命周期收尾指南

Mon, 29 Jun 2026 15:21:35 +0000

Spring 团队在 2026-06-25 发布了 Spring Boot 3.5.16。如果你还在 3.5.x 线上维护窗口内，这个版本值得关注，因为它不仅是一个常规补丁版，还带着一个更重要的信号：3.5.x 已经来到开源维护周期的最后阶段。

这篇文章不重复官方公告，而是从工程落地角度整理成一份中文操作指南：这次版本到底变了什么、哪些团队应该马上升、升完要验证什么、以及如果你准备继续停留在 3.5 分支，应该怎样安排后续计划。

一、先说结论：3.5.16 是什么性质的版本

根据 Spring 官方博客，Spring Boot 3.5.16 已于 2026-06-25 发布，本次发布包含 3 项依赖升级。同时，官方明确说明它是 3.5.x 代际的最后一个 OSS 发布版本，后续若需要更长周期支持，需要转向商业支持方案。

结合 Spring Boot GitHub Release 与生命周期数据，可以把这个版本理解成：

它是 3.5.x 的收官补丁版本；
它不是一个新特性大版本，而是维护型版本；
对仍在 3.5.x 的团队来说，它很适合作为该分支的最终稳定落点；
如果你们还没有升级到 4.0/4.1，那么现在至少应先把 3.5.x 升到 3.5.16，再规划后续迁移。

二、这次实际更新了什么

从 Spring Boot 3.5.16 的 GitHub Release 页面可以确认，本次补丁版包含 3 个依赖升级：

Spring AMQP 3.2.12
Spring Data BOM 2025.0.13
Spring Integration 6.5.10

这说明 3.5.16 的核心价值并不是引入新的框架行为，而是：

对 3.5 代际已纳入管理的依赖做最后一轮维护性更新；
尽量把生态内相关模块收敛到更稳定的补丁位；
给仍在 3.5 线上运行的项目提供一个更明确的“最终补丁基线”。

如果你的应用显式或隐式使用了以下能力，建议优先升级并回归：

RabbitMQ / Spring AMQP 消息处理；
Spring Data 相关持久层能力；
Spring Integration 驱动的集成流、适配器或消息编排。

三、为什么这个版本值得今天就处理

很多团队看到“只有 3 个依赖升级”时，容易觉得可以先放一放。但从维护节奏上看，这次比功能变化更重要的是支持窗口变化。

生命周期数据表明：

Spring Boot 3.5 首次发布时间为 2025-05-31；
3.5.x 的 OSS 支持截止日期为 2026-06-30；
商业支持可延长到 2032-06-30；
截至校验时，3.5 分支最新版本就是 3.5.16（2026-06-25）。

这意味着什么？

1）你还在 3.5.x，就应该把 3.5.16 当成收官版看待

后续即便应用继续稳定运行，也不能再默认期待有新的公开补丁不断跟进。对生产团队来说，落在最后一个 OSS 补丁版本上，比停留在更早的 3.5.x 小版本上更稳妥。

2）升级 3.5.16 和规划下一跳，是两件要并行做的事

正确做法不是“反正马上要升 4.x，就不升 3.5.16 了”，而是：

短期：先把生产基线更新到 3.5.16；
中期：评估是升到 4.0 还是直接跟进 4.1；
长期：决定是否需要商业支持兜底。

因为 3.5.16 是补丁升级，风险通常远低于跨代升级。先完成这一步，可以降低你在迁移前的运行风险。

四、哪些项目应该优先升级

下面几类项目，建议你优先安排升级窗口：

1）仍在长期维护的存量业务系统

如果系统没有立刻升级到 4.x 的资源，但还要持续运行几个月甚至更久，那么停在 3.5.16 是更合理的选择。

2）依赖 Spring Data / Spring Integration / AMQP 的集成型系统

这次补丁直接涉及这些依赖线，消息、数据访问、系统集成相关项目更应该完成回归验证。

3）准备做 3.5 → 4.x 升级演练的团队

先把 3.5 基线统一到 3.5.16，再做跨代升级，排障边界会更清晰。否则你很难分辨问题来自：

旧的 3.5.x 补丁差异；
还是 4.x 的行为变化。

五、怎么升级到 3.5.16

大多数项目只需要改版本号，然后走一次标准构建与回归。

Maven

如果你使用 spring-boot-starter-parent：

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>3.5.16</version>
 <relativePath/>
</parent>

如果你使用 Spring Boot BOM：

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-dependencies</artifactId>
 <version>3.5.16</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

Gradle

如果你通过 Spring Boot Gradle Plugin 管理版本：

plugins {
 id("org.springframework.boot") version "3.5.16"
 id("io.spring.dependency-management") version "1.1.7"
 kotlin("jvm") version "2.2.0"
}

如果你的项目并不使用 Kotlin 或不需要显式声明这些插件版本，请按你们自己的构建脚本风格调整，核心是把 Spring Boot 版本对齐到 3.5.16。

六、升级后重点验证什么

虽然 3.5.16 本身是补丁版，但 3.5 这一代并不是完全没有行为约束变化。Spring Boot 3.5 Release Notes 中有几项很适合作为升级后的重点回归清单。

1）`heapdump` 端点默认访问策略变更

在 3.5 代际中，heapdump Actuator 端点默认变成了 access=NONE。如果你们过去只做了暴露配置，没有显式设置访问策略，那么升级后相关诊断链路可能与旧行为不同。

如果你确实需要启用它，应同时配置暴露与访问权限，例如：

management:
 endpoints:
 web:
 exposure:
 include: heapdump
 endpoint:
 heapdump:
 access: unrestricted

建议你在测试环境确认：

端点是否仍按预期可访问；
安全配置是否仍符合内网/零信任策略；
是否存在把高敏感诊断端点暴露到错误网络边界的风险。

2）布尔型配置值解析更严格

3.5 代际对 .enabled 这类布尔配置的可接受值收紧为更一致的 true / false。如果你的历史配置里混入了不规范值，升级后应检查是否产生行为变化。

建议排查：

application.yml / application.properties；
环境变量注入后的映射值；
Helm Chart / Kustomize / Ansible 模板里的布尔值渲染方式。

3）Profile 命名校验更严格，但 3.5.1 起已部分放宽

Spring Boot 3.5 代际增强了 Profile 命名校验；官方 Release Notes 同时说明：从 3.5.1 开始，这些限制已部分放宽，额外允许 .、+、@ 字符，也可以通过 spring.profiles.validate=false 关闭校验。

如果你们组织里有历史遗留 Profile 命名习惯，比如：

prod-cn
gray@hz
perf.test

建议在升级后跑一次完整启动验证，确认 Profile 解析与加载顺序没有偏差。

4）按名称注入 `taskExecutor` 的代码需要留意

Spring Boot 3.5 Release Notes 明确指出：自动配置的 TaskExecutor 不再同时提供 taskExecutor 和 applicationTaskExecutor 两个 Bean 名称，现在只提供 applicationTaskExecutor。

如果你们代码里存在按名称获取执行器的写法，例如：

@Qualifier("taskExecutor")
手动 getBean("taskExecutor")
XML 或脚本化配置里写死旧名称

那就要重点回归这部分逻辑。更稳妥的做法是改成依赖 applicationTaskExecutor，避免在未来版本继续背兼容包袱。

七、升级前后的实操检查单

为了让这次补丁升级更可控，可以按下面的顺序执行。

升级前

锁定当前生产版本与构建产物；
导出一份依赖树，确认是否显式覆盖了 Spring AMQP、Spring Data、Spring Integration 相关版本；
识别所有依赖 Actuator、TaskExecutor、Profile、布尔配置开关的模块；
准备至少一轮完整的自动化测试与一轮烟雾验证。

升级中

把 Spring Boot 版本提升到 3.5.16；
执行依赖刷新；
运行单元测试、集成测试、启动测试；
对消息链路、数据库访问、接口调用、定时任务做重点验证。

升级后

检查 /actuator/health、/actuator/info 以及你们自定义观测端点；
检查日志里是否出现 Bean 注入名称变化、配置绑定失败、Profile 校验失败；
观察消息积压、线程池使用率、慢 SQL、启动耗时；
将 3.5.16 标记为 3.5 分支最终基线，并启动 4.x 升级计划。

八、现在是继续留在 3.5，还是直接上 4.x？

截至核实时，Spring 官方项目页显示 Spring Boot 当前最新主线版本为 4.1.0。因此从路线选择看，团队通常有三种策略：

策略 A：先稳定到 3.5.16，再规划 4.1

适合：生产系统多、变更窗口谨慎、近期不适合跨代升级的团队。

优点：

风险最低；
便于先完成一次补丁级基线收敛；
给 4.x 迁移预留独立测试周期。

策略 B：在测试环境同时启动 3.5.16 与 4.1 双线验证

适合：平台团队、公共框架团队、拥有较强自动化测试体系的组织。

优点：

能同步评估短期稳定性与中期迁移成本；
更早暴露跨代兼容性问题；
有利于制定统一升级路线。

策略 C：如果必须长期停留 3.5，评估商业支持

适合：合规要求高、升级窗口长、系统耦合深的企业场景。

因为官方已经明确 3.5.x 的 OSS 周期结束在即，所以“长期停留但不做支持兜底”会越来越被动。

九、给团队负责人的建议

如果你是技术负责人、架构师或中台维护者，我更建议把这次发布当成一个版本治理节点，而不是一次普通补丁升级。

你可以在本周内完成三件事：

把所有 3.5.x 服务统一到 3.5.16；
拉出仍按名称依赖 taskExecutor、依赖宽松布尔配置、依赖旧 profile 命名习惯的模块清单；
明确 4.0 / 4.1 的迁移时间表与负责人。

这样做的好处是，你不会在 3.5 OSS 窗口结束后，仍把版本决策停留在“以后再说”。

十、总结

Spring Boot 3.5.16 表面上只是一次小型维护发布，但它的意义并不小：

它是 Spring Boot 3.5.x 的最后一个 OSS 发布版本；
它把 Spring AMQP 3.2.12、Spring Data BOM 2025.0.13、Spring Integration 6.5.10 纳入最终补丁基线；
它适合作为仍在 3.5 分支上的团队的最终稳定落点；
它也在提醒你：该开始准备 4.x 了。

如果你今天只能做一件事，那就先把测试环境升到 3.5.16，跑完关键回归，再安排生产发布窗口。对仍处在 3.5 生命周期尾段的系统来说，这是成本最低、收益最高的一步。