Go encoding/hex.DecodeString 返回错误时怎样定位非法字节

我在把十六进制配置读进 Go 服务时，最初也把所有解码失败都当成“输入格式不对”。真正排查起来，奇数长度和非法字符是两种完全不同的线索：前者对应 hex.ErrLength，后者可以通过 hex.InvalidByteError 找到出问题的字节。先分层，再定位，日志里就不必打印整串可能包含敏感信息的令牌。

官方文档地址：https://pkg.go.dev/encoding/hex#DecodeString

先把解码失败分成两条线

hex.DecodeString 的输入是十六进制字符串，长度必须为偶数，每两个字符组成一个字节。输入长度是奇数时，标准库返回 hex.ErrLength；遇到不属于 0-9、a-f、A-F 的字符时，会返回描述非法字节的 hex.InvalidByteError。失败前已经解出的字节也会返回，因此不要在 err != nil 时继续把结果当成完整数据。

用标准错误先判断是哪种输入问题

我会把错误判断写在输入边界，而不是散落到业务分支里。errors.Is 适合判断哨兵错误 hex.ErrLength；errors.As 适合把错误转换为 hex.InvalidByteError。这样即使未来调用链给错误加了包装，判断仍然有清晰的语义。

package main

import (
    "encoding/hex"
    "errors"
    "fmt"
)

func describeHexInput(s string) string {
    decoded, err := hex.DecodeString(s)
    if err == nil {
        // 没有错误时，decoded 才是完整的二进制结果。
        return fmt.Sprintf("解码成功，得到 %d 个字节", len(decoded))
    }

    if errors.Is(err, hex.ErrLength) {
        // 奇数长度无法按两个十六进制字符组成一个字节。
        return fmt.Sprintf("长度错误：输入有 %d 个字符", len(s))
    }

    var invalid hex.InvalidByteError
    if errors.As(err, &invalid) {
        // InvalidByteError 给出非法字节，具体位置由原始字符串扫描得到。
        return fmt.Sprintf("包含非法字符 %q", byte(invalid))
    }

    // 保留未知错误，避免把其他输入故障误报成十六进制问题。
    return fmt.Sprintf("解码失败：%v", err)
}

这里的 decoded 只在成功分支使用；错误分支只提取诊断信息。特别是 hex.InvalidByteError 是一个描述非法字节的错误类型，拿到它并不等于已经得到字符下标。

把非法字节映射回输入位置

如果配置文件里有多段十六进制字段，只有“非法字符”还不够。可以沿着原字符串寻找第一个非十六进制字节，并同时保留它前面的字段上下文；对奇数长度则把最后一个字符单独标出来。这个扫描函数不重新解码，也不依赖错误文本，因此更适合做稳定的诊断信息。

func isHexDigit(b byte) bool {
    // 接受标准十六进制的三段 ASCII 范围。
    return (b >= '0' && b = 'a' && b = 'A' && b 

下标是字节下标，不是“第几个十六进制字节”。若返回 i，它对应输入中的第 i+1 个 ASCII 字符；如果输入来自 UTF-8 文本，非 ASCII 字符可能占多个字节，所以日志中应同时说明这是字节偏移。

生产边界要把错误信息和原始数据分开

我觉得最容易被忽略的是日志边界：错误定位需要足够具体，但完整的密钥、签名或用户令牌不应该跟着错误一起落盘。服务可以记录字段名、字节偏移、错误类别和输入长度；调试环境若确实需要样本，也应使用固定的脱敏值。

常见问题

为什么拿到 InvalidByteError 还不知道位置？

因为它描述的是非法字节本身，不承诺提供原字符串下标。用同一个输入做轻量扫描，就能得到稳定的字节偏移。

奇数长度能不能自动在末尾补 0？

只有协议明确规定允许补位时才可以。对密钥、摘要或签名这类值，自动补字符会改变数据含义，应该直接拒绝并让上游修正。

返回的 decoded 有一部分内容，能不能继续使用？

不建议。它只是错误发生前已经解出的前缀，不能代表完整字段；除非业务协议明确允许分段处理，否则应把整个输入视为失败。

这套处理方式的重点不是把错误字符串改得更长，而是让每一层各司其职：标准错误负责分类，原字符串扫描负责定位，日志策略负责保护数据。这样遇到配置或请求字段异常时，修复动作会更明确，也不会为了排障扩大敏感信息暴露面。