Structured Output

type

Post

status

Published

date

Apr 6, 2026

slug

structured-output

summary

Agent 项目结构化输出开发指南

需求场景

从自由文本中抽取姓名、年龄、邮箱，拿到强类型 Java 对象：

问题：如何保证抽取结果可靠？

解决方案：两层保证

层次	保证内容	实现方式
类型层	字段名、类型、必填	Spring AI 自动生成 Schema
业务层	年龄范围、邮箱格式	validate() 方法

开发流程（3步）

步骤 1：定义 Java 类（目标对象）

关键点：

使用 record：自动生成不可变对象

@JsonPropertyDescription：告诉模型每个字段的含义

Spring AI 会自动根据这个类生成 JSON Schema

步骤 2：添加业务验证（保证数据合理性）

为什么需要 validate()？

Spring AI 保证 age 是 integer，但不保证是 0-150

Spring AI 保证 email 是 string，但不保证包含 @

validate() 是业务逻辑的最后一道防线

步骤 3：实现 Service 调用

关键点：

不需要手动配置 responseFormat

不需要手动生成 JSON Schema

Spring AI 根据 Person 类自动处理一切

两层保证如何工作

第一层：类型层（Spring AI 自动）

Spring AI 自动保证：

字段名必须是 name、age、email

类型必须匹配（age 必须是 integer）

必填字段都必须返回

JSON 自动转为 Java 对象

编译时类型安全

第二层：业务层（validate）

保证业务规则：

年龄 0-150（模型可能返回 999，符合类型，但不符合业务）

邮箱格式（模型可能返回 "abc"，符合 string，但不符合邮箱）

姓名非空

违反时抛出 IllegalArgumentException

使用示例

Controller

测试

响应：

关键点总结

为什么用 Record？

简洁：自动生成 getter、equals、hashCode

不可变：线程安全

类型安全：编译时检查

Spring AI 原生支持，自动生成 Schema

为什么需要 validate()？

Spring AI 的自动 Schema 只保证基本类型，不保证业务规则：

场景	Spring AI 保证	需要 validate()
age 是 integer	是	否
age 在 0-150	否	是
email 是 string	是	否
email 包含 @	否	是

validate() 是业务逻辑的最后一道防线。

Spring AI 自动做了什么？

当你调用 .entity(Person.class) 时，Spring AI 会：

分析 Record 类的字段类型

读取 @JsonPropertyDescription 注解

自动生成 JSON Schema

配置到模型请求中

将返回的 JSON 自动反序列化为 Java 对象

你不需要手动写任何 Schema 生成代码。

完整项目结构

核心总结

目标：从文本抽取信息，拿到强类型 Java 对象

两层保证：

类型层：Spring AI 自动生成 Schema + 反序列化

业务层：validate() 保证业务规则

关键代码（超简单）：

就这么简单！