Go hex 解码奇数长度字符串为什么失败

我在处理一段外部传来的十六进制字符串时，最容易误判的不是字符大小写，而是“看起来像十六进制”却少了半个字节。Go 的 encoding/hex 并不会替你猜最后一个字符应该补什么：DecodeString 要求输入长度为偶数，每两个十六进制字符表示一个字节，奇数长度会返回 hex.ErrLength。

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

如果输入是奇数长度，先回到协议确认这个半字节是否有明确含义；没有约定时应直接拒绝，不要为了让解码通过而盲目补零。

这篇只讨论 DecodeString 的长度边界，不延伸到 Base64、字符集转换或自定义十六进制字母表。我的排查顺序是：确认两个字符一字节，再区分长度错误和非法字符，最后决定补齐还是拒绝。

先确认奇数长度为什么无法组成完整字节

十六进制的每一位只有 4 个二进制位，一个 Go byte 需要两位十六进制字符才能凑满 8 个二进制位。例如 48 是一个完整字节，6C 又是一个完整字节；但 486 只能拆成 48 和孤立的 6。最后这个字符究竟应该放在高四位还是低四位，单靠解码函数无法推断。

因此，输入长度检查应使用字节长度：

package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	input := "486"
	if len(input)%2 != 0 {
		// 先拦截无法组成完整字节的输入，保留原始边界。
		fmt.Println("hex 字符串长度必须为偶数")
		return
	}

	decoded, err := hex.DecodeString(input)
	if err != nil {
		// 解码失败时保留标准库错误，交给上层决定如何返回。
		fmt.Println("解码失败:", err)
		return
	}
	fmt.Printf("解码结果: %x\\n", decoded)
}

这里的提前判断不是替代错误处理，而是把“长度不完整”转成更靠近输入入口的业务提示。即使删除判断，也仍然必须检查 DecodeString 返回的错误。

用 DecodeString 区分长度错误和字符错误

我后来把这类问题拆成两条线，排查速度快了很多。奇数长度对应 hex.ErrLength；长度正确但出现 G、空格或其他非十六进制字符时，则是 hex.InvalidByteError。前者是配对边界问题，后者是字符内容问题，修复动作不能混为一谈。

package main

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

func explain(input string) {
	decoded, err := hex.DecodeString(input)
	if err != nil {
		// 先判断长度边界，再把其他错误保留为字符内容问题。
		if errors.Is(err, hex.ErrLength) {
			fmt.Printf("%q：长度为奇数，无法按字节解码\\n", input)
			return
		}
		var invalid hex.InvalidByteError
		if errors.As(err, &invalid) {
			fmt.Printf("%q：包含非法十六进制字符 0x%02x\\n", input, byte(invalid))
			return
		}
		fmt.Println("其他解码错误:", err)
		return
	}
	fmt.Printf("%q -> %x\\n", input, decoded)
}

func main() {
	explain("486")
	explain("48G0")
}

判断顺序的价值在于：日志可以明确告诉调用方“数据短了”还是“字符不合法”，而不是统一返回一个难以追踪的解码失败。对于外部请求，还应避免把未经处理的原始敏感数据完整写入日志。

按协议决定补齐还是拒绝半字节

能不能补零，不是 encoding/hex 的技术问题，而是数据协议问题。我通常按下面三种情况取舍：

• 协议明确左侧补零：例如上游把每个半字节当作独立数值，且文档明确规定 F 等价于 0F，才在解码前补齐。
• 协议要求完整字节：文件摘要、密钥材料、二进制标识等场景无法猜测缺失半字节，应直接返回输入错误。
• 输入来自展示层：先确认是否混入空格、换行或分隔符；清洗格式符号也必须有协议依据，不能把真实数据错误吞掉。

func decodeNibbleText(input string) ([]byte, error) {
	if len(input)%2 != 0 {
		// 只有协议明确“左侧补零”时才做这个转换。
		input = "0" + input
	}
	decoded, err := hex.DecodeString(input)
	if err != nil {
		// 补齐后仍要检查字符是否合法，不能把两类错误合并。
		return nil, fmt.Errorf("解码十六进制输入: %w", err)
	}
	return decoded, nil
}

如果协议没有写清楚补齐方向，我更建议在入口返回错误并推动上游补全约定。静默补齐会让同一个字符串在不同系统中得到不同字节，后续排查比一次失败更难。

把排查流程收进入口校验和速查表

落到接口或文件导入时，可以把流程固定成四步：先保留原始输入，再检查长度是否为偶数；长度正确后交给 DecodeString；根据 ErrLength 或 InvalidByteError 选择返回提示；最后只在协议明确时做清洗或补齐。这样既不会把半字节当成完整字节，也不会把非法字符伪装成长度问题。

我觉得最值得记住的一点是：奇数长度不是“hex 包太严格”，而是输入缺少一个四位半字节的协议事实。先把这个事实说清楚，再选择补零或拒绝，代码才会稳定。

相关问题

hex.DecodeString 能不能自动把奇数长度前面补 0？

不能。标准库按完整字节解码并返回 hex.ErrLength；是否补零应由业务协议决定。

奇数长度和非法字符可以用同一个错误提示吗？

不建议。两者的修复方向不同，至少应在日志或接口错误中区分长度边界与字符内容。