1. 问题现场一个看似简单的JSON解析报错今天在调试一个数据接口时遇到了一个典型的Hutool JSON解析报错cn.hutool.json.JSONException: Expected a ‘:‘ after a key at 5。这个错误信息非常直接Hutool的JSONUtil在解析一个字符串时在第5个字符的位置期待看到一个冒号:但实际上没有找到。对于任何处理过JSON数据的开发者来说这几乎立刻就能联想到——JSON格式不正确键值对之间缺少了分隔符冒号。但问题往往没那么简单。我遇到的原始字符串乍一看是标准的JSON格式{name:张三,age:25}。这格式完美无缺为什么还会报错这就是今天想和大家深入探讨的在看似正确的表象下隐藏着哪些常见的“坑”以及如何系统性地排查和解决这类问题。这不仅仅是解决一个报错更是理解字符串处理、编码和工具库行为的好机会。2. 核心原理Hutool JSONUtil 的解析机制与容错边界要解决问题首先要理解工具是如何工作的。Hutool的JSONUtil是对JSONObject和JSONArray的快捷封装其底层解析器在遇到一个待解析的字符串时会严格按照JSON标准RFC 8259进行词法分析和语法分析。2.1 解析器的“预期”行为当解析器读取到一个键Key之后它“预期”下一个非空白字符应该是一个冒号用以分隔键和值。报错信息中的at 5指的就是解析器指针在字符串中的位置从0开始计数。例如对于字符串{a解析器在读取完键a和闭合引号后指针位置可能就在第4或第5个字符取决于引号位置此时它急切地寻找那个冒号。这个机制本身是严谨的它保证了JSON数据的结构完整性。Hutool的解析器在这一点上并没有提供像某些库那样的“宽松模式”。因此任何导致键和冒号之间关系被破坏的因素都会触发这个异常。2.2 常见触发场景深度剖析根据经验Expected a ‘:‘ after a key错误很少是因为手写JSON时真的忘了加冒号。更多时候问题出在字符串的来源和预处理上。以下是几个高频场景字符串拼接或格式化引入的不可见字符这是最隐蔽的坑。比如通过字符串模板或多行字符串拼接JSON时可能在键的结尾和预期的冒号之间无意中插入了换行符\n、回车符\r甚至制表符\t。这些字符在编辑器和日志中可能不可见但解析器会忠实地将它们视为有效字符导致其找不到紧随其后的冒号。编码问题与“幽灵”字符当JSON字符串来自网络请求、文件读取或数据库时可能会携带BOM字节顺序标记或其他不可见的Unicode控制字符。例如一个UTF-8 with BOM的文件开头会有EF BB BF这三个字节。如果这个字符串被整体当作JSON解析开头的BOM就会被解析器视为键的一部分彻底打乱整个结构报错位置就会非常靠前比如at 1或at 3。转义字符处理不当如果键或值中包含需要转义的字符如引号、反斜杠\而转义操作不正确会导致解析器对字符串边界的判断失误。例如键是key\number如果反斜杠被错误处理解析器可能认为键在\处就结束了后面的内容就变成了无法识别的语法。字符串截取或切片错误有时我们可能对原始的JSON字符串进行了substring、split等操作如果索引计算错误拿到的可能是一个残缺的、不以{或[开头的字符串片段。解析器会尝试将其解析为一个JSON对象或数组但一开始的结构就是错的。实操心得遇到此类报错第一反应不应该是去检查JSON语法因为通常语法是IDE或在线工具验证过的而应该立刻怀疑“我拿到的字符串真的是我以为的那个字符串吗” 一个非常有效的调试方法是将报错的字符串变量输出到控制台或日志时在其前后加上明显的边界标记如System.out.println(--- jsonStr ---);这有助于发现首尾的空格或换行。3. 系统性诊断与排查实战当错误发生时我们需要一套可重复操作的诊断流程而不是盲目猜测。下面是我总结的排查步骤从最简单到最复杂。3.1 第一步可视化与基础检查首先将引发异常的字符串完整地打印出来。不要依赖IDE调试工具的简略显示。String suspiciousJson getJsonStringFromSomewhere(); // 你的数据来源 System.out.println(原始字符串:); System.out.println(suspiciousJson); System.out.println(字符串长度: suspiciousJson.length());接着遍历打印每个字符的ASCII码或Unicode码点这能暴露所有不可见字符。for (int i 0; i suspiciousJson.length(); i) { char c suspiciousJson.charAt(i); System.out.printf(位置 %d: 字符【%c】 - 十进制码点 %d%n, i, c, (int)c); }运行这段代码你会清晰地看到每个位置到底是什么。比如你可能会在位置4下标从0开始发现一个值为13的回车符\r而不是期待的58冒号:的ASCII码。这就是铁证。3.2 第二步使用更健壮的工具进行预处理在确认存在非法字符后我们需要清理它。Hutool本身提供了强大的字符串工具StrUtil。import cn.hutool.core.util.StrUtil; // 1. 去除首尾空白包括全角空格 String cleanedJson StrUtil.trim(suspiciousJson); // 2. 去除所有控制字符谨慎使用可能破坏JSON内的合法转义 // String cleanedJson StrUtil.cleanBlank(suspiciousJson); // 移除所有空白符 // 更推荐针对性移除BOM if (suspiciousJson.startsWith(\uFEFF)) { // UTF-8 BOM 的 Unicode 表示 cleanedJson suspiciousJson.substring(1); } // 3. 使用正则表达式移除键名周围可能存在的非法字符 // 此正则需谨慎编写仅作为示例移除键名引号之后、冒号之前的所有非冒号空白字符 // String cleanedJson suspiciousJson.replaceAll(\\\s*\\s*\:, \:);特别注意直接使用StrUtil.cleanBlank或过于激进的正则表达式可能会移除JSON字符串值内部必要的空格比如一个字符串值内部包含空格。因此最佳实践是精确打击根据第一步诊断出的问题字符位置和类型进行针对性清理。3.3 第三步验证与解析清理后再次尝试解析。为了更安全可以分两步走try { // 再次清理并验证 cleanedJson StrUtil.trim(cleanedJson); // 可选使用Hutool的JSONValidator进行快速格式验证非必须因为parseObj本身会验证 // boolean valid JSONValidator.of(cleanedJson).validate(); JSONObject jsonObj JSONUtil.parseObj(cleanedJson); System.out.println(解析成功: jsonObj); } catch (JSONException e) { System.err.println(清理后仍然解析失败: e.getMessage()); // 回到第一步对cleanedJson进行字符级诊断 }3.4 第四步追根溯源修复数据源如果上述步骤能解决问题那么恭喜你。但更重要的是我们要找到污染数据的源头防止问题复发。如果数据来自文件检查文件的编码格式。确保使用无BOM的UTF-8格式保存。在读取文件时明确指定编码String jsonStr FileUtil.readString(new File(data.json), CharsetUtil.CHARSET_UTF_8);如果数据来自HTTP请求检查响应头Content-Type是否包含charsetutf-8。使用Hutool的HttpUtil时它会自动处理编码但最好在获取响应后检查一下字符串内容。如果数据来自数据库检查字段的编码和存储过程。有时从数据库CLOB或TEXT字段中读取的数据可能包含额外的控制字符。如果数据来自字符串拼接避免使用进行复杂的多行JSON拼接。改用JSONObject或JSONUtil.createObj()来以编程方式构建JSON或者使用文本块Java 15并注意缩进。4. 进阶场景与特殊案例处理有些情况比较特殊需要更细致的处理。4.1 处理包含换行符的JSON值如果JSON字符串中某个值Value内部包含换行符这是完全合法的但需要正确转义。例如{message: Hello\nWorld}这个字符串在Java中定义时需要写成String json {\message\: \Hello\\nWorld\};或者使用文本块和转义String json {message: Hello\\nWorld} ;如果你接收到的字符串中值部分的换行符是未转义的字面换行符那么解析器在解析到值的时候就会报错可能是Unterminated string。这时你需要对输入字符串进行全局的转义处理但这非常复杂且容易出错。更好的办法是与数据提供方约定必须输出标准转义后的JSON。4.2 Hutool 5.7.x 与 5.8.x 的细微差异虽然核心解析逻辑稳定但不同小版本间对某些边界情况的处理可能有细微差别。例如对于尾随逗号如{a:1,}的容忍度或者对注释的支持JSON标准不支持注释但有些库的“宽松模式”支持。如果你在升级Hutool版本后突然出现大量此类解析错误可以查阅官方GitHub仓库的Release Notes和Issue列表看是否有相关解析器严格化的改动。一个建议在关键的数据解析路径上不要盲目升级工具库的次要版本尤其是涉及数据格式解析的库应先在小范围测试。如果使用Maven可以使用version[5.7.0,5.8.0)/version这样的版本范围限定避免自动升级到可能不兼容的版本。4.3 与其它常见JSON库的对比有时一段字符串用Hutool解析报错但用Jackson或Gson却能成功或报不同的错。这通常是因为其他库开启了“宽松模式”如JsonParser.Feature.ALLOW_UNQUOTED_FIELD_NAMES、JsonReadFeature.ALLOW_TRAILING_COMMAS等。这并不意味着Hutool有bug恰恰说明Hutool的默认行为更严格地遵循了JSON标准。严格的解析有助于提前发现数据格式问题对于确保系统间数据交换的可靠性是好事。如果你确实需要兼容一些“不标准”的JSON可以考虑先使用其他库的宽松模式解析再用Hutool处理。但更推荐的做法是统一数据规范在源头产出标准的JSON。5. 构建防御性代码与最佳实践为了避免在未来反复掉进同一个坑里我们需要在代码层面建立防御。5.1 封装安全的解析方法不要在所有地方直接调用JSONUtil.parseObj()。应该封装一个工具方法集中处理预处理和异常。import cn.hutool.core.exceptions.ExceptionUtil; import cn.hutool.core.util.StrUtil; import cn.hutool.json.JSONException; import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.extern.slf4j.Slf4j; Slf4j public class JsonSafeParser { /** * 安全地解析JSON字符串为JSONObject并记录诊断日志 * param jsonStr 原始JSON字符串 * param source 数据来源描述用于日志 * return 解析成功的JSONObject解析失败返回null */ public static JSONObject parseObjectSafely(String jsonStr, String source) { if (StrUtil.isBlank(jsonStr)) { log.warn([{}] 传入的JSON字符串为空或null, source); return null; } String processedStr jsonStr; // 1. 去除BOM if (processedStr.startsWith(\uFEFF)) { log.debug([{}] 检测到并移除UTF-8 BOM, source); processedStr processedStr.substring(1); } // 2. 去除首尾空白包括全角空格 processedStr StrUtil.trim(processedStr); // 3. 诊断性日志仅在调试级别开启 if (log.isDebugEnabled()) { log.debug([{}] 处理后字符串长度: {}, 前50字符: {}, source, processedStr.length(), StrUtil.subPre(processedStr, 50)); if (processedStr.length() jsonStr.length()) { log.debug([{}] 原始字符串长度: {}, 已执行清理, source, jsonStr.length()); } } try { JSONObject result JSONUtil.parseObj(processedStr); log.debug([{}] JSON解析成功, source); return result; } catch (JSONException e) { log.error([{}] JSON解析失败! 错误信息: {}, source, e.getMessage()); log.error([{}] 失败字符串(Hex): {}, source, StrUtil.hex(processedStr)); // 在错误级别下打印前几个字符的码点帮助定位问题 if (log.isErrorEnabled() processedStr.length() 0) { StringBuilder sb new StringBuilder(前10个字符码点: ); for (int i 0; i Math.min(10, processedStr.length()); i) { sb.append(String.format([%d:%d] , i, (int)processedStr.charAt(i))); } log.error([{}] {}, source, sb.toString()); } // 可以根据异常类型进行更精细的异常转换或重试逻辑 return null; } catch (Exception e) { // 捕获其他未知异常 log.error([{}] JSON解析发生未知异常: {}, source, ExceptionUtil.getMessage(e)); return null; } } }5.2 在数据流入点进行校验在系统边界处进行数据校验是最有效的。例如在Controller层接收HTTP请求体时除了用Valid做业务校验可以增加一个过滤器或拦截器对application/json类型的内容进行初步的格式健康检查例如检查首尾字符是否为{或[是否包含非法控制字符等。虽然无法完全替代解析但可以拦截明显畸形的问题数据避免其进入核心业务逻辑。5.3 编写单元测试覆盖边界情况为你的解析逻辑编写单元测试模拟各种脏数据情况。Test public void testParseJsonWithVariousInvalidInputs() { // 测试BOM assertNull(JsonSafeParser.parseObjectSafely(\uFEFF{\a\:1}, TestBOM)); // 测试首尾空格/换行 assertNotNull(JsonSafeParser.parseObjectSafely( \n {\a\:1} \r\n, TestWhitespace)); // 测试键后有多余字符模拟报错场景 JSONObject result JsonSafeParser.parseObjectSafely({\a\\r:1}, TestCRBeforeColon); assertNull(result); // 应解析失败返回null // 测试正确JSON assertNotNull(JsonSafeParser.parseObjectSafely({\a\:1}, TestCorrect)); }6. 从错误信息反推问题根源的通用思路Expected a ‘:‘ after a key at [position]这个错误模式可以推广到许多类似的解析错误中。其核心思路是解析器在某个特定位置position期待一个特定的语法元素但没有找到。Expected a ‘}‘ or ‘,‘ at [position]通常表示对象或数组结构未正确闭合或者元素之间缺少逗号分隔。Expected a ‘]‘ or ‘,‘ at [position]同上针对数组。Unterminated string at [position]字符串缺少闭合引号很可能是因为字符串内部有未转义的引号。Illegal unquoted character at [position]在需要引号的地方使用了未加引号的字符串或者值中包含了非法字符。当遇到这些错误时都可以采用类似的排查策略定位利用at [position]信息直接跳到字符串的指定位置。检查检查该位置前的字符是什么。解析器的“预期”是基于它已经解析完的内容做出的判断。例如Expected a ‘:‘ after a key at 5就去看位置4或5之前的字符是不是一个键的结束引号。诊断检查该位置上的字符是什么。是不是有不该出现的空格、换行符、特殊字符验证将问题位置前后一段字符串单独提取出来放在一个简单的验证环境如在线JSON校验器、或一个独立的测试程序中查看。通过这样系统化的拆解绝大多数JSON解析错误都能在几分钟内定位到根本原因。记住工具报错是结果而你的任务是找到导致这个结果的、隐藏在字符串字节里的那个“因”。这个过程也是提升你对数据格式、编码和程序行为理解的绝佳途径。