Go AI 应用开发实战:从基础、MCP 到完整 Agent 项目

结构化输出: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 到底是什么

在动手前,把三个容易混的概念对齐一下。

  1. JSON Schema:一种用 JSON 写的「数据形状说明书」。它描述一个 JSON 应该有哪些字段、每个字段是什么类型、哪些必填。比如:
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "age"]
}
  1. 结构化输出(Structured Output):OpenAI 提供的能力,你把上面的 Schema 传进去,模型就保证输出是符合这个 Schema 的合法 JSON。注意它不是「提示词里求模型返回 JSON」,而是底层强制约束,保证率远高于 prompt 约定。

  2. 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 是它的投影,反序列化是它的回归。

五、容易踩的四个坑

  1. 忘了关 additionalProperties:默认虽然已经是 false,但如果你用别的库或误设成 true,严格模式下多余字段会直接导致请求失败或校验报错。
  2. 嵌套类型生成了 $ref:忘记设 DoNotReference: true 时,嵌套 struct 会生成 $defs + $ref,部分模型/接口对 $ref 支持不佳,导致结构化输出失败。
  3. 整数被 float64 污染:跳过 json.RawMessage 中转直接把 schema 转 map[string]any,大整数可能在边界值上丢精度,第 2 节的代码就是为了规避这点。
  4. 模型不支持就硬上:结构化输出是模型能力,不是提示词技巧。先确认目标模型支持,否则请求会报参数错误。

六、小结与下一篇

到这里,你掌握了: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.ChatModelGPT5_2)与结构化输出的可用性,以你的服务商控制台为准。

本文是「Go AI 应用开发」系列第 8 篇(共 18 篇规划),阶段二「Go AI 框架」第四篇。上一篇:《Eino 图编排实战:分支、循环与人机协同中断恢复》;系列前篇:《大模型 API 基础》、《Function Calling 教程》、《Embedding 与语义检索》、《SSE 流式输出教程》、《Go AI 框架选型横评》、《Eino 入门》。下一篇预告:《RAG 实战:给自己的博客建一个问答机器人》。

🛒 站长推荐(京东联盟)

以上链接含京东联盟推广代码;通过链接购买本站可能获得少量佣金,不影响你的购买价格。

📮 关注公众号「Go2AI之路」
Go2AI之路 公众号二维码

每周更新 Go + AI 应用开发实战:AI 面试官完整项目、MCP、Agent 工程化,完整源码随文章首发。

微信扫码,或搜索「Go2AI之路」关注,第一时间获取系列更新与源码,不再错过任何一篇。

wx

关注公众号

©2017-2026 鲁ICP备17023316号-1 Powered by Hugo · 隐私政策