Java CharsetDecoder 怎么定位乱码：REPORT 模式、ByteBuffer 边界与解码结果

日志里出现“�”时，先别急着替换编码。Java 的 CharsetDecoder 如果保留默认替换策略，非法字节会悄悄变成替换字符；把错误策略改成 REPORT，再按 ByteBuffer 的边界处理输入，才能知道乱码究竟发生在哪一段。

定位乱码的关键是让解码器报告错误：用 onMalformedInput(CodingErrorAction.REPORT) 和 onUnmappableCharacter(CodingErrorAction.REPORT)，并在流式解码中区分输入未完整（underflow）与输出空间不足（overflow）。

乱码为什么先表现成一个替换字符

new String(bytes, charset) 追求的是尽量得到字符串，遇到不合法的字节序列时通常会采用替换策略。对于用户界面，这种“能显示”有时够用；对于导入、签名校验和日志取证，它反而把原始问题藏起来。

这次排查把链路收窄为四个节点：字节输入 进入解码器，REPORT 改变错误策略，非法序列转成 解码错误，只有完整成功时才到达 文本输出。

先用 REPORT 把非法字节暴露出来

下面的示例故意把 UTF-8 的三字节序列截断，观察解码器返回的结果。decode 适合一次性输入：它会从输入的当前位置读到 limit，并在成功时返回新的 CharBuffer。

import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;

public class DecodeCheck {
    public static void main(String[] args) throws CharacterCodingException {
        byte[] broken = {(byte) 0xE4, (byte) 0xB8};
        var decoder = StandardCharsets.UTF_8.newDecoder()
                .onMalformedInput(CodingErrorAction.REPORT)
                .onUnmappableCharacter(CodingErrorAction.REPORT);

        var text = decoder.decode(ByteBuffer.wrap(broken));
        System.out.println(text);
    }
}

运行时应在 decode 处得到字符编码异常，而不是拿到一个看似正常的字符串。若业务需要继续处理，可以捕获 CharacterCodingException，同时记录输入来源和字节范围；不要在 catch 中直接改用默认替换策略，否则排查链路又断了。

流式输入要分清 underflow 和 overflow

网络读取或分块文件读取时，一次拿到的字节可能只包含半个字符。此时解码器返回 UNDERFLOW 不代表数据正确，而是提示输入缓冲区暂时不完整；把剩余字节移到下一轮前，要保留它们。

另一种情况是输出 CharBuffer 太小，返回 OVERFLOW。这时应扩大或清空输出缓冲区，再继续调用，而不是重复喂同一段输入。下面这条链路对应的核对点是 ByteBuffer、decode、underflow 和 补齐输入。

三个现场检查点

检查字符集是否来自协议

不要根据乱码外观猜 GBK 或 UTF-8。优先查看 HTTP 的 Content-Type、文件格式约定或上游接口文档；如果没有可信声明，记录候选编码和原始字节，避免把一次猜测写成永久配置。

检查 ByteBuffer 的 position 和 limit

解码器只看 position 到 limit 的区间。复用缓冲区时，确认写入后调用了 flip()；追加残余字节时，确认旧数据没有被 clear() 提前丢掉。

检查异常发生前后的字节

异常信息本身不一定告诉你业务字段。可以在送入解码器前打印长度、偏移和受控的十六进制片段，严禁把整段可能含有隐私的原始内容写进普通日志。

一个可复用的判断顺序

先确认字符集来源，再用 REPORT 复现；一次性输入看异常位置，分块输入看 underflow/overflow；最后对比成功解码后的字符数、原始字节长度和业务字段边界。这样能把“页面有乱码”拆成可验证的输入、策略、缓冲区和输出四个环节。

常见问题

为什么没有异常却出现了 �？

通常是默认错误策略进行了替换。改用 REPORT 后，非法输入会显式失败，便于定位来源。

underflow 是解码失败吗？

不一定。流式输入中它往往表示当前缓冲区缺少完整字符，需要保留残余字节并等待下一块数据。

只设置 REPORT 够不够？

不够。还要检查 ByteBuffer 的 position、limit、flip 和残余字节处理，否则仍可能漏掉分块边界问题。

小结

CharsetDecoder 的价值不只是“把字节变成字符串”，还在于把错误策略、输入边界和结果状态交给程序检查。把默认替换改成 REPORT，再围绕 ByteBuffer 的消费范围做记录，乱码就能从视觉现象还原成一段具体的坏输入。