结构化输出:Go 泛型 + JSON Schema 的类型安全之道
引言:模型返回的字符串,永远不靠谱
从系列第 1 篇起,我们一直在和模型返回的「自由文本」打交道:chat.Choices[0].Message.Content 是个 string,你想从里面提取一个名字、一个日期、一组标签,只能靠正则或字符串切割。这注定是脆弱的——模型今天可能返回 {"name": "张三"},明天就给你来个 "姓名:张三" 或者干脆在 JSON 外面多套一层 markdown 代码块。
这正是「结构化输出」(Structured Output)要解决的问题:告诉模型「你必须按我给的这个 JSON 结构来回答」,模型就会严格遵守,输出的每一个字段、每一个类型都在你的掌控之中。
本篇用 Go 把它跑通,核心就一句话:用 Go 泛型定义数据结构,用反射自动生成 JSON Schema,再把 Schema 交给模型,最后把返回的 JSON 无痛反序列化回同一个 struct——类型安全从头贯到尾。
| 传统做法 | 结构化输出 |
|---|---|
| 模型返回自由文本,正则/切割提取 | 模型返回严格 JSON,直接反序列化 |
| 字段类型靠约定,随时可能崩 | Schema 约束类型,字段名类型都锁死 |
| 提示词里手写「返回 JSON 格式」 | JSON Schema 形式化声明,模型强遵循 |
| 解析失败只能重试 | 从源头保证结构合法 |
一、先讲清三个概念:JSON Schema 到底是什么
在动手前,把三个容易混的概念对齐一下。
- JSON Schema:一种用 JSON 写的「数据形状说明书」。它描述一个 JSON 应该有哪些字段、每个字段是什么类型、哪些必填。比如:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["name", "age"]
}
-
结构化输出(Structured Output):OpenAI 提供的能力,你把上面的 Schema 传进去,模型就保证输出是符合这个 Schema 的合法 JSON。注意它不是「提示词里求模型返回 JSON」,而是底层强制约束,保证率远高于 prompt 约定。
-
Go 泛型 + 反射生成 Schema:我们不想手写上面那段 JSON Schema(字段一多就啰嗦且易错),而是先定义一个 Go struct,用
invopop/jsonschema这个库的反射能力,从 struct 自动反射出等价的 JSON Schema。泛型函数让这个「struct → Schema」的映射变得类型安全。
三者串起来的链路是:
Go struct(类型安全的源头)
│ jsonschema 反射(泛型 GenerateSchema[T])
▼
JSON Schema(交给模型的约束)
│ Responses API 结构化输出
▼
模型返回合法 JSON
│ json.Unmarshal 回同一个 struct
▼
Go struct(类型安全回到终点)
二、为什么用泛型:一次定义,两处复用
先看一个典型业务场景:让模型从一段自然语言里抽取「人物信息」,返回结构化的 Person。
type Person struct {
Name string `json:"name" jsonschema_description:"人物的姓名"`
Age int `json:"age" jsonschema_description:"人物的年龄"`
City string `json:"city" jsonschema_description:"人物所在城市"`
Tags []string `json:"tags" jsonschema_description:"描述人物的标签列表"`
}
传统做法里,这个 struct 只是「反序列化的目标」;而结构化输出里,它同时还是「生成 Schema 的源头」。为了不写死针对 Person 的重复代码,我们把「struct → Schema」抽成一个泛型函数:
import (
"encoding/json"
"github.com/invopop/jsonschema"
)
// GenerateSchema 从任意 Go struct 反射生成 JSON Schema。
// T 是类型参数,让「生成 Schema」和「反序列化」共享同一个类型,从编译期保证一致。
func GenerateSchema[T any]() (map[string]any, error) {
reflector := jsonschema.Reflector{
// 结构化输出只支持 JSON Schema 的一个子集,这两个配置是必须的:
AllowAdditionalProperties: false, // 不允许 schema 外的额外字段
DoNotReference: true, // 内联展开,不生成 $defs/$ref 引用
}
var v T
schema := reflector.Reflect(v)
data, err := json.Marshal(schema)
if err != nil {
return nil, err
}
// 关键:保留原始 JSON 值,避免整数约束在 float64 里被舍入
var rawSchema map[string]json.RawMessage
if err := json.Unmarshal(data, &rawSchema); err != nil {
return nil, err
}
result := make(map[string]any, len(rawSchema))
for key, value := range rawSchema {
result[key] = value
}
return result, nil
}
这段代码是整篇的地基,几个要点必须吃透:
- 泛型参数
T any():调用时写GenerateSchema[Person](),Person这个类型同时约束了「生成什么 Schema」和「反序列化回什么类型」。将来你改了Person的字段,Schema 会跟着变,不需要再维护第二份手写 Schema。 AllowAdditionalProperties: false:默认就是false,这里显式写出是为了强调——结构化输出要求严格模式,多余的键会导致校验失败。DoNotReference: true:不生成$defs/$ref,把嵌套结构全部内联。OpenAI 结构化输出对$ref的支持有限,内联最省心。json.RawMessage那一段:反射出的 schema 里整数是int,直接json.Marshal再Unmarshal成map[string]any会把整数变成float64,可能在边界值上丢精度。用RawMessage中转能保留原始 JSON 数值。
三、把 Schema 交给模型:Responses API 结构化输出
Schema 有了,接下来用 openai-go 的 Responses API 把它用起来。第 1 篇提过,Responses API 是 OpenAI 现在的主推接口,结构化输出也围绕它设计。
package main
import (
"context"
"encoding/json"
"fmt"
"os"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/option"
"github.com/openai/openai-go/v3/responses"
"github.com/invopop/jsonschema"
)
type Person struct {
Name string `json:"name" jsonschema_description:"人物的姓名"`
Age int `json:"age" jsonschema_description:"人物的年龄"`
City string `json:"city" jsonschema_description:"人物所在城市"`
Tags []string `json:"tags" jsonschema_description:"描述人物的标签列表"`
}
// GenerateSchema 实现同第二节(完整版见上),这里保留完整可运行代码
func GenerateSchema[T any]() (map[string]any, error) {
reflector := jsonschema.Reflector{
AllowAdditionalProperties: false,
DoNotReference: true,
}
var v T
schema := reflector.Reflect(v)
data, err := json.Marshal(schema)
if err != nil {
return nil, err
}
var rawSchema map[string]json.RawMessage
if err := json.Unmarshal(data, &rawSchema); err != nil {
return nil, err
}
result := make(map[string]any, len(rawSchema))
for key, value := range rawSchema {
result[key] = value
}
return result, nil
}
func main() {
client := openai.NewClient(
option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
)
ctx := context.Background()
// 1. 用泛型从 Person 反射出 JSON Schema
schema, err := GenerateSchema[Person]()
if err != nil {
panic(err)
}
// 2. 结构化输出请求:把 schema 作为 response_format 传进去
resp, err := client.Responses.New(ctx, responses.ResponseNewParams{
Model: openai.ChatModelGPT5_2, // 以服务商可用模型为准
Input: responses.ResponseNewParamsInputUnion{
OfString: openai.String("张三,32 岁,住在杭州,是一名狂热的开源贡献者和马拉松爱好者"),
},
Text: responses.ResponseTextConfigParam{
Format: responses.ResponseFormatTextConfigUnionParam{
OfJSONSchema: &responses.ResponseFormatTextJSONSchemaConfigParam{
Name: "person",
Description: openai.String("从文本中抽取的人物信息"),
Schema: schema,
Strict: openai.Bool(true), // 开启严格模式
},
},
},
})
if err != nil {
panic(err)
}
// 3. 取回输出的 JSON 文本
text := resp.OutputText()
// 4. 反序列化回同一个 Person struct
var person Person
if err := json.Unmarshal([]byte(text), &person); err != nil {
panic(err)
}
fmt.Printf("%+v\n", person)
// 预期输出类似:{Name:张三 Age:32 City:杭州 Tags:[开源 马拉松]}
}
几个关键点:
Name字段是给这个 schema 起的名字(person),会出现在 OpenAI 后台的 schema 里,方便排查。Strict: openai.Bool(true)开启严格模式,模型会 100% 保证输出符合 Schema 且不包含多余字段。resp.OutputText()直接拿到最终输出文本(第 1 篇已用过这个方法)。- 类型闭环:
GenerateSchema[Person]()生成的 Schema 约束输出,json.Unmarshal又解回Person,中间的any/map只存在于边界处,业务代码全程是强类型。
提示:结构化输出要求模型支持。像 GPT-4o、GPT-5 系列都支持;某些第三方兼容接口(如 DeepSeek)对
response_format的支持情况不一,用之前先查服务商文档。对不支持严格 schema 的模型,退而求其次可以用response_format: {"type": "json_object"}只保证「是合法 JSON」,再自己校验字段。
四、速查清单:手写 Schema vs 泛型反射
| 维度 | 手写 JSON Schema | 泛型反射生成 |
|---|---|---|
| 字段多了怎么办 | 逐个手写,容易漏 | 加 struct 字段自动带上 |
| 类型一致性 | 手动保证,易写错 | struct 定义即类型,编译期锁定 |
| 与反序列化目标 | 两份,要人工对齐 | 同一份 struct,天然一致 |
| 嵌套结构 | 手写 $ref 或内联,繁琐 |
DoNotReference 自动内联 |
| 描述信息 | 手写 description |
jsonschema_description tag 自动带入 |
| 维护成本 | 高,改一处漏一处 | 低,单点修改 |
一句话记忆:struct 是唯一的真相来源(single source of truth),Schema 是它的投影,反序列化是它的回归。
五、容易踩的四个坑
- 忘了关
additionalProperties:默认虽然已经是false,但如果你用别的库或误设成true,严格模式下多余字段会直接导致请求失败或校验报错。 - 嵌套类型生成了
$ref:忘记设DoNotReference: true时,嵌套 struct 会生成$defs+$ref,部分模型/接口对$ref支持不佳,导致结构化输出失败。 - 整数被
float64污染:跳过json.RawMessage中转直接把 schema 转map[string]any,大整数可能在边界值上丢精度,第 2 节的代码就是为了规避这点。 - 模型不支持就硬上:结构化输出是模型能力,不是提示词技巧。先确认目标模型支持,否则请求会报参数错误。
六、小结与下一篇
到这里,你掌握了:JSON Schema 的本质、用 Go 泛型从 struct 反射生成 Schema、通过 Responses API 开启严格结构化输出、以及把结果无痛反序列化回强类型 struct 的完整闭环。这是「让 LLM 输出变得可信」的关键一步,也是后续《RAG 实战》《Agent 记忆》里数据落库、结构化编排的地基。
下一篇(系列第 9 篇):RAG 实战——给自己的博客建一个问答机器人。
版本说明
本文代码 API 均于 2026-11-20 逐字核对自官方 releases 页、README 与 pkg.go.dev,安装请以下列版本为准:
| 依赖 | 版本 | 安装命令 |
|---|---|---|
| openai-go | v3.103.0(2026-11-18 发布,官方 releases 页核实) | go get github.com/openai/openai-go/v3@v3.103.0 |
| invopop/jsonschema | v0.14.0(2026-04-23 发布,pkg.go.dev 核实) | go get github.com/invopop/jsonschema@v0.14.0 |
- Go 工具链要求:openai-go v3.103.0 延续 v3 系列要求 Go 1.26+(系列第 1 篇已说明;若项目停留在 Go 1.25 请固定 v3.74.0,更早版本固定 v3.44.0);invopop/jsonschema v0.14.0 要求 Go 1.24+。
- 官方文档与源码:
- openai-go 仓库:github.com/openai/openai-go(结构化输出示例见 README「Structured Outputs」小节,
responses.ResponseTextConfigParam、responses.ResponseFormatTextJSONSchemaConfigParam、responses.ResponseFormatTextConfigUnionParam字段抄录自其源码)。 - invopop/jsonschema:github.com/invopop/jsonschema,
Reflector的AllowAdditionalProperties、DoNotReference字段说明见 pkg.go.dev/github.com/invopop/jsonschema。 - OpenAI 平台文档:platform.openai.com/docs(结构化输出概念与约束)。
- openai-go 仓库:github.com/openai/openai-go(结构化输出示例见 README「Structured Outputs」小节,
- 文中模型名(
openai.ChatModelGPT5_2)与结构化输出的可用性,以你的服务商控制台为准。
本文是「Go AI 应用开发」系列第 8 篇(共 18 篇规划),阶段二「Go AI 框架」第四篇。上一篇:《Eino 图编排实战:分支、循环与人机协同中断恢复》;系列前篇:《大模型 API 基础》、《Function Calling 教程》、《Embedding 与语义检索》、《SSE 流式输出教程》、《Go AI 框架选型横评》、《Eino 入门》。下一篇预告:《RAG 实战:给自己的博客建一个问答机器人》。
- 《Go 程序设计语言》(Go 语言圣经,机械工业出版社) —— Go 官方团队出品,公认入门第一书
- 《Go 语言实战》(异步图书,人民邮电出版社) —— 实战导向,面试前巩固工程手感
- 《Go 语言编程之旅:一起用 Go 做项目》(博文视点,电子工业出版社) —— 项目驱动入门,从零写出完整应用
- Keychron K1Max 矮轴机械键盘(Mac/Win 双系统,QMK/VIA 开源改键) —— 轻薄矮轴 + 开源固件,程序员桌面常客
- 罗技 MX Master 3S 无线鼠标(Flow 跨屏,静音电磁滚轮) —— 人体工学设计,写代码一整天手不酸
以上链接含京东联盟推广代码;通过链接购买本站可能获得少量佣金,不影响你的购买价格。
每周更新 Go + AI 应用开发实战:AI 面试官完整项目、MCP、Agent 工程化,完整源码随文章首发。
微信扫码,或搜索「Go2AI之路」关注,第一时间获取系列更新与源码,不再错过任何一篇。