Go jsonschema 怎样复用编译结果校验多份文档

如果一批请求使用同一份 JSON Schema，Go 里不必每次都重新编译。github.com/santhosh-tekuri/jsonschema/v5 的典型做法是先用 Compiler 注册资源并得到 *jsonschema.Schema，后续文档只做解析和 Validate。这样编译成本集中在初始化阶段，校验循环更简单。

官方地址：https://pkg.go.dev/github.com/santhosh-tekuri/jsonschema/v5

复用的关键不是缓存原始 JSON 字符串，而是缓存已经编译完成的 *jsonschema.Schema；同一规则校验多份文档时，编译只做一次。

一、先把 Schema 编译成可复用对象

先安装 v5 模块。示例把 Schema 放在内存字符串里，真实项目也可以从文件读取；关键顺序不变：创建 Compiler、加入资源、调用 Compile。

go get github.com/santhosh-tekuri/jsonschema/v5

package main

import (
    "fmt"
    "strings"

    "github.com/santhosh-tekuri/jsonschema/v5"
)

func compileOrderSchema() (*jsonschema.Schema, error) {
    schemaText := `{
        "type": "object",
        "required": ["id", "amount"],
        "properties": {
            "id": {"type": "string"},
            "amount": {"type": "number", "minimum": 0}
        }
    }`

    // Compiler 管理 Schema 资源；相同规则只需要初始化一次。
    compiler := jsonschema.NewCompiler()
    // 资源名是 Compile 使用的地址，不能带片段标识符。
    if err := compiler.AddResource("order.json", strings.NewReader(schemaText)); err != nil {
        return nil, fmt.Errorf("注册 Schema 失败: %w", err)
    }
    // Compile 返回可反复调用 Validate 的编译结果。
    schema, err := compiler.Compile("order.json")
    if err != nil {
        return nil, fmt.Errorf("编译 Schema 失败: %w", err)
    }
    return schema, nil
}

Compile 的错误表示 Schema 本身没有成功编译，应该在服务启动或配置加载阶段尽早暴露。只要 Schema 内容不变，就不要把这段编译逻辑放进每个请求的循环。

二、在循环中解析并重复 Validate

编译完成后，每份文档仍然要先经过 JSON 解析，再交给同一个 Schema。解析失败和 Schema 校验失败不是一回事，建议分别返回或记录。

下面的函数承接上一个示例，并额外使用 encoding/json 和 log。

func validateDocuments(schema *jsonschema.Schema, documents []string) []error {
    var failures []error
    for index, raw := range documents {
        var value interface{}
        // Unmarshal 只负责把文本变成 JSON 值，不负责检查业务 Schema。
        if err := json.Unmarshal([]byte(raw), &value); err != nil {
            failures = append(failures, fmt.Errorf("文档 %d JSON 解析失败: %w", index+1, err))
            continue
        }
        // 同一个编译结果可以被多份已经解析的文档反复校验。
        if err := schema.Validate(value); err != nil {
            failures = append(failures, fmt.Errorf("文档 %d Schema 校验失败: %w", index+1, err))
        }
    }
    return failures
}

func main() {
    schema, err := compileOrderSchema()
    if err != nil {
        log.Fatal(err)
    }

    documents := []string{
        `{"id":"A-100","amount":18.5}`,
        `{"id":"A-101","amount":-2}`,
        `{"id":"A-102"}`,
    }
    // 先完成一次编译，再把结果交给批量校验函数。
    failures := validateDocuments(schema, documents)
    for _, failure := range failures {
        log.Println(failure)
    }
}

上例中的第二份文档会触发 minimum 约束，第三份缺少 amount。这类校验错误不会要求重新编译 Schema；修正输入后仍可使用同一个对象。

三、区分三类错误并处理并发边界

批量校验时可以按下面的边界处理：

• JSON 解析错误：输入不是合法 JSON，问题在文档文本本身。
• Schema 编译错误：规则文件或它引用的资源有问题，问题在启动配置。
• *jsonschema.ValidationError：文档是合法 JSON，但没有满足约束，可读取路径和嵌套原因。

如果需要把校验路径写入日志，可以用类型断言读取 InstanceLocation、KeywordLocation 和 Causes。不要把所有错误都压成一个字符串，否则排查数组项或嵌套对象时会丢掉定位信息。

同一个只读的编译结果适合被多个请求复用；但若请求会改变 Schema、Compiler 配置或资源内容，就应当建立新的编译对象。缓存时可以用 Schema 文件的版本、内容摘要或配置版本作为键，避免不同规则误用同一个结果。

四、带 $ref 的 Schema 怎样扩展

当主 Schema 引用了另一个资源时，先用同一个 Compiler 调用多次 AddResource，再编译主资源。不要在每份文档到来时临时加载依赖。

compiler := jsonschema.NewCompiler()

// $ref 指向 obj.json，因此两个资源都要在 Compile 前注册。
if err := compiler.AddResource("main.json", strings.NewReader(`{"$ref":"obj.json"}`)); err != nil {
    log.Fatal(err)
}
if err := compiler.AddResource("obj.json", strings.NewReader(`{"type":"object"}`)); err != nil {
    log.Fatal(err)
}
// 编译主资源后，返回的 Schema 仍然可以复用给多份文档。
schema, err := compiler.Compile("main.json")
if err != nil {
    log.Fatal(err)
}

最终可以把编译阶段放进 sync.Once 或应用启动钩子，把得到的 Schema 交给处理函数。清理时释放外部资源、关闭文件读取器即可；*jsonschema.Schema 本身作为规则对象保存在应用生命周期内。

常见问题

每份文档都要调用 Compile 吗？ 不需要。只有规则发生变化，或缓存键指向新的规则版本时，才重新编译。

校验失败后要丢弃 Schema 吗？ 通常不用。校验失败说明当前文档不符合规则，不代表编译结果失效；只有规则资源变化或编译配置变化时才换对象。

为什么不能只缓存 schemaText？ 缓存原文仍然要重复解析和编译；缓存 *jsonschema.Schema 才能直接进入多文档校验阶段。

总结

Go jsonschema 的复用边界很清晰：初始化时注册资源并编译一次，运行时对每份文档执行 json.Unmarshal 和 Schema.Validate。把编译错误挡在启动阶段，把解析错误和 ValidationError 分开记录，再为不同 Schema 版本设置独立缓存键，就能在不改变校验规则的前提下稳定处理多份文档。