Go base64.Encoding.AppendDecode 出错后如何识别已追加数据

处理不完整或被污染的 Base64 输入时，AppendDecode 的关键不是“有错误就没有结果”，而是同时看返回切片和 error：它会把成功解出的字节追加到 dst，遇到非法输入时仍可能返回部分追加数据与错误。默认业务策略应是错误时丢弃本次追加区间；只有明确支持部分恢复时，才单独记录这段数据。

官方地址：https://pkg.go.dev/encoding/base64#Encoding.AppendDecode

先确定返回值：切片和 error 必须一起解释

官方文档对 AppendDecode 的语义很具体：返回值是扩展后的目标缓冲区；输入格式错误时，返回已经部分解码的数据和错误。它和只返回一个布尔值的校验函数不是一回事，也不能只用 len(out) 判断成功。

下面的最小函数把结果拆成“完整成功”和“失败”两条业务路径。示例中的非法字符只是为了说明错误处理，不代表任何真实运行输出。

package main

import (
    "encoding/base64"
    "fmt"
)

func decodeOnce(src string) ([]byte, error) {
    // 预留容量，避免把目标切片的已有前缀误当成解码结果。
    dst := make([]byte, 0, base64.StdEncoding.DecodedLen(len(src)))
    out, err := base64.StdEncoding.AppendDecode(dst, []byte(src))
    if err != nil {
        // 发生错误时，调用方不要继续消费 out 中的部分结果。
        return nil, fmt.Errorf("base64 输入无效: %w", err)
    }
    // 只有 err 为 nil 时，才把完整的 out 交给后续业务。
    return out, nil
}

这里使用 AppendDecode 而不是把结果直接写入一个固定数组，是为了突出它的追加语义。容量只是性能上的预留，不改变错误规则；如果输入来自网络或文件，外层仍应先限制原始文本大小。

把 dst 前缀与本次追加区间分开

当 dst 已经有业务数据时，返回切片的前半段属于调用前的前缀，后半段才是本次解码尝试追加的范围。这个边界决定了日志、回滚和部分恢复是否会误伤旧数据。

package main

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

func inspectAppend(src string) {
    // prefix 代表调用前已有的数据，不能在失败回滚时被截掉。
    prefix := []byte("header:")
    before := len(prefix)
    out, err := base64.StdEncoding.AppendDecode(prefix, []byte(src))

    // 追加区间从调用前长度开始，前缀始终保留。
    appended := out[before:]
    var corrupt base64.CorruptInputError
    if errors.As(err, &corrupt) {
        // CorruptInputError 的数值表示输入中的错误偏移。
        fmt.Printf("追加字节=%d，错误偏移=%d\n", len(appended), int64(corrupt))
        return
    }
    if err != nil {
        // 其他错误也不能被当成成功结果继续向下传递。
        fmt.Println("解码失败")
        return
    }
    // 无错误时，out 才是包含前缀和完整追加区间的结果。
    fmt.Printf("完整结果=%q\n", out)
}

这段示例只展示切片边界和错误分类，不应把打印内容当成实测证据。生产代码通常不打印输入；如果需要审计，只记录输入长度、错误类别和请求标识。还要注意：如果错误发生在第一个量化块之前，追加区间可能为空；“返回了切片”不等于“返回了可用业务数据”。

用 CorruptInputError 把错误变成诊断线索

AppendDecode 的格式错误可以通过 errors.As 识别为 base64.CorruptInputError。它携带的是输入字节偏移，适合定位是哪一段传输文本出现非法字符，但这个偏移不是 UTF-8 字符下标，也不是解码后字节下标。

因此，日志可以记录“输入偏移 12 的格式错误”，但不要把整个令牌写进日志，更不要把部分输出当成已认证的内容。若输入还包含 CR/LF，标准解码器会按文档忽略它们；空格、制表符和其他字符仍需要按协议单独决定是否允许。

func classifyBase64Error(err error) string {
    // 先区分具体的格式错误，便于统计错误位置而不暴露原文。
    var corrupt base64.CorruptInputError
    if errors.As(err, &corrupt) {
        return fmt.Sprintf("格式错误，输入偏移=%d", int64(corrupt))
    }
    if err == nil {
        // nil 表示本次追加结果通过了解码器的格式检查。
        return "成功"
    }
    // 保留未知错误的类别，不把原始输入拼进日志。
    return "其他解码错误"
}

失败时丢弃部分结果，还是允许恢复

大多数配置、令牌和消息字段都应该选择“失败即丢弃”。因为部分 Base64 字节可能只是完整量化块的前半段，把它们交给 JSON、压缩包或签名校验器，往往会把格式错误推迟到更远的层，反而难以定位。

如果业务确实允许从损坏输入中抢救前缀，至少要同时保存三项信息：调用前的 len(dst)、本次追加的范围、CorruptInputError 的输入偏移。恢复结果必须进入隔离状态，经过完整性检查后才能合并，不能因为返回切片非空就自动提交。

特别是签名或身份令牌场景，先规范化、再校验签名的顺序可能改变被签名的字节。Base64 解码成功只说明表示层可读，不代表来源可信、内容完整或权限有效。

增量输入不要随意逐片 AppendDecode

Base64 以 4 个输入字符组成一个编码块。若把网络流任意切成两段，第一段末尾可能只有半个块；直接对每一段分别调用 AppendDecode，第二段不会自动继承第一段的残留状态，结果就可能出现误报或丢失。

需要持续从 io.Reader 读取时，应优先考虑 base64.NewDecoder，让解码器保留跨读取边界的状态。如果业务已经把输入切成完整的 4 字符块，才可以按明确协议使用 AppendDecode；每次仍要检查返回的错误。

func appendCompleteChunk(dst []byte, chunk []byte) ([]byte, error) {
    // 调用方的协议保证 chunk 是完整的 Base64 块或最后一块。
    out, err := base64.StdEncoding.AppendDecode(dst, chunk)
    if err != nil {
        // 失败时返回原 dst，避免把部分追加数据泄漏给上层。
        return dst, fmt.Errorf("分片解码失败: %w", err)
    }
    // 只有成功分片才能替换累积缓冲区。
    return out, nil
}

接入前的四个判断

• 是否同时检查了返回切片和 error，而不是只判断长度？
• 是否保存了调用前长度，能区分 dst 前缀和本次追加区间？
• 错误时是否默认丢弃部分结果，并避免把原始输入写进日志？
• 输入是否可能跨任意读取边界？如果会，是否改用 NewDecoder 或建立完整块协议？

记住一句话：AppendDecode 的返回切片回答“目前追加了什么”，error 回答“这次输入是否完整有效”。两者必须作为一个结果处理。

常见问题

输入非法时，返回切片能不能继续使用？默认不能。它可能只包含部分量化块，除非业务专门设计了隔离的部分恢复协议。

如何知道错误发生在哪个字符？用 errors.As 取出 CorruptInputError，把它当作输入字节偏移；不要把它当作 Unicode 字符位置。

为什么不把每个网络分片都直接 AppendDecode？任意分片可能切断 4 字符编码块，AppendDecode 本身不替调用方跨调用保存残块状态；流式读取应考虑 NewDecoder。

CR/LF 需要先手工删除吗？标准 Base64 解码器会忽略 CR/LF。是否允许其他空白字符，则应由接口协议明确规定，不能用“全量清洗”掩盖输入错误。