unmappablecharacterexception 在显式启用 report 策略时抛出，表明合法字节在目标字符集无映射；常见于 charsetdecoder/encoder 的 decode/encode 过程中，因源字符集有而目标字符集无对应字符（如 iso-8859-1 的 é 解码为 us-ascii）所致。
UnmappableCharacterException 是 Java 字符编码过程中一种明确的、可检查的异常，它不表示数据损坏或格式错误，而是指出：输入的字节序列本身合法有效，但在当前目标字符集里找不到对应的字符映射。比如用 UTF-8 解码一段原本是 GBK 编码的中文，某些 GBK 扩展区汉字在 UTF-8 中虽有定义，但若解码器配置为严格模式且未启用兼容策略，就可能触发该异常。
什么时候会抛出 UnmappableCharacterException
这个异常只在显式启用 REPORT 策略时才会抛出，常见于 CharsetDecoder 或 CharsetEncoder 的主动解码/编码流程中：
- 调用 CharsetDecoder.onUnmappableCharacter(CodingErrorAction.REPORT) 后执行 decode()
- 源字节属于某个字符集（如 ISO-8859-1），但目标字符集（如 US-ASCII）没有对应码位（例如带重音的 é 在 ASCII 中不存在）
- 读取遗留系统导出的文本文件，其编码声明与实际内容不符，而程序又拒绝自动猜测或替换
如何捕获并合理处理
它继承自 CharacterCodingException，属于 IOException 的子类，必须显式 try-catch。关键不是“吞掉异常”，而是根据业务决定映射失败后的语义：
- 记录原始字节位置和长度（通过 e.getInputLength() 获取出问题的字节数）
- 用替代字符（如 或 ?）继续解码：改用 onUnmappableCharacter(CodingErrorAction.REPLACE)
- 跳过不可映射段：onUnmappableCharacter(CodingErrorAction.IGNORE)
- 结合日志输出上下文，辅助排查文件来源或编码声明错误
和 MalformedInputException 的区别
两者常一起出现，但成因不同：
- MalformedInputException：输入字节本身违反编码规则（如 UTF-8 中出现非法的 0xC0 0x00 组合），属于“结构错误”
- UnmappableCharacterException：字节完全合规，只是目标字符集“不认识它”，属于“语义缺失”
- 一个文件可能同时触发两者——例如混合了 UTF-8 主体 + 几个 GBK 私有区字节
避免异常的最佳实践
与其依赖异常处理流程，不如前置控制编码行为：
- 优先使用 StandardCharsets.UTF_8 并确保 I/O 全链路统一（文件、数据库连接、HTTP header）
- 读取未知来源文本时，先用工具（如 juniversalchardet）探测编码，再创建对应 CharsetDecoder
- 对用户上传文件，在解析前校验 BOM 或首几百字节特征，拒绝明显不匹配的编码声明
- 对外提供 API 时，明确要求 Content-Type 指定 charset，不接受无声明的 text/plain
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
