前两天，项目组开周会，我们后端组被老板点名了——“AI能力接得挺快，但你们这提示词里一堆让人晕的 JSON 字符串能不能整得优雅点？”
场面一度非常尴尬。
那一刻，我突然想起前几天翻 Spring AI 文档时瞄到的一句话：结构化输出（Structured Output）支持！
嘿，就是它了！今天这篇文章，我就用我昨天下午鼓捣了一下午的结果，跟你们聊聊这个“结构化输出转换器”是怎么一回事，有哪些玩法、用法、踩坑，适合谁用，不适合谁用。
结构化输出 API 是什么？
还记得你刚开始玩 AI 接口时，是不是一开始就让它直接输出文本？但随着业务需求上升，你很快就会遇到两个字： “结构” 。
比如我要从 AI 那里拿到如下内容：
但如果只是简单提示词 + 纯文本，结果可想而知——字段名千奇百怪，格式松散，解析代码写得你怀疑人生。
Spring AI 正是为了解决这种混乱，引入了结构化输出（Structured Output）能力。它不再只是给你一堆文本，而是可以直接解析为 Java 对象、Map、List！这就是它的魔力。
可用的转换器有哪些？
Spring AI 提供了多个转换器（Converter），用于将 AI 输出的“自然语言”或“JSON格式文本”转换为结构化数据。以下是它支持的主要几种：
简单来说：你可以让 LLM 输出结构化文本，而 Spring AI 帮你把这些东西直接“自动封装”成 Java 数据结构！
使用转换器怎么玩？
1. Bean 输出转换器（BeanOutputConverter）
这是我最喜欢的模式：你先定义好一个 Java 类，告诉 AI 你要的字段，它按你的定义来输出，然后你直接拿到一个 Java 对象，丝滑得不行！
定义 DTO：
使用 BeanOutputConverter：
Spring AI 会自动识别 MovieRecommendation.class 这个结构，让 LLM 给出的内容对齐这个结构，并自动映射为 Java 对象。
是不是很像你写 JSON 的时候前后端联调的“contract”那味儿？
2. 生成模式中的属性排序
默认情况下，Bean 的字段顺序可能不固定。
不过你可以通过添加 @JsonPropertyOrder 注解（Jackson 提供）来控制字段顺序：
这在提示词和模型格式需要严格对齐时，尤其重要。
3. 泛型 Bean 类型
如果你想要更加灵活，比如 Bean 中的 List 是泛型怎么办？
也可以！Spring AI 的 BeanOutputConverter 底层用的是 Jackson 的泛型解析机制，你只需要在使用时用 TypeReference 就可以搞定：
- Map 输出转换器（MapOutputConverter）
有时候，你只想偷个懒，不想定义 POJO 类，那 Map 是你的好朋友。
返回值会是 Map<String, Object>，适合你前期快速试验，或者结构经常变化但不严重依赖字段的场景。
不过要注意一点：你需要在提示词中清晰地告诉 AI 输出为 JSON 格式，否则容易翻车。
5. List 输出转换器（ListOutputConverter）
很多时候，我们希望 AI 输出一个对象的列表，比如：
你只需要：
就能优雅接住 LLM 的输出了！
支持的 AI 模型有哪些？
结构化输出功能并不是所有 AI 模型都能玩得转的，Spring AI 当前支持结构化输出的模型包括：
- OpenAI GPT-4, GPT-3.5
- Anthropic Claude 3
- Mistral（有限支持）
- Ollama 系列本地模型
- Azure OpenAI
- Gemini（Google 模型）
只要模型具备“输出 JSON 能力”或者支持 Function calling（像 OpenAI 的函数调用 API），Spring AI 基本上都能搞定。
内置 JSON 模式（JsonSchemaMode）
Spring AI 的一大亮点在于：它自动根据你的 Java 类型生成 JSON Schema，然后把这个 Schema 嵌入提示词中！
什么意思？
比如你想让 AI 输出 MovieRecommendation.class 的结构，它会生成类似这样的 prompt：
这玩意儿是标准的 JSON Schema，AI 更容易理解输出结构，准确率大幅提升，极大减少了解析错误！
尾声：我对结构化输出的理解总结
一下午摸索完这些，我有两个结论：
1. 它真的能提升开发效率。
再也不用费劲写正则去提取 LLM 的“模糊内容”，提示词清晰、结构清晰、解析清晰，写出来的代码也有模有样。
2. 它值得在中大型项目中推广。
尤其是后台系统、配置类系统、推荐系统、数据抽取场景，结构化输出能显著提高接口稳定性。
END
如果你现在正在做一个 AI 落地项目，或者正在尝试构建提示词链路，那么请记得一句话：
文本是玩具，结构是工程。
别等产品经理跟你说“这个字段多了，那个字段少了”，才想起来用结构化转换器。用 Spring AI 的结构化输出机制，让 LLM 成为你后端的可靠“服务者”而不是“猜谜者”。
我是 31 岁的小米，一个喜欢把技术讲成故事的程序员。如果你也喜欢这样的内容，记得点赞、收藏、转发让我知道！我们下期见～
我是小米，一个喜欢分享技术的31岁程序员。如果你喜欢我的文章，欢迎关注我的微信公众号“软件求生”，获取更多技术干货！
