从问题场景来看，自由文本的“解析地狱”

先看我们现在拿到的 AI 回复：

使用者：帮我查一下订单号ORD123456789的状态
AI回复的观点是。您的订单ORD123456789当前状态是"已发货"，快递单号为SF1234567890，预计2026年7月25日送达。如有疑问请联系客服，

作为人类阅读很舒服，但程序要从中提取 订单状态快递单号预计送达时间就得写一堆正则：

String status = response.replaceAll.replaceAll;// 灾难
String tracking = response.replaceAll.replaceAll;// 更灾难

这段代码的脆弱性。任何一个后端老鸟看到都会血压飙升——AI 换个说法，解析全崩。

痛点：

• 正则维护成本高，稍微改动一句话就炸。
• 字段缺失或顺序变化导致空指针或错误数据。怎么说呢，
• 业务方需要一次又一次地手动补丁。

需要的是：让 AI 直接返回 JSON，像调一个正经 API 一样。其实，

至于方案对比，三种让 AI 输出结构化数据的方式

方式	原理	适用场景	可靠性
Prompt 约束	手动在 Prompt 中加入格式要求	快速验证、临时脚本	⭐⭐
.entity Bean 输出	自动把返回的 JSON 映射到 Java DTO	明确的 DTO 场景、生产代码	⭐⭐⭐
结构化转换器	基于 JSON Schema 严格约束输出结构和类型	复杂嵌套、强类型需求	⭐⭐⭐⭐

至于方式一。Prompt 约束

代码实现

package com.yunxi.ai.service;import org.springframework.ai.chat.client.ChatClient;import org.springframework.stereotype.Service;@Service
public class ChatService {
private final ChatClient chatClient;按理说，public ChatService {
this.chatClient = builder.build;}
/**
* 从使用者的输入提取使用者信息
*/
public String getUserInfo {
String prompt = """
请根据使用者输入的信息：%s
提取姓名，手机号，省，市，区县，详细地址，并严格按照以下 JSON 格式返回。不要包含任何其他内容
{
至于"name"，"姓名","phone": "手机号","province": "省","city": "市","district": "区县","address": "详细地址"
}
只返回 JSON，不要解释。""".formatted;return chatClient.prompt
.system
.user
.call
.content;}
}

测试结果

{
从"name"来看，"shiyunxi","phone": "","province": "北京市","city": "北京市","district": "朝阳区"。"address": "瑞平家园"
}

Pain Point：

1. A I 有时候不听话：可能在 JSON 前面加 “好的，这是您要的 JSON：”。
2. 字段可能缺失或改名：A I 自作主张把 "name" 写成 "user_name".
3. If you need strict compliance。this method is fragile.

至于方式二，Bean 输出

S​pring AI 提供了 .entity 方法，可直接把 AI 返回的 JSON 映射到 Java 类，这才是正式生产级做法。

.DTO 定义 & 代码实现

package com.yunxi.ai.dto;import lombok.Data;@Data
public class UserInfo {
private String name;
老实说，private String phone;private String province;private String city;private String district;private String address;怎么说呢，}

public UserInfo getUserInfoV2 {
return chatClient.prompt
.system
.user
.call
.entity;}
@GetMapping
public UserInfo getUserInfoV2 {
return chatService.getUserInfoV2;}

. 测试结果

{
再看"name"，"shiyunxi","phone": "","province": "北京市","city": "北京市","district": ""。"address": "瑞平家园"
}

The conversion process behind .entity:

1. S​pring AI 自动在 Prompt 中追加 “请按以下 schema 返回 JSON”。
2. A I 返回后用 Jackson 将字符串反序列化成 UserInfo .
3. If output is not a valid JSON,an exception is thrown – so you instantly know when something goes wrong.
\end{ol}

从方式三来看。结构化转换器

If you need fine‑grained control over field types,mandatory/optional flags or descriptions,use S​tructuredOutputConverter .

. DTO 注解示例

package com.yunxi.ai.dto;import com.fasterxml.jackson.annotation.JsonPropertyDescription;import lombok.Data;@Data
public class UserInfo {
@JsonPropertyDescription
private String name;@JsonPropertyDescription
private String phone;@JsonPropertyDescription
private String province;@JsonPropertyDescription
private String city;@JsonPropertyDescription
private String district;@JsonPropertyDescription
private String address;}
}

. 调用示例

import org.springframework.ai.output.BeanOutputConverter;

public UserInfo getUserInfoV3 { return chatClient.prompt .system .user .call .entity);}

The converter reads @JsonPropertyDescription annotations and builds a JSON‑Schema payload that is sent to LLM:

json { "$schema":"https://json-schema.org/draft/-/schema","type":"object","properties":{ 从"name"来看，{"type":"string","description":"姓名"},"phone":{"type":"string"。"description":"手机号"},... },"additionalProperties":false }

Because schema is explicit,model almost never deviates from expected shape.

. 打印大模型请求日志

• *配置内置的* S​impleLoggerAdvisor : add it to client builder.
• *调低日志级别* 为 DEBUG，以便看到完整请求/响应。

// 在 ChatService 构造函数里加入日志提高器
public ChatService {
this.chatClient = builder
.defaultAdvisors)
.build;}

yaml

logging: level这方面，org.springframework.ai.chat.client.advisor: DEBUG # 开启日志输出

Pitfalls & Avoidance Guide

Pitfall 1：AI 在 JSON 前后加了 “废话”

json 好的。如下： { "orderId":"ORD123456789",... }

Solve:

• Prompt 约束 – 在提示词里写 “只返回 JSON，不要任何解释”。
• Bean/Converter – Spring AI 会自动抽取首个合法 JSON 块。
• 终极方案 – 手动截取第一个 { 与最终一个 } 区间。\end{ul}

Pitfall 2：字段名不匹配

A I 把 "trackingNumber"` 改成了下划线风格 "tracking_number".

Solve:

• Add multiple possible names via Jackson’s @JsonAlias..
• The StructuredOutputConverter forces exact property names through schema.
\end{ul}

---