Go encoding/hex.InvalidByteError 怎样定位非法十六进制字符

我在接收外部十六进制 ID 时遇到过一种很典型的排障场景：解码失败只打印出一个 error，日志能说明“输入不对”，却说不清是哪个字符、位于第几个输入字节。真正有用的做法不是把错误字符串再包一层，而是利用 encoding/hex.Decode 已经返回的部分结果和错误类型。

官方地址：https://pkg.go.dev/encoding/hex#InvalidByteError

如果错误可以断言为 hex.InvalidByteError，就能拿到非法字节；它在输入切片中的位置通常是已写入字节数的两倍。奇数长度则属于 hex.ErrLength，不能按非法字符处理。

先把 Decode 的返回值拆开

hex.Decode 的输入是一串十六进制字符，两个字符对应一个输出字节。返回的 n 表示已经写入目标缓冲区的字节数，err 决定后续是否需要定位具体字符。下面的代码只演示返回值关系，不把示例输出冒充成运行截图。

package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	src := []byte("4f6b7a")
	dst := make([]byte, hex.DecodedLen(len(src)))

	// n 是已经写入 dst 的字节数，err 负责描述输入边界问题。
	n, err := hex.Decode(dst, src)
	if err != nil {
		// 保留 n，排障时它能帮助定位错误附近的输入位置。
		fmt.Printf("decoded=%d err=%v\\n", n, err)
		return
	}

	// 只有 err 为 nil 时，才把完整 dst 当作成功结果使用。
	fmt.Printf("decoded=%d value=%q\\n", n, dst[:n])
}

输入长度是偶数且字符都合法时，n 等于 len(src)/2。输入包含非法字符时，n 通常表示错误前已经完成的字节数；这给了我们一个稳定的定位基准。

InvalidByteError 能告诉我们什么

hex.InvalidByteError 本质上携带一个非法输入字节。用类型断言拿到它后，可以用 %q 打印原始字符，也可以把它转换为整数，避免控制字符在日志中不可见。

func explainHexError(src []byte, n int, err error) string {
	if err == nil {
		// nil 表示没有解码错误，n 是有效输出长度。
		return fmt.Sprintf("ok: decoded=%d", n)
	}

	if err == hex.ErrLength {
		// 奇数长度缺少半个十六进制字符，不能归因给某个完整字节。
		return fmt.Sprintf("odd length: input_bytes=%d", len(src))
	}

	var bad hex.InvalidByteError
	if errors.As(err, &bad) {
		// 每个输出字节消耗两个输入字符，n*2 是错误字节的起始偏移。
		inputOffset := n * 2
		return fmt.Sprintf("invalid byte %q at input[%d]", byte(bad), inputOffset)
	}

	// 保留未知错误，避免诊断函数掩盖未来的库行为变化。
	return fmt.Sprintf("decode failed after %d bytes: %v", n, err)
}

这段函数需要在文件顶部同时导入 errors、encoding/hex 和 fmt。这里用 errors.As 而不是直接比较错误字符串，是为了让包装过的错误仍能被识别。

定位公式的前提是标准的两字符一字节编码：如果 n=3，说明前 6 个输入字符已经组成 3 个输出字节，候选非法字符从 src[6] 附近开始。为了让日志更好读，我通常还会截取错误位置前后各两个字符，但不会把完整的外部令牌写入日志。

为什么奇数长度要单独处理

例如 "4f6" 只有三个十六进制字符，前两个可以组成一个字节，最后一个字符却没有配对项。此时问题不是某个字符不在十六进制集合里，而是输入结构不完整，因此应该记录长度和来源，不要伪装成 InvalidByteError。

func decodeHex(src []byte) ([]byte, error) {
	if len(src)%2 != 0 {
		// 提前返回能把“缺半个字符”和“字符非法”分成两条告警路径。
		return nil, fmt.Errorf("hex input has odd length %d: %w", len(src), hex.ErrLength)
	}

	dst := make([]byte, hex.DecodedLen(len(src)))
	n, err := hex.Decode(dst, src)
	if err != nil {
		// 只返回已写入部分，调用方可按需要决定是否丢弃它。
		return dst[:n], err
	}
	return dst[:n], nil
}

提前判断长度不是必须的，hex.Decode 自己也会返回相应错误；它的价值在于把入口处的业务日志分成“长度异常”和“字符异常”。如果调用链上已经统一处理 ErrLength，也可以省略这层判断，避免重复包装。

把诊断放到导入边界，而不是业务深处

在小流量脚本里，直接打印错误足够了；在批量导入、消息消费或 API 入参处理中，我更倾向于在解码边界生成结构化诊断。这样后面的业务函数只接收合法字节，不必反复判断半成品。

type HexDiagnostic struct {
	InputOffset int
	BadByte     byte
	Decoded     int
	Kind        string
}

func diagnoseHex(src []byte, n int, err error) *HexDiagnostic {
	if err == nil {
		return nil
	}
	if err == hex.ErrLength {
		// 没有完整非法字节时，用 -1 表示位置不存在。
		return &HexDiagnostic{InputOffset: -1, Decoded: n, Kind: "odd-length"}
	}
	var bad hex.InvalidByteError
	if errors.As(err, &bad) {
		// InvalidByteError 的值来自输入，可用于指标标签前先做白名单化。
		return &HexDiagnostic{InputOffset: n * 2, BadByte: byte(bad), Decoded: n, Kind: "invalid-byte"}
	}
	return &HexDiagnostic{InputOffset: -1, Decoded: n, Kind: "other"}
}

这类结构体的好处是可以在边界层统一记录 Kind、解码进度和位置，再由日志层决定是否显示非法字节。对用户提交的令牌、密钥或身份标识，建议只记录位置和错误类别，不记录原文片段。

我会保留的几个边界

我实际最看重的是“错误分类先于错误文案”。错误文案适合给人看，Kind、InputOffset 和 Decoded 才适合进入指标或后续聚合。若解码输入来自敏感凭据，诊断对象也应该在日志边界做脱敏。

相关问题

InvalidByteError 的位置一定是 n*2 吗？

在标准两字符一字节的十六进制输入中，这是定位错误字符的实用基准；如果代码对输入做过预处理，则应以传给 Decode 的原始切片为准。

可以直接比较 error.Error() 吗？

不建议。比较 hex.ErrLength 或用 errors.As 识别 InvalidByteError 更稳定，也能兼容错误包装。

Decode 返回的部分字节能继续使用吗？

除非业务明确支持增量恢复，否则应当把它视为诊断信息。输入已经不完整或包含非法字符，继续使用半成品容易把错误带到更深层。