Java CharsetDecoder 怎样处理不完整多字节输入

在流式 UTF-8 输入里，一个汉字可能被拆到两个 ByteBuffer 中。此时 CharsetDecoder.decode(in, out, false) 返回 UNDERFLOW 并不表示数据损坏，而是说明当前输入块还不够，剩余字节必须保留下来，等下一块到达后继续解码。真正结束时才把最后一次 decode 的 endOfInput 设为 true，随后调用 flush 完成收尾。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/charset/CharsetDecoder.html

先区分 UNDERFLOW、OVERFLOW 和错误

CharsetDecoder 把输入字节转换为字符，并通过 CoderResult 告诉调用方为什么暂时停下。UNDERFLOW 可能意味着输入已经读完，也可能意味着解码器需要更多字节；OVERFLOW 表示输出 CharBuffer 空间不足；malformed input 和 unmappable character 才是需要按错误策略处理的数据问题。

分块解码时最容易犯的错，是把每个块单独交给便捷方法 decode(ByteBuffer)。这个方法会自己完成一次完整的 reset、decode 和 flush，不适合跨块保存解码状态。跨块场景应使用三参数 decode，并自行维护输入和输出缓冲区。

用 compact 保留半个字符

下面用 UTF-8 的“中”作为示意：它的三个字节被拆成第一块的两个字节和第二块的一个字节。第一次解码结束时，输入缓冲区里没有完成的字节仍然属于当前解码状态；调用 compact() 会把这些剩余字节移到缓冲区开头，下一次 put 才能把新数据接在后面。

import java.nio.ByteBuffer;
import java.nio.CharBuffer;
import java.nio.charset.CoderResult;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;

public class StreamingDecode {
    public static void main(String[] args) throws Exception {
        var decoder = StandardCharsets.UTF_8.newDecoder()
                // 流式输入遇到非法字节时报告，避免静默替换掩盖数据问题。
                .onMalformedInput(CodingErrorAction.REPORT)
                .onUnmappableCharacter(CodingErrorAction.REPORT);
        var input = ByteBuffer.allocate(8);
        var output = CharBuffer.allocate(32);

        byte[][] chunks = {
                {0x41, (byte) 0xE4, (byte) 0xB8}, // A 加上“中”的前两个字节
                {(byte) 0xAD, 0x42}                // 补齐“中”，再接 B
        };

        for (int i = 0; i 

这里的关键不是把字节数组写成固定两块，而是保留“未消费输入”。第一次 decode 以 false 结束后，如果返回 UNDERFLOW，input.compact() 会把尚未组成完整字符的前缀留下；第二块写入后，解码器才能看到完整的 UTF-8 序列。

最后一次 decode 必须传 true

endOfInput 表示调用方是否还能提供更多输入。只要后面还有数据，就传 false；确认输入流结束后，最后一次调用必须传 true。如果此时仍有半个 UTF-8 字符，解码器才会把它按 malformed input 处理，而不是继续等待一个永远不会到来的字节。

状态顺序也不能跳过：一次解码操作通常是先 reset()，再多次 decode(false)，然后一次 decode(true)，最后 flush()。尚未结束时直接调用 flush，或者在没有完成最终 decode 的情况下重复进入下一阶段，都会触发 IllegalStateException。

按返回结果定位故障

生产代码还要注意输出缓冲区的生命周期：OVERFLOW 不代表输入失败，输入位置应保持在未完成的位置，排空输出后继续调用。若只是一次性完整字节数组，才适合使用便捷的 decode(ByteBuffer)。

速查结论

分块输入遇到半个多字节字符时，先把 UNDERFLOW 当作“需要更多输入”，用 compact() 保留剩余字节；结束时用 decode(true) 明确封口，再调用 flush()。只有这样，输入不足、输出不足和数据损坏才会被分开处理。

相关问题

UNDERFLOW 一定表示 UTF-8 字节不完整吗？

不一定。它也可能只是当前输入块已经读完；调用方要结合是否还有下一块和输入缓冲区的 remaining 判断。

为什么不能每块都调用 decode(ByteBuffer)？

便捷方法会把每次调用视为独立解码操作，并自行 reset 与 flush；跨块输入需要保留 decoder 和剩余字节，所以应使用三参数 decode。