Go x/text/encoding/korean 分块解码为什么不能丢掉未消费字节

我在接入旧韩文档案时遇到过一个很隐蔽的问题：同一份 EUC-KR 数据，整块读取时正常，改成网络分块后偶尔少一个字或出现替换字符。最后发现，问题不在 korean.EUCKR 的映射，而在分块调用 Transform 时把尚未消费的源字节直接丢了。

官方地址：https://pkg.go.dev/golang.org/x/text/encoding/korean

分块解码要把 nDst 产生的输出先写入结果，再保留 src[nSrc:]。当 atEOF=false 且返回 transform.ErrShortSrc 时，它通常表示当前块不完整，应等待下一块，而不是把尾部当成无效数据丢弃。

EUC-KR 解码器真正负责什么

golang.org/x/text/encoding/korean 暴露的 EUCKR 是 EUC-KR 编码，也被文档标为 Code Page 949。调用 korean.EUCKR.NewDecoder() 后得到的解码器会把输入字节转换成 UTF-8，并实现 transform.Transformer 接口。

这个接口不是“传入一块字节，返回一块完整字符串”的简单函数。它同时返回写入目标的字节数 nDst、已经从源切片消费的字节数 nSrc 和错误。生产代码必须先处理已经生成的输出，再依据 nSrc 决定下一次要继续提供哪些输入。

为什么 nSrc 不能被忽略

一个 EUC-KR 字符可能跨越两个读取块的边界。假设当前块最后只剩下一个前导字节，解码器无法在没有后续字节的情况下完成字符。此时 Transform 可能只消费前面的完整内容，令 nSrc ，并返回 transform.ErrShortSrc。

最危险的写法是只处理 dst[:nDst]，然后无条件把整个 src 标记为已处理。这样一来，src[nSrc:] 中的半个字符不会再出现在下一次调用里；后续块即使包含正确的后半字节，也无法恢复原来的字符。

// Transform 的返回值分别表示输出字节数、已消费源字节数和错误。
nDst, nSrc, err := decoder.Transform(dst, src, false)
// 先保存 dst[:nDst]，因为这部分输出已经可以交给上层。
output = append(output, dst[:nDst]...)
// 只有 nSrc 之后的尾部还没有被转换，不能直接丢弃。
pending = append(pending[:0], src[nSrc:]...)
if err != nil && !errors.Is(err, transform.ErrShortSrc) {
	// 非短源错误才按当前业务策略中止或记录。
	return err
}

分块读取要怎样保存 carry

我更倾向于把“未消费字节”单独叫作 carry，这样代码审查时不容易把它误当成已经处理过的输入。每次收到新块，先把 carry 与新数据拼成当前输入；调用转换器后，只把 nSrc 之后的尾部复制回 carry。

package main

import (
	"errors"
	"fmt"

	"golang.org/x/text/encoding/korean"
	"golang.org/x/text/transform"
)

// decodeChunk 处理一个输入块，并返回 UTF-8 输出与尚未消费的尾部。
func decodeChunk(dec transform.Transformer, carry, chunk []byte, atEOF bool) ([]byte, []byte, error) {
	src := make([]byte, 0, len(carry)+len(chunk))
	src = append(src, carry...)
	src = append(src, chunk...)
	dst := make([]byte, len(src)*3+8)

	// dst 只承接当前调用产生的 UTF-8 字节，容量按输入字节数留出余量。
	nDst, nSrc, err := dec.Transform(dst, src, atEOF)
	result := append([]byte(nil), dst[:nDst]...)
	// nSrc 之后的源字节可能只是一个尚未完成的 EUC-KR 字符。
	left := append([]byte(nil), src[nSrc:]...)
	if err != nil && !errors.Is(err, transform.ErrShortSrc) {
		return result, left, err
	}
	return result, left, nil
}

func main() {
	decoder := korean.EUCKR.NewDecoder()
	// 真实程序会从文件或网络获得两个相邻块；这里不展示具体字节内容。
	first, carry, err := decodeChunk(decoder, nil, firstChunk(), false)
	if err != nil {
		panic(err)
	}
	second, carry, err := decodeChunk(decoder, carry, secondChunk(), true)
	if err != nil {
		panic(err)
	}
	if len(carry) != 0 {
		panic("输入在 EOF 处仍有未完成字节")
	}
	fmt.Print(string(append(first, second...)))
}

// 示例占位函数代表上层读取器提供的相邻数据块。
func firstChunk() []byte  { return nil }
func secondChunk() []byte { return nil }

这个示例里，atEOF=false 的调用允许尾部等待更多输入；最后一次调用才传入 true。如果真正到达 EOF 时 carry 仍非空，说明输入在字符中间结束，应按业务要求报错、记录损坏数据或采用明确的替换策略，不能静默吞掉。

什么时候直接使用 Decoder.Reader

如果输入本来就是连续的 io.Reader，通常不需要自己维护 nSrc。官方提供的 Decoder.Reader 会把解码器包在读取器外面，适合文件、HTTP 响应体或管道这类顺序流。

// Reader 封装负责跨 Read 调用保留转换状态，调用方只读取 UTF-8 结果。
decoded := korean.EUCKR.NewDecoder().Reader(srcReader)
if _, err := io.Copy(dstWriter, decoded); err != nil {
	// 上层仍需处理底层读取错误和转换错误。
	return err
}

手动调用 Transform 只在上层协议已经把数据拆成消息、需要自定义缓冲、或要把转换错误和消息边界绑定时更合适。不要因为“每块都调用一次”就把 Decoder 重新创建；转换器的状态和未完成字符都应在同一条连续流中保留。

排查丢字的四个检查点

1. 确认调用的是 NewDecoder，不是把 EUC-KR 原始字节直接转换成字符串。
2. 记录每次 Transform 的 nDst、nSrc 和 err，重点看 nSrc 的调用。
3. 检查是否把 src[nSrc:] 拼回下一块，以及拼接时是否发生了意外覆盖。
4. 确认最后一次调用才传 atEOF=true，并对 EOF 时的非空 carry 做显式处理。

结论：把 nSrc 当成输入所有权边界

这次问题给我的经验是，分块解码最重要的不是把目标缓冲区开得多大，而是尊重转换器返回的消费边界。nDst 之前是已经产生的 UTF-8，nSrc 之后是调用方仍然拥有的输入；ErrShortSrc 只是告诉你当前块还不够完整。连续流优先选 Decoder.Reader，只有确实需要自定义分块协议时，才手动维护 carry。

参考资料：https://pkg.go.dev/golang.org/x/text/encoding/korean、https://pkg.go.dev/golang.org/x/text/encoding、https://pkg.go.dev/golang.org/x/text/transform

相关问题

ErrShortSrc 是不是代表 EUC-KR 数据损坏？

不一定。只要 atEOF=false，它可能只是当前分块在多字节字符中间结束。真正 EOF 时仍有未消费字节，才需要按不完整输入处理。

可以把每个块都交给新的 Decoder 吗？

不建议。这样会丢失跨块的转换状态，边界字符和错误判断都可能失真。连续输入应复用同一个 Decoder。

为什么不直接把源字节全部 append 到结果？

源字节是 EUC-KR 编码，结果应是 UTF-8。直接拼接只是在保存原始数据，并没有完成字符集转换。