用途:go-gen-jsonschema 是 Go 代码生成器,把 Go 结构体转成 JSON Schema 文件,并生成 Go 访问器(Schema(),可选 ValidateJSON())以及针对已注册接口的可选 JSON/YAML 解码。主要面向 LLM 函数调用:属性按结构体字段顺序输出(确定、可控提示),additionalProperties: false,普通字段与可空字段为必填,Optional[T] 字段可选,Go 文档注释成为 schema 的 description。
主要能力:通过两个 build tag 文件协作。schema.go(//go:build jsonschema)由你编写,含 panic 桩与标记注册,仅在生成时编译;jsonschema_gen.go(//go:build !jsonschema)由工具生成,基于 embed.FS 中的 jsonschema/*.json 提供真实实现。JSON 为默认,YAML 或两者需显式开启。生成物需提交,每个 T.json 附带 T.json.sum 校验和用于变更检测。
使用方式:需 Go 1.24+。添加工具:go get -tool github.com/tylergannon/go-gen-jsonschema/gen-jsonschema@latest。在类型文件加 //go:generate go tool gen-jsonschema;加 --validate 生成 ValidateJSON();加 --formats=both 或 --formats=yaml 控制接口解码。可用 CLI 生成桩:go tool gen-jsonschema new -out schema.go -methods 'Person=Schema,Address=Schema' --validate --generate。生成后运行 go mod tidy,验证 go build ./...、go test ./... 通过,且第二次 go generate ./... 无差异。
适用场景:为 LLM 函数调用生成确定性 schema;需要字段级描述、必填/可选/可空语义;需要枚举、判别联合、共享 $ref/$defs 等。
限制:不支持 map 与递归类型;已注册接口仅支持标量 I、Optional[I] 和直接一维 []I,不支持 Nullable[I]、固定数组、嵌套切片、命名切片容器或 Optional/Nullable 接口切片;外部包类型除 time.Time 外不支持。OpenAI 严格结构化输出中所有属性必须必填,应使用 Nullable 而非 Optional。