Go jsonschema 怎样展开嵌套字段的校验错误

用 Go 的 github.com/santhosh-tekuri/jsonschema/v5 校验嵌套 JSON 时，不要只打印 err.Error()。真正有用的信息在 *jsonschema.ValidationError：它保留当前错误的 InstanceLocation、KeywordLocation、Message，并通过 Causes 继续保存子错误。把这棵错误树递归展开，就能得到类似 /profile/address/city 这样的字段路径。

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

如果错误要返回给前端或写入结构化日志，推荐先用类型断言拿到 *jsonschema.ValidationError，再递归走完 Causes。页面展示通常需要叶子错误列表；排查 allOf、oneOf 或 $ref 时，则应保留完整层级或直接使用 DetailedOutput()。

先把校验错误看成一棵树

Schema.Validate 在文档不符合 Schema 时返回 *ValidationError。这个类型不是只有一段文本，而是一组可以继续处理的字段：

例如一个 profile 对象里同时有 name 类型错误和 address.city 缺失，根错误可能只承担聚合语义，真正需要显示给用户的是 Causes 里的具体节点。InstanceLocation 使用 JSON Pointer 形式，因此对象字段是 /profile/address/city，数组项通常会出现 /items/0 这样的索引。

先判断需要哪一种输出形状

这个包提供三种输出方向。FlagOutput() 只有是否有效，适合门禁；BasicOutput() 是扁平错误单元列表，适合表格、日志和简单接口；DetailedOutput() 按 Schema 结构保留嵌套 errors，适合排查组合关键字和跨引用关系。

package main

import (
    "encoding/json"
    "fmt"
    "errors"

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

// printStructuredError 只在校验错误属于 ValidationError 时读取结构化输出。
// 其他错误可能来自输入类型或校验循环，不能强行当作字段错误处理。
func printStructuredError(err error) {
    var validationErr *jsonschema.ValidationError
    if !errors.As(err, &validationErr) {
        // 非 ValidationError 保留原始文本，便于区分编译或运行时故障。
        fmt.Printf("非字段校验错误: %v\n", err)
        return
    }

    // DetailedOutput 保留 Causes 对应的层级，适合诊断复杂 Schema。
    detailed, marshalErr := json.MarshalIndent(validationErr.DetailedOutput(), "", "  ")
    if marshalErr != nil {
        // 序列化失败时不要丢掉原错误对象。
        fmt.Printf("错误输出序列化失败: %v\n", marshalErr)
        return
    }
    fmt.Println(string(detailed))
}

如果接口契约只需要一组字段错误，也可以调用 validationErr.BasicOutput()。它的每个单元包含 keywordLocation、absoluteKeywordLocation、instanceLocation 和 error，不必自己从错误文本中截取路径。

用递归函数展开到叶子错误

页面通常希望得到“字段路径、规则路径、消息”三列。可以定义一个自己的输出结构，然后从根节点开始递归；有子节点时继续向下，没有子节点时才追加结果。

package main

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

// FieldError 是业务层比 ValidationError 更稳定的展示模型。
type FieldError struct {
    Path          string `json:"path"`
    Rule          string `json:"rule"`
    Message       string `json:"message"`
    AbsoluteRule  string `json:"absoluteRule,omitempty"`
}

// flattenValidationError 只输出叶子节点，避免把聚合父节点重复显示给用户。
func flattenValidationError(node *jsonschema.ValidationError, out *[]FieldError) {
    if node == nil {
        return
    }
    if len(node.Causes) == 0 {
        // 叶子节点拥有最具体的实例路径和错误消息。
        *out = append(*out, FieldError{
            Path:         node.InstanceLocation,
            Rule:         node.KeywordLocation,
            Message:      node.Message,
            AbsoluteRule: node.AbsoluteKeywordLocation,
        })
        return
    }
    for _, child := range node.Causes {
        // 递归保留每一层的原始路径，不在这里拼接或改写 JSON Pointer。
        flattenValidationError(child, out)
    }
}

这里故意不把父节点的 InstanceLocation 与子节点再次拼接。库已经为每个错误节点记录了实例位置，手工拼接容易在 $ref、数组索引或组合 Schema 下得到重复路径。

数组字段和组合关键字怎么处理

数组错误的路径应原样保留索引。例如 /items/0/name 表示第一个元素的 name，业务层可以再把数字片段映射成“第 1 项”，但不要把原始 JSON Pointer 丢掉，否则后续定位原始请求会变得困难。

allOf、anyOf、oneOf 和 $ref 可能让错误树变深。对于这几类规则，父节点常常解释“哪组 Schema 没有通过”，子节点才说明具体失败字段。页面只展示叶子时，建议额外保留 Rule 或 AbsoluteRule；日志排查则直接保存 DetailedOutput()，以免失去组合关系。

如果同一个字段因为多个分支产生多条错误，不要用路径做唯一键后无条件覆盖。更稳妥的做法是以“实例路径 + 规则路径 + 消息”去重，或在接口层明确允许一个字段对应多条原因。

把展开结果接入校验门禁和通知

在请求处理链中，可以把流程分成四段：入口解析得到 JSON 值，Schema 校验负责产生错误树，转换器负责生成业务错误列表，最后由接口响应或日志通知消费。这样“校验失败”仍然是门禁条件，但“怎样展示失败原因”不会污染 Schema 本身。

package main

import (
    "errors"
    "net/http"

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

// validationResponse 统一接口层的成功与失败形状。
type validationResponse struct {
    Valid  bool         `json:"valid"`
    Errors []FieldError `json:"errors,omitempty"`
}

// validateRequest 把库错误转换成接口可消费的字段列表。
func validateRequest(schema *jsonschema.Schema, value interface{}) (validationResponse, int) {
    if err := schema.Validate(value); err != nil {
        var validationErr *jsonschema.ValidationError
        if errors.As(err, &validationErr) {
            var fields []FieldError
            // 失败时保留字段级原因，让调用方一次修正多个输入。
            flattenValidationError(validationErr, &fields)
            return validationResponse{Valid: false, Errors: fields}, http.StatusUnprocessableEntity
        }
        // 非字段错误不应伪装成用户输入错误。
        return validationResponse{Valid: false}, http.StatusInternalServerError
    }
    return validationResponse{Valid: true}, http.StatusNoContent
}

通知或日志里可以同时保存三份信息：原始错误的 Error() 文本用于快速检索，DetailedOutput() 用于复杂问题复盘，字段错误列表用于前端定位。三者的职责不同，不必为了“只保留一种格式”而互相替代。

常见问题

为什么只打印 Error() 看不到所有嵌套错误？

Error() 面向单条错误文本，复杂层级应读取 Causes，或调用 GoString()、DetailedOutput() 等结构化输出方法。

BasicOutput 和 DetailedOutput 选哪个？

前端字段列表、平面日志优先 Basic；需要保留组合 Schema 层级、跨文件引用和排查上下文时优先 Detailed。

能不能只用字符串切出字段路径？

不建议。库已经提供 JSON Pointer 路径字段，直接读取 InstanceLocation 更稳定，也不会受错误文本措辞变化影响。

总结

Go jsonschema 展开嵌套校验错误的关键不是重新解析错误字符串，而是保留库生成的错误树：先用 errors.As 取得 *ValidationError，再根据消费场景选择 BasicOutput() 或 DetailedOutput()，最后递归 Causes 并输出叶子节点的 InstanceLocation、KeywordLocation 和 Message。这样前端、接口、日志和失败通知可以共享同一套稳定的字段信息。