Go encoding/hex编码二进制标识并保持日志可读的实践

Go 服务把请求 ID、摘要片段或协议字段写进日志时，直接输出 []byte 往往会混入不可见字符，复制和检索都不稳定。更合适的做法是用 encoding/hex 把每个字节编码成两个十六进制字符：日志保持可读，长度可以预估，必要时还能无损解码回原始字节。

先把二进制标识转换成固定可读字符串

hex.EncodeToString 适合把一段字节变成日志字段、追踪键或排障时可复制的值。它不改变字节内容，也不隐藏内容，只是用字符集 0-9a-f 表示每个半字节。因此输入长度为 n 时，输出长度就是 2n；空输入得到空字符串。

package main

import (
    "encoding/hex"
    "log"
)

func loggableID(raw []byte) string {
    // hex 是可逆编码，不是加密；日志权限仍需由日志系统控制。
    return hex.EncodeToString(raw)
}

func main() {
    requestID := []byte{0x01, 0xaf, 0x20, 0xff}
    // 只记录可复制的十六进制字段，避免直接打印原始字节。
    log.Printf("request_id=%s", loggableID(requestID))
}

示例中的结果是 01af20ff。同一组字节始终得到同一串文本，适合在日志平台按完整字段搜索。若原始值本身属于密钥、令牌或个人数据，编码后仍然是敏感数据，不能因为“看起来可读”就放宽访问控制。

按分配敏感度选择字符串或预分配缓冲区

在普通业务日志中，EncodeToString 的表达最直接。若编码出现在循环、批处理或高频追踪路径，可以显式预留目标空间：hex.EncodedLen(len(src)) 返回所需字符数，hex.Encode 再把编码写入这个缓冲区。这样做的重点不是“把每段代码都优化”，而是让缓冲区尺寸与编码规则对应，避免切片过短。

func formatTraceID(raw []byte) string {
    // 一个字节对应两个十六进制字符，先按精确长度分配目标切片。
    dst := make([]byte, hex.EncodedLen(len(raw)))
    n := hex.Encode(dst, raw)
    // n 是实际写入长度；只把已写区域转换成字符串。
    return string(dst[:n])
}

func appendTraceField(dst []byte, raw []byte) []byte {
    // 复用调用方容量，适合把多个字段拼成一条日志行。
    dst = append(dst, "trace_id="...)
    return hex.AppendEncode(dst, raw)
}

两种写法的选择可以按下面的边界判断：

解码时先处理奇数长度和非法字符

日志回放、接口参数还原或测试夹具需要把十六进制文本恢复成字节时，使用 hex.DecodeString。输入必须只含十六进制字符，并且长度为偶数。奇数长度会触发 hex.ErrLength；字符不合法时会返回错误，函数也可能已经得到部分字节。业务代码应在 err == nil 前拒绝这份结果。

func parseTraceID(s string) ([]byte, error) {
    // 奇数个字符无法组成完整字节，先给出明确错误。
    if len(s)%2 != 0 {
        return nil, hex.ErrLength
    }
    raw, err := hex.DecodeString(s)
    if err != nil {
        // 丢弃可能返回的半截字节，避免把不完整标识交给下游。
        return nil, fmt.Errorf("invalid trace id: %w", err)
    }
    return raw, nil
}

如果需要把错误类型分开统计，可以对包装后的错误使用 errors.Is 检查 hex.ErrLength，或用 errors.As 识别 hex.InvalidByteError。错误日志记录输入长度、字段名和错误类型即可，通常不必把整段可能敏感的原文再打印一次。

把日志字段、长度边界和检查清单固定下来

落地时建议把字段名、大小写和解码策略写成约定：例如统一使用小写 request_id，不要让同一字段一会儿是原始字节、一会儿是大写十六进制。提交前至少检查四项：空输入是否有明确含义；长输入是否会放大日志体积；解码失败是否拒绝半截数据；编码值是否仍受原有脱敏、权限和保留策略约束。

最后记住，hex 解决的是表示和传输可读性，不解决碰撞、保密或身份认证。需要摘要时选择哈希，需要保密时使用加密，需要防篡改时增加认证机制；不要把“日志里没有乱码”误认为“日志里没有敏感信息”。

相关问题

hex 编码后为什么长度会变成两倍？

一个字节包含两个十六进制半字节，每个半字节用一个字符表示，所以 n 个输入字节需要 2n 个输出字符。

能不能用 hex 代替加密？

不能。hex 可直接反向解码，只提供表示方式，不提供保密性、完整性或身份认证。

DecodeString 返回错误时能继续使用返回字节吗？

不建议。错误输入可能只解出了前半段，调用方应丢弃返回字节并根据错误类型记录或拒绝请求。