Go encoding/json/v2 SemanticError 怎样定位嵌套字段的解码错误

我在把配置文件从字符串字段扩展成嵌套结构时，最容易误判的一类错误是：JSON 本身格式正确，但某个值无法映射到目标 Go 类型。Go 1.27 的 encoding/json/v2 会把这类问题包装成 SemanticError，除了错误文本，还能给出字节偏移、JSON Pointer 和目标 Go 类型。

官方地址：https://pkg.go.dev/encoding/json/v2@go1.27.3#SemanticError

真正适合放进日志和告警的字段不是一整段英文错误文本，而是结构化的 ByteOffset、JSONPointer、JSONKind、JSONValue 与 GoType。下面用一个嵌套配置例子说明怎样拿到它们。

先分清语法错误和语义错误

缺少右括号、字符串没有闭合等问题属于 JSON 语法层；输入可以被解析成 JSON，但数字、字符串或对象形状无法落到目标 Go 值时，才进入语义层。两者的处理方式不同：语法错误通常先看输入字节，语义错误则要看目标类型和失败路径。

例如下面的 retries 期待整数，却收到字符串。这个 JSON 文本是合法的，失败点在“JSON 值如何变成 Go 值”这一步：

package main

import (
	"encoding/json/v2"
	"fmt"
)

type Service struct {
	Name    string `json:"name"`
	Retries int    `json:"retries"`
}

type Config struct {
	Service Service `json:"service"`
}

func main() {
	// JSON 语法正确，但 retries 的字符串值不能直接解码为 int。
	input := []byte(`{"service":{"name":"worker","retries":"three"}}`)
	var cfg Config
	if err := json.Unmarshal(input, &cfg); err != nil {
		fmt.Println(err)
	}
}

不要只根据错误字符串包含了哪个字段来写解析器。官方文档明确说明，SemanticError 描述的是 JSON 数据与 Go 数据之间的语义转换失败，而且错误文本内容可能随版本变化。

用 errors.As 取出嵌套错误上下文

实际项目里，错误经常经过业务层再包装一次，所以应使用 errors.As，而不是直接类型断言。JSONPointer 表示 JSON Pointer 路径；GoType 是无法处理的目标 Go 类型，可能为空，因此输出时要允许缺省。

package main

import (
	"encoding/json/v2"
	"errors"
	"fmt"
	"reflect"
)

func reportDecodeError(input []byte, err error) {
	var semantic *json.SemanticError
	if !errors.As(err, &semantic) {
		// 语法错误或其他错误不应伪装成语义错误。
		fmt.Printf("decode failed: %v\n", err)
		return
	}

	goType := ""
	if semantic.GoType != nil {
		goType = semantic.GoType.String()
	}
	value := string(semantic.JSONValue)
	if value == "" {
		value = ""
	}
	// Pointer 适合机器检索，Error 文本只作为人类补充信息。
	fmt.Printf("semantic error: offset=%d pointer=%s kind=%s value=%s go_type=%s\n",
		semantic.ByteOffset, semantic.JSONPointer, semantic.JSONKind, value, goType)
	_ = input // 输入内容可交给后续行列转换，不在日志中直接打印密文配置。
}

var _ reflect.Type

上面的函数把 JSONValue 转为字符串只是为了展示；生产日志应限制长度，并对可能包含敏感配置的值做脱敏。JSONKind 和 GoType 组合起来，通常比错误文本更容易用于聚合。

把 ByteOffset 转成行列，保留 Pointer 做定位键

ByteOffset 是字节偏移，适合机器记录，不等同于“第几个字符”。配置文件经常有换行和多字节 UTF-8 字符，因此转换前要检查偏移是否落在输入范围内。JSON Pointer 则保留为原样字符串，例如 /service/retries。

func lineColumn(input []byte, offset int64) (line, column int, ok bool) {
	// 偏移越界时直接返回失败，避免日志处理器切片越界。
	if offset  int64(len(input)) {
		return 0, 0, false
	}
	line, column = 1, 1
	for index, current := range input[:offset] {
		if current == '\n' {
			line, column = line+1, 1
			continue
		}
		// 这里按字节计数，和 ByteOffset 的单位保持一致。
		_ = index
		column++
	}
	return line, column, true
}

func formatSemantic(input []byte, semantic *json.SemanticError) string {
	line, column, ok := lineColumn(input, semantic.ByteOffset)
	if !ok {
		return fmt.Sprintf("pointer=%s offset=%d", semantic.JSONPointer, semantic.ByteOffset)
	}
	return fmt.Sprintf("pointer=%s offset=%d line=%d column=%d",
		semantic.JSONPointer, semantic.ByteOffset, line, column)
}

这里的列号同样按字节计数，适合和编辑器或原始文件偏移对照；如果产品要展示“人眼看到的字符列”，应另写 UTF-8 rune 计数规则，不要把两种单位混在同一个字段里。

自定义解码器会影响哪些字段

如果类型实现了自定义解码方法，方法返回的 SemanticError 中，值为零的 ByteOffset、JSONPointer 和 GoType 可以由调用上下文补齐。这意味着自定义方法不应擅自把外层路径写死，也不应把内部错误改成无法展开的纯字符串。

自定义方法需要保留底层错误的可展开性：

func decodeAndWrap(input []byte, out any) error {
	// 保留原始错误链，调用方才能继续 errors.As 到 SemanticError。
	if err := json.Unmarshal(input, out); err != nil {
		return fmt.Errorf("load service config: %w", err)
	}
	return nil
}

若处理的是多个连续 JSON 值，可以用 jsontext.Decoder 配合 json.UnmarshalDecode。此时要把 io.EOF 当作流结束，而不是把它当成语义错误；单个值的错误仍可通过 errors.As 继续提取。

一套不依赖错误文本的输出策略

我通常按三层记录：

常见误区有三个：把 ByteOffset 当成 rune 下标；只记录 Error() 文本；为了得到路径而在外层重新扫描 JSON。前两种会让日志在多语言输入或版本升级后失真，最后一种会造成重复解析。优先使用 SemanticError 自带的上下文，必要时才做受控的行列转换。

结论：把 SemanticError 当成结构化诊断对象

处理 encoding/json/v2 的嵌套解码失败时，推荐顺序是：先用 errors.As 判断是否为 *json.SemanticError，再读取 JSONPointer 和 GoType，最后把 ByteOffset 转为展示位置。错误文本可以帮助人阅读，但不应成为程序分组和告警聚合的唯一依据。

相关问题

SemanticError 和 JSON 语法错误有什么区别？

前者是合法 JSON 无法映射到目标 Go 值，后者是输入连合法 JSON 都无法组成；两者应分别处理。

为什么 JSONPointer 为空？

错误可能发生在未知位置，或自定义解码器返回时没有足够上下文；调用方应允许它为空，不能自行拼接假路径。

可以直接比较 SemanticError 的错误文本吗？

不建议。官方文档提示其生成内容可能变化，应优先使用公开字段和错误链。