Go encoding/hex 怎么把二进制 ID 稳定转换成小写文本

如果 ID 原本是 []byte，不要直接把它转换成 string 当作可读文本：那只是按原始字节解释字符串，可能包含不可见字符，也不适合放进日志、URL 或文本字段。更稳妥的做法是用 encoding/hex 编码成小写十六进制字符串，需要恢复时再解码。

最小写法是 hex.EncodeToString(id) 和 hex.DecodeString(text)。前者输出只含 0-9a-f 的小写文本，后者会检查输入是否为偶数长度且全部是十六进制字符；解码失败时必须检查 error，不能只看返回的字节切片。

一、先固定二进制 ID 与文本的编码契约

一个二进制 ID 的编码契约最好在接口或数据模型旁边说清楚：文本统一使用小写十六进制，不插入连字符或空格，且必须能够无损恢复原始字节。这样同一个 ID 不会因为大小写、展示格式或隐式字符集转换出现多种表示。

十六进制的长度关系很简单：源数据有 n 个字节，文本就有 2*n 个字符；反向解码则是文本长度除以 2。这个关系很适合放在入参校验和数据库字段长度设计里。

二、用 EncodeToString 生成稳定的小写文本

普通业务直接使用 EncodeToString 就够了。它接收源字节并返回新的字符串，标准库内部使用小写字符表，因此不需要再调用 strings.ToLower。

package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	// 这里的字节可以来自数据库、随机源或上游协议。
	id := []byte{0x01, 0xaf, 0x00, 0x7e}
	text := hex.EncodeToString(id)

	// text 为 01af007e，长度是原始 ID 的两倍。
	fmt.Println(text)
}

不要写成 string(id)，那是在保留原始字节，不是在进行可读编码。也不要为了“统一格式”手工拼接每个字节；手工实现容易漏掉前导零，例如 0x01 必须编码成 01，不能变成单字符 1。

三、用 DecodeString 恢复字节并把错误当成无效 ID

从路径参数、JSON 字段或配置文件读到文本后，使用 DecodeString 解码。它要求输入长度为偶数，并且每个字符都在 0-9、a-f 或对应的大写范围内。错误时不要继续使用结果；标准库可能已经返回部分解码内容，但那不是完整 ID。

package main

import (
	"encoding/hex"
	"fmt"
)

func parseID(text string) ([]byte, error) {
	// 先让标准库检查奇数长度和非法十六进制字符。
	id, err := hex.DecodeString(text)
	if err != nil {
		return nil, fmt.Errorf("无效的十六进制 ID: %w", err)
	}
	// 固定 4 字节 ID 时，再检查业务长度，避免短 ID 混入后续查询。
	if len(id) != 4 {
		return nil, fmt.Errorf("ID 长度为 %d 字节，期望 4 字节", len(id))
	}
	return id, nil
}

接口层通常还应检查业务长度。DecodeString("abc") 会因奇数长度失败，DecodeString("01xz") 会因非法字符失败；这两种情况都属于输入不合法，而不是需要“修正大小写”或自动补零。

四、普通字符串 API 与预分配写法怎么选

EncodeToString 和 DecodeString 适合接口参数、配置和单个 ID。需要控制缓冲区时，可以使用 EncodedLen、DecodedLen 配合 Encode、Decode：

// 预先计算目标长度，适合批量转换时复用明确的缓冲区。
dst := make([]byte, hex.EncodedLen(len(src)))
written := hex.Encode(dst, src)
encoded := string(dst[:written])

// 解码前必须确认文本长度为偶数，并为完整结果准备空间。
decoded := make([]byte, hex.DecodedLen(len(encoded)))
n, err := hex.Decode(decoded, []byte(encoded))
if err != nil {
	// 错误时不要使用 decoded[:n] 作为最终 ID。
	return err
}
_ = decoded[:n]

这组 API 不会改变编码规则，只是让目标内存更明确。多数业务代码优先保持 EncodeToString 的可读性；只有批量处理、内存分配已经成为可测量问题时，才值得围绕缓冲区复用做优化。

相关问题

十六进制字符串必须全部小写吗？

协议允许时建议统一小写，因为它能让同一个 ID 只有一种文本表示。DecodeString 仍能识别大写十六进制字符，但输出端最好固定使用 EncodeToString 的小写结果。

为什么不能对奇数长度的文本自动补 0？

补在左侧还是右侧会改变原始字节边界，标准库因此直接把奇数长度视为错误。只有当业务协议明确规定补齐方向时，才应在边界层单独实现并记录该规则。

解码出错时返回的部分字节能使用吗？

不能把它当作完整 ID 使用。它只表示错误发生前已经转换的前缀；调用方应返回错误或拒绝请求，再由上游修复输入。