1. 问题现场一个看似简单的JSON解析为何突然“罢工”今天在调试一个老项目时遇到了一个让我卡了半个小时的“小”问题。场景很常见从外部接口拿到一个JSON字符串用Hutool的JSONUtil去解析准备提取里面的数据。代码就一行简单得不能再简单String jsonStr {\name\:\张三\, \age\:30}; JSONObject jsonObject JSONUtil.parseObj(jsonStr);按理说这应该稳稳地输出一个JSONObject。但实际运行后控制台却无情地抛出了一个cn.hutool.json.JSONExceptioncn.hutool.json.JSONException: Expected a ‘:‘ after a key at 5“在位置5期望一个冒号”我盯着字符串{name:张三, age:30}数了又数从0开始索引位置5的字符明明是第二个双引号这语法看起来完全正确啊。相信很多用过Hutool的朋友都遇到过类似的报错错误信息指向一个看似没有问题的位置让人一头雾水。这不仅仅是Hutool的问题而是处理JSON这种结构化数据时一个非常典型且容易踩坑的场景——字符串中不可见的“幽灵字符”。这个问题背后牵扯到字符编码、数据来源、字符串处理习惯等一系列细节。接下来我就把这次排查的完整链路、根因分析以及一劳永逸的解决方案毫无保留地分享给你。2. 错误信息深度拆解Expected a ‘:‘ after a key at 5到底在说什么首先我们得真正理解Hutool抛出的这个异常信息。JSONException: Expected a ‘:‘ after a key at 5这句话是Hutool内置的JSON解析器在词法分析Lexical Analysis阶段抛出的。2.1 JSON解析器的“阅读”过程你可以把JSON解析器想象成一个严格的语法检查员它按照标准JSON规范RFC 8259逐字符扫描你提供的字符串。它的工作流程大致是这样的期待一个对象开始遇到{进入解析对象状态。期待一个键Key键必须是双引号包裹的字符串。解析器会寻找下一个然后读取直到遇到配对的中间的内容就是键名。期待一个冒号读取完键名和后面的后解析器立即期待下一个非空白字符是:。这是JSON语法铁律键值对必须由冒号分隔。期待一个值Value读取冒号后开始解析值可能是字符串、数字、对象、数组等。期待逗号或结束符解析完一个键值对后期待下一个非空白字符是,表示还有下一个键值对或}表示对象结束。2.2 位置5的玄机错误信息中的at 5指的是在原始字符串中从索引0开始计数的第6个字符因为索引从0开始。让我们手动计算一下字符串{name:张三, age:30}的索引字符序列 { n a m e : 张 三 , a g e : 3 0 } 索引位置 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22按照这个计算索引5的字符是e索引6的字符是。但错误信息说的是“在位置5期望一个冒号”。这似乎对不上这里有一个关键点解析器报告的位置可能是在它“卡住”或遇到意外字符时的索引而不一定是它期望找到冒号的那个精确位置。更可能的情况是当解析器在索引5或附近遇到一个它无法理解的字符时它回溯或记录了这个位置然后报告说“我在这里本来应该看到一个冒号来分隔键值对但我没看到”。所以at 5是一个强烈的信号在字符串开头部分很可能存在一个不可见或非预期的字符干扰了解析器对键名结束符的识别。解析器可能认为键名还没有结束或者在键名结束后没有立即看到期待的冒号于是报错。注意不同版本的Hutool或不同的JSON库对错误位置的报告可能略有差异但核心逻辑一致它告诉你在它解析的路径上语法出现了意外。3. 完整排查链路从怀疑到实证的侦探过程当遇到这种解析错误时切忌直接去修改JSON字符串本身比如手动加冒号而应该遵循一个系统的排查流程。下面是我这次采用的步骤它适用于绝大多数类似的字符串解析问题。3.1 第一步视觉检查与基础验证首先我确认了代码中的字符串字面量。看起来没问题。然后我使用了一个最原始但有效的方法打印字符串的长度和每个字符的十六进制表示。String jsonStr {\name\:\张三\, \age\:30}; System.out.println(字符串长度: jsonStr.length()); System.out.println(字符串内容带转义: jsonStr); // 打印前10个字符的ASCII/Unicode值 for (int i 0; i Math.min(10, jsonStr.length()); i) { char c jsonStr.charAt(i); System.out.printf(索引 %d: 字符 %c - Unicode: \\u%04x%n, i, c, (int) c); }输出结果让我发现了第一个异常字符串长度: 24 字符串内容带转义: {name:张三, age:30} 索引 0: 字符 { - Unicode: \u007b 索引 1: 字符 - Unicode: \u0022 索引 2: 字符 n - Unicode: \u006e 索引 3: 字符 a - Unicode: \u0061 索引 4: 字符 m - Unicode: \u006d 索引 5: 字符 e - Unicode: \u0065 索引 6: 字符 - Unicode: \u0022 索引 7: 字符 : - Unicode: \u003a ...长度24是符合预期的。前几个字符的Unicode码也正常。但问题可能就出在字符串的来源上。我意识到我例子中的字符串是手写的字面量但实际项目中这个字符串很可能来自网络请求响应、文件读取或数据库查询。于是我模拟了一个更真实的场景。3.2 第二步模拟真实数据源问题复现我创建了一个文本文件data.txt用Notepad以UTF-8编码编辑内容如下{name:张三, age:30}然后通过Java读取import cn.hutool.core.io.FileUtil; import cn.hutool.json.JSONUtil; import cn.hutool.json.JSONObject; public class TestJsonParse { public static void main(String[] args) { String jsonStr FileUtil.readUtf8String(data.txt); System.out.println(读取的字符串: jsonStr); System.out.println(长度: jsonStr.length()); try { JSONObject obj JSONUtil.parseObj(jsonStr); System.out.println(解析成功: obj); } catch (Exception e) { e.printStackTrace(); } } }运行后解析成功了。这说明单纯的文件读取UTF-8没有问题。那么什么情况下会引入不可见字符呢我想到了两个常见罪魁祸首字节顺序标记BOM某些编辑器或系统在保存UTF-8文件时会在文件开头添加一个不可见的BOM字符\uFEFF。换行符或空白符从某些富文本编辑器、网页复制粘贴时可能会引入特殊的空白字符如不间断空格\u00A0。3.3 第三步引入BOM制造问题我用Notepad重新创建data_with_bom.txt并明确指定编码为UTF-8-BOM。然后再次运行读取代码。果然报错了错误信息类似但位置可能变成了at 0或at 1因为BOM字符占据了最前面的索引。// 读取带BOM的文件后打印前三个字符 String jsonStrWithBom FileUtil.readUtf8String(data_with_bom.txt); for (int i 0; i 3; i) { char c jsonStrWithBom.charAt(i); System.out.printf(索引 %d: 字符 %c - Unicode: \\u%04x%n, i, c, (int) c); } // 输出可能包含索引 0: 字符 ? - Unicode: \ufeff (BOM)BOM字符\uFEFF对于JSON解析器来说是一个非法且意外的字符它期待的是{所以会立即报错。Hutool的JSONUtil默认不处理BOM。3.4 第四步排查网络请求与字符串拼接在实际开发中JSON字符串更常来自HTTP响应。如果使用HttpUtil等工具通常会自动处理编码。但如果你手动处理响应体或者字符串经过多次拼接、转换就可能出问题。例如// 模拟一个蹩脚的字符串拼接实际中可能是日志拼接、消息组装等 String part1 {\name\:; String part2 \张三\; String part3 , \age\:30}; String badJson part1 part2 part3; // 看起来没问题 // 但如果 part2 是从某个包含特殊空格的地方来的呢 String part2FromWeb 张三; // 注意这里的空格是全角空格或不间断空格 String badJson2 part1 part2FromWeb part3; JSONUtil.parseObj(badJson2); // 很可能报错因为键名 name 后面的值开头不是合法的引号这种错误信息可能就会是Expected a ‘:‘ after a key at X因为解析器在读完键name后期待一个冒号但接下来它遇到了一个奇怪的字符比如全角空格它无法识别为冒号于是报错。4. 根因定位与解决方案如何彻底清除这些“幽灵”通过以上排查我们可以将JSONException: Expected a ‘:‘ after a key at X的根因归结为一点在JSON字符串中键名Key与其后的冒号:之间存在解析器无法识别或视为非法的字符或字符序列。这些非法字符通常分为几类不可见控制字符如BOM (\uFEFF)、零宽空格 (\u200B)、文本方向标记等。非标准空白符如全角空格 (\u3000)、不间断空格 (\u00A0)、制表符 (\t)等。虽然标准JSON允许字符串值内包含转义的空格但在语法符号如{,,:,,之间解析器对空白符的定义可能比较严格或者这些字符在某些编码下被错误解读。编码不一致导致的乱码例如字符串是GBK编码的但你用UTF-8的方式去解析它导致某些多字节字符被拆分成多个非法单字节字符。字符串截断或损坏网络传输不完整、缓冲区大小限制导致字符串被意外截断使得一个完整的键名或值缺失了结束符。4.1 通用解决方案预处理与清洗最可靠的办法是在解析前对字符串进行清洗。Hutool本身提供了强大的工具。import cn.hutool.core.util.StrUtil; import cn.hutool.json.JSONUtil; import cn.hutool.json.JSONObject; public class SafeJsonParser { public static JSONObject parseSafely(String jsonStr) { if (StrUtil.isBlank(jsonStr)) { throw new IllegalArgumentException(JSON字符串为空); } // 方案1移除BOM (推荐) String cleaned StrUtil.removePrefix(jsonStr, \uFEFF); // 也可以使用 Hutool 的 BOM 相关工具 // cleaned BomReader.readUtf8(jsonStr.getBytes(StandardCharsets.UTF_8)); // 方案2替换所有非标准空白符为普通空格需谨慎可能改变语义 // 如果确定问题是非标准空白符可以使用此方法 // cleaned cleaned.replaceAll([\\u00A0\\u200B\\u3000], ); // 方案3使用更宽松的解析模式Hutool 5.8 // JSONConfig config JSONConfig.create().setStripTrailingZeros(false); // JSONObject obj new JSONObject(cleaned, config); try { return JSONUtil.parseObj(cleaned); } catch (cn.hutool.json.JSONException e) { // 如果清洗后还报错可能是更严重的语法错误或编码问题 System.err.println(清洗后字符串: cleaned); System.err.println(长度: cleaned.length()); // 可以进一步打印可疑位置的字符 int errorPos -1; // 这里可以简单尝试从异常信息中提取位置如果信息格式固定 String msg e.getMessage(); // 注意异常信息提取位置可能不总是准确仅供参考 System.err.println(原始异常: msg); throw new RuntimeException(JSON解析失败请检查字符串语法和编码, e); } } }4.2 针对不同来源的专项处理从文件读取使用FileUtil.readUtf8String通常能自动处理无BOM的UTF-8。如果文件可能有BOM使用上面的StrUtil.removePrefix或BomReader。从HTTP响应读取优先使用HttpUtil.get或HttpUtil.post它们内部会处理编码。如果自行处理InputStream务必指定正确的字符集例如IOUtil.read(stream, StandardCharsets.UTF_8)。从数据库读取确保数据库连接字符集如MySQL的characterEncodingutf8mb4与应用程序一致。有时数据库里存储的文本可能包含控制字符需要在查询后或存入前进行清洗。字符串拼接生成避免直接拼接使用JSONUtil.createObj()或JSONObject对象来构建JSON从源头上保证格式正确。// 正确做法使用对象构建而非字符串拼接 JSONObject obj JSONUtil.createObj(); obj.set(name, 张三); obj.set(age, 30); String safeJsonStr obj.toString(); // 这个字符串一定是语法正确的4.3 Hutool 5.7 与 5.8 的潜在差异在搜索相关热词时我注意到有“hutool 5.8与5.7协议上的区别”的讨论。虽然这里“协议”可能用词不准确但版本间JSON解析器的实现细节确实可能有变。例如对某些边缘字符的容忍度、错误信息的格式等。如果你的项目升级Hutool版本后突然出现此类错误可以检查新版本是否加强了对JSON标准的严格性检查是否引入了新的默认配置可以查看JSONConfig类的变化。使用JSONUtil.parseObj(jsonStr, JSONConfig.create())创建一个默认配置的解析器看行为是否一致。一个稳妥的做法是在升级依赖后对涉及JSON解析的关键用例进行回归测试。5. 举一反三其他常见JSON解析报错与关联排查Expected a ‘:‘ after a key只是JSON解析错误家族的一员。理解了这个错误的本质就能快速联想到其他类似错误并运用相同的排查方法论。5.1Expected a ‘,’ or ‘}’含义在对象中解析完一个值后期望遇到逗号下一个键值对或右花括号对象结束。常见原因最后一个键值对后面多了一个逗号{a:1, b:2,}标准JSON不允许尾随逗号但有些解析器支持。字符串中包含了未转义的控制字符或非法Unicode。数值或布尔值书写错误如{flag”: tru}true写成了tru。排查检查报错位置附近的字符特别是逗号和花括号的配对以及值的书写是否正确。5.2Unterminated string含义字符串没有以双引号结束。常见原因字符串中包含未转义的双引号{msg: He said hello}。字符串被意外截断。编码问题导致引号字符被“吃掉”或变成乱码。排查确保字符串内的双引号都使用反斜杠转义\。检查字符串长度是否完整。5.3Illegal unquoted character含义在需要引号的地方通常是键名使用了未加引号的字符。常见原因试图解析JavaScript风格的对象字面量允许键名不加引号但使用的是严格JSON解析器。排查确保你的字符串是标准JSON所有键名都用双引号包裹。Hutool的JSONUtil默认是严格模式。5.4 数字或布尔值解析错误含义NaN,Infinity或undefined等JavaScript特有的值在标准JSON中是不被允许的。常见原因后端序列化时错误地将这些特殊值写入了JSON字符串。排查在生成JSON的源头进行过滤将这些值转换为合法的JSON值如null或字符串。通用的高级排查技巧 对于任何复杂的、难以定位的JSON错误可以尝试以下步骤最小化复现将出错的JSON字符串复制到一个简单的测试程序中单独测试。在线验证使用在线的JSON验证工具如 jsonlint.com粘贴你的字符串看工具是否报错及报错位置。这能快速排除是否是基本的语法错误。十六进制查看如果怀疑有不可见字符用十六进制编辑器或代码如上面的\u%04x打印查看字符串的原始字节。逐段验证如果字符串很长可以尝试截取前半部分解析逐步增加长度定位出错的大致区间。6. 最佳实践与编码习惯防患于未然与其在报错后花费大量时间排查不如在编码和设计阶段就建立良好的习惯从根本上减少此类问题。6.1 统一字符编码在整个数据流中强制使用UTF-8。在Java中明确指定字符集读写文件Files.readString(path, StandardCharsets.UTF_8)/FileUtil.readUtf8String网络请求设置HTTP头Content-Type: application/json; charsetutf-8数据库连接在JDBC URL中指定useUnicodetruecharacterEncodingutf8mb4字符串转换避免使用无参的String.getBytes()和new String(byte[])总是带上StandardCharsets.UTF_8。6.2 使用库构建而非拼接这是最重要的原则。99%的JSON生成都应该通过库来完成。Hutool:JSONUtil.createObj(),JSONUtil.parseObj()。Jackson:ObjectMapper().writeValueAsString(object)。Gson:Gson().toJson(object)。 手动拼接不仅容易引入语法错误还可能造成严重的JSON注入安全漏洞。6.3 对输入进行验证和清洗对于任何来自外部用户输入、第三方接口、文件上传的JSON字符串在解析前进行预处理。Trim操作StrUtil.trim(jsonStr)可以去除首尾的空白符包括换行符但注意它不会去除中间的BOM。BOM处理使用前面提到的StrUtil.removePrefix。使用健壮的解析库一些库提供了“非严格模式”或“容错模式”可以解析一些不那么标准的JSON如尾随逗号、注释。但生产环境谨慎使用最好在入口处就规范数据格式。6.4 添加详细的日志和监控在解析JSON的关键位置记录原始字符串的长度、哈希值或前N个字符。当发生错误时这些信息能帮你快速判断是否是数据本身发生了变化或损坏。import lombok.extern.slf4j.Slf4j; Slf4j public class JsonService { public JSONObject parseExternalJson(String rawJson) { log.debug(尝试解析JSON长度: {}, 前50字符: {}, rawJson.length(), rawJson.length() 50 ? rawJson.substring(0, 50) ... : rawJson); try { String cleaned StrUtil.removePrefix(StrUtil.trim(rawJson), \uFEFF); return JSONUtil.parseObj(cleaned); } catch (JSONException e) { log.error(JSON解析失败。原始字符串Hex: {}, StrUtil.hex(rawJson), e); throw new BusinessException(数据格式错误, e); } } }6.5 编写单元测试为JSON解析逻辑编写单元测试覆盖各种边界情况正常JSON。带BOM的JSON。包含特殊空白符的JSON。空字符串、null。格式错误缺失引号、冒号、逗号的JSON验证其是否按预期抛出异常。通过这次对Expected a ‘:‘ after a key错误的深入排查我再次深刻体会到在软件开发中最“简单”的字符串处理往往隐藏着最棘手的编码和边界问题。面对这类问题一套科学的排查方法打印长度、查看原始字节、最小化复现远比盲目猜测有效。而养成良好的编码习惯统一编码、库构建JSON、输入清洗则是避免问题的最佳防线。希望我的这次踩坑经历能帮你下次遇到类似问题时快速定位从容解决。 
长河君 · 2026/8/26 21:37:52 · 阅读 1.2k JSON解析报错Expected a ‘:‘ after a key排查与解决
1. 问题现场一个看似简单的JSON解析为何突然“罢工”今天在调试一个老项目时遇到了一个让我卡了半个小时的“小”问题。场景很常见从外部接口拿到一个JSON字符串用Hutool的JSONUtil去解析准备提取里面的数据。代码就一行简单得不能再简单String jsonStr {\name\:\张三\, \age\:30}; JSONObject jsonObject JSONUtil.parseObj(jsonStr);按理说这应该稳稳地输出一个JSONObject。但实际运行后控制台却无情地抛出了一个cn.hutool.json.JSONExceptioncn.hutool.json.JSONException: Expected a ‘:‘ after a key at 5“在位置5期望一个冒号”我盯着字符串{name:张三, age:30}数了又数从0开始索引位置5的字符明明是第二个双引号这语法看起来完全正确啊。相信很多用过Hutool的朋友都遇到过类似的报错错误信息指向一个看似没有问题的位置让人一头雾水。这不仅仅是Hutool的问题而是处理JSON这种结构化数据时一个非常典型且容易踩坑的场景——字符串中不可见的“幽灵字符”。这个问题背后牵扯到字符编码、数据来源、字符串处理习惯等一系列细节。接下来我就把这次排查的完整链路、根因分析以及一劳永逸的解决方案毫无保留地分享给你。2. 错误信息深度拆解Expected a ‘:‘ after a key at 5到底在说什么首先我们得真正理解Hutool抛出的这个异常信息。JSONException: Expected a ‘:‘ after a key at 5这句话是Hutool内置的JSON解析器在词法分析Lexical Analysis阶段抛出的。2.1 JSON解析器的“阅读”过程你可以把JSON解析器想象成一个严格的语法检查员它按照标准JSON规范RFC 8259逐字符扫描你提供的字符串。它的工作流程大致是这样的期待一个对象开始遇到{进入解析对象状态。期待一个键Key键必须是双引号包裹的字符串。解析器会寻找下一个然后读取直到遇到配对的中间的内容就是键名。期待一个冒号读取完键名和后面的后解析器立即期待下一个非空白字符是:。这是JSON语法铁律键值对必须由冒号分隔。期待一个值Value读取冒号后开始解析值可能是字符串、数字、对象、数组等。期待逗号或结束符解析完一个键值对后期待下一个非空白字符是,表示还有下一个键值对或}表示对象结束。2.2 位置5的玄机错误信息中的at 5指的是在原始字符串中从索引0开始计数的第6个字符因为索引从0开始。让我们手动计算一下字符串{name:张三, age:30}的索引字符序列 { n a m e : 张 三 , a g e : 3 0 } 索引位置 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22按照这个计算索引5的字符是e索引6的字符是。但错误信息说的是“在位置5期望一个冒号”。这似乎对不上这里有一个关键点解析器报告的位置可能是在它“卡住”或遇到意外字符时的索引而不一定是它期望找到冒号的那个精确位置。更可能的情况是当解析器在索引5或附近遇到一个它无法理解的字符时它回溯或记录了这个位置然后报告说“我在这里本来应该看到一个冒号来分隔键值对但我没看到”。所以at 5是一个强烈的信号在字符串开头部分很可能存在一个不可见或非预期的字符干扰了解析器对键名结束符的识别。解析器可能认为键名还没有结束或者在键名结束后没有立即看到期待的冒号于是报错。注意不同版本的Hutool或不同的JSON库对错误位置的报告可能略有差异但核心逻辑一致它告诉你在它解析的路径上语法出现了意外。3. 完整排查链路从怀疑到实证的侦探过程当遇到这种解析错误时切忌直接去修改JSON字符串本身比如手动加冒号而应该遵循一个系统的排查流程。下面是我这次采用的步骤它适用于绝大多数类似的字符串解析问题。3.1 第一步视觉检查与基础验证首先我确认了代码中的字符串字面量。看起来没问题。然后我使用了一个最原始但有效的方法打印字符串的长度和每个字符的十六进制表示。String jsonStr {\name\:\张三\, \age\:30}; System.out.println(字符串长度: jsonStr.length()); System.out.println(字符串内容带转义: jsonStr); // 打印前10个字符的ASCII/Unicode值 for (int i 0; i Math.min(10, jsonStr.length()); i) { char c jsonStr.charAt(i); System.out.printf(索引 %d: 字符 %c - Unicode: \\u%04x%n, i, c, (int) c); }输出结果让我发现了第一个异常字符串长度: 24 字符串内容带转义: {name:张三, age:30} 索引 0: 字符 { - Unicode: \u007b 索引 1: 字符 - Unicode: \u0022 索引 2: 字符 n - Unicode: \u006e 索引 3: 字符 a - Unicode: \u0061 索引 4: 字符 m - Unicode: \u006d 索引 5: 字符 e - Unicode: \u0065 索引 6: 字符 - Unicode: \u0022 索引 7: 字符 : - Unicode: \u003a ...长度24是符合预期的。前几个字符的Unicode码也正常。但问题可能就出在字符串的来源上。我意识到我例子中的字符串是手写的字面量但实际项目中这个字符串很可能来自网络请求响应、文件读取或数据库查询。于是我模拟了一个更真实的场景。3.2 第二步模拟真实数据源问题复现我创建了一个文本文件data.txt用Notepad以UTF-8编码编辑内容如下{name:张三, age:30}然后通过Java读取import cn.hutool.core.io.FileUtil; import cn.hutool.json.JSONUtil; import cn.hutool.json.JSONObject; public class TestJsonParse { public static void main(String[] args) { String jsonStr FileUtil.readUtf8String(data.txt); System.out.println(读取的字符串: jsonStr); System.out.println(长度: jsonStr.length()); try { JSONObject obj JSONUtil.parseObj(jsonStr); System.out.println(解析成功: obj); } catch (Exception e) { e.printStackTrace(); } } }运行后解析成功了。这说明单纯的文件读取UTF-8没有问题。那么什么情况下会引入不可见字符呢我想到了两个常见罪魁祸首字节顺序标记BOM某些编辑器或系统在保存UTF-8文件时会在文件开头添加一个不可见的BOM字符\uFEFF。换行符或空白符从某些富文本编辑器、网页复制粘贴时可能会引入特殊的空白字符如不间断空格\u00A0。3.3 第三步引入BOM制造问题我用Notepad重新创建data_with_bom.txt并明确指定编码为UTF-8-BOM。然后再次运行读取代码。果然报错了错误信息类似但位置可能变成了at 0或at 1因为BOM字符占据了最前面的索引。// 读取带BOM的文件后打印前三个字符 String jsonStrWithBom FileUtil.readUtf8String(data_with_bom.txt); for (int i 0; i 3; i) { char c jsonStrWithBom.charAt(i); System.out.printf(索引 %d: 字符 %c - Unicode: \\u%04x%n, i, c, (int) c); } // 输出可能包含索引 0: 字符 ? - Unicode: \ufeff (BOM)BOM字符\uFEFF对于JSON解析器来说是一个非法且意外的字符它期待的是{所以会立即报错。Hutool的JSONUtil默认不处理BOM。3.4 第四步排查网络请求与字符串拼接在实际开发中JSON字符串更常来自HTTP响应。如果使用HttpUtil等工具通常会自动处理编码。但如果你手动处理响应体或者字符串经过多次拼接、转换就可能出问题。例如// 模拟一个蹩脚的字符串拼接实际中可能是日志拼接、消息组装等 String part1 {\name\:; String part2 \张三\; String part3 , \age\:30}; String badJson part1 part2 part3; // 看起来没问题 // 但如果 part2 是从某个包含特殊空格的地方来的呢 String part2FromWeb 张三; // 注意这里的空格是全角空格或不间断空格 String badJson2 part1 part2FromWeb part3; JSONUtil.parseObj(badJson2); // 很可能报错因为键名 name 后面的值开头不是合法的引号这种错误信息可能就会是Expected a ‘:‘ after a key at X因为解析器在读完键name后期待一个冒号但接下来它遇到了一个奇怪的字符比如全角空格它无法识别为冒号于是报错。4. 根因定位与解决方案如何彻底清除这些“幽灵”通过以上排查我们可以将JSONException: Expected a ‘:‘ after a key at X的根因归结为一点在JSON字符串中键名Key与其后的冒号:之间存在解析器无法识别或视为非法的字符或字符序列。这些非法字符通常分为几类不可见控制字符如BOM (\uFEFF)、零宽空格 (\u200B)、文本方向标记等。非标准空白符如全角空格 (\u3000)、不间断空格 (\u00A0)、制表符 (\t)等。虽然标准JSON允许字符串值内包含转义的空格但在语法符号如{,,:,,之间解析器对空白符的定义可能比较严格或者这些字符在某些编码下被错误解读。编码不一致导致的乱码例如字符串是GBK编码的但你用UTF-8的方式去解析它导致某些多字节字符被拆分成多个非法单字节字符。字符串截断或损坏网络传输不完整、缓冲区大小限制导致字符串被意外截断使得一个完整的键名或值缺失了结束符。4.1 通用解决方案预处理与清洗最可靠的办法是在解析前对字符串进行清洗。Hutool本身提供了强大的工具。import cn.hutool.core.util.StrUtil; import cn.hutool.json.JSONUtil; import cn.hutool.json.JSONObject; public class SafeJsonParser { public static JSONObject parseSafely(String jsonStr) { if (StrUtil.isBlank(jsonStr)) { throw new IllegalArgumentException(JSON字符串为空); } // 方案1移除BOM (推荐) String cleaned StrUtil.removePrefix(jsonStr, \uFEFF); // 也可以使用 Hutool 的 BOM 相关工具 // cleaned BomReader.readUtf8(jsonStr.getBytes(StandardCharsets.UTF_8)); // 方案2替换所有非标准空白符为普通空格需谨慎可能改变语义 // 如果确定问题是非标准空白符可以使用此方法 // cleaned cleaned.replaceAll([\\u00A0\\u200B\\u3000], ); // 方案3使用更宽松的解析模式Hutool 5.8 // JSONConfig config JSONConfig.create().setStripTrailingZeros(false); // JSONObject obj new JSONObject(cleaned, config); try { return JSONUtil.parseObj(cleaned); } catch (cn.hutool.json.JSONException e) { // 如果清洗后还报错可能是更严重的语法错误或编码问题 System.err.println(清洗后字符串: cleaned); System.err.println(长度: cleaned.length()); // 可以进一步打印可疑位置的字符 int errorPos -1; // 这里可以简单尝试从异常信息中提取位置如果信息格式固定 String msg e.getMessage(); // 注意异常信息提取位置可能不总是准确仅供参考 System.err.println(原始异常: msg); throw new RuntimeException(JSON解析失败请检查字符串语法和编码, e); } } }4.2 针对不同来源的专项处理从文件读取使用FileUtil.readUtf8String通常能自动处理无BOM的UTF-8。如果文件可能有BOM使用上面的StrUtil.removePrefix或BomReader。从HTTP响应读取优先使用HttpUtil.get或HttpUtil.post它们内部会处理编码。如果自行处理InputStream务必指定正确的字符集例如IOUtil.read(stream, StandardCharsets.UTF_8)。从数据库读取确保数据库连接字符集如MySQL的characterEncodingutf8mb4与应用程序一致。有时数据库里存储的文本可能包含控制字符需要在查询后或存入前进行清洗。字符串拼接生成避免直接拼接使用JSONUtil.createObj()或JSONObject对象来构建JSON从源头上保证格式正确。// 正确做法使用对象构建而非字符串拼接 JSONObject obj JSONUtil.createObj(); obj.set(name, 张三); obj.set(age, 30); String safeJsonStr obj.toString(); // 这个字符串一定是语法正确的4.3 Hutool 5.7 与 5.8 的潜在差异在搜索相关热词时我注意到有“hutool 5.8与5.7协议上的区别”的讨论。虽然这里“协议”可能用词不准确但版本间JSON解析器的实现细节确实可能有变。例如对某些边缘字符的容忍度、错误信息的格式等。如果你的项目升级Hutool版本后突然出现此类错误可以检查新版本是否加强了对JSON标准的严格性检查是否引入了新的默认配置可以查看JSONConfig类的变化。使用JSONUtil.parseObj(jsonStr, JSONConfig.create())创建一个默认配置的解析器看行为是否一致。一个稳妥的做法是在升级依赖后对涉及JSON解析的关键用例进行回归测试。5. 举一反三其他常见JSON解析报错与关联排查Expected a ‘:‘ after a key只是JSON解析错误家族的一员。理解了这个错误的本质就能快速联想到其他类似错误并运用相同的排查方法论。5.1Expected a ‘,’ or ‘}’含义在对象中解析完一个值后期望遇到逗号下一个键值对或右花括号对象结束。常见原因最后一个键值对后面多了一个逗号{a:1, b:2,}标准JSON不允许尾随逗号但有些解析器支持。字符串中包含了未转义的控制字符或非法Unicode。数值或布尔值书写错误如{flag”: tru}true写成了tru。排查检查报错位置附近的字符特别是逗号和花括号的配对以及值的书写是否正确。5.2Unterminated string含义字符串没有以双引号结束。常见原因字符串中包含未转义的双引号{msg: He said hello}。字符串被意外截断。编码问题导致引号字符被“吃掉”或变成乱码。排查确保字符串内的双引号都使用反斜杠转义\。检查字符串长度是否完整。5.3Illegal unquoted character含义在需要引号的地方通常是键名使用了未加引号的字符。常见原因试图解析JavaScript风格的对象字面量允许键名不加引号但使用的是严格JSON解析器。排查确保你的字符串是标准JSON所有键名都用双引号包裹。Hutool的JSONUtil默认是严格模式。5.4 数字或布尔值解析错误含义NaN,Infinity或undefined等JavaScript特有的值在标准JSON中是不被允许的。常见原因后端序列化时错误地将这些特殊值写入了JSON字符串。排查在生成JSON的源头进行过滤将这些值转换为合法的JSON值如null或字符串。通用的高级排查技巧 对于任何复杂的、难以定位的JSON错误可以尝试以下步骤最小化复现将出错的JSON字符串复制到一个简单的测试程序中单独测试。在线验证使用在线的JSON验证工具如 jsonlint.com粘贴你的字符串看工具是否报错及报错位置。这能快速排除是否是基本的语法错误。十六进制查看如果怀疑有不可见字符用十六进制编辑器或代码如上面的\u%04x打印查看字符串的原始字节。逐段验证如果字符串很长可以尝试截取前半部分解析逐步增加长度定位出错的大致区间。6. 最佳实践与编码习惯防患于未然与其在报错后花费大量时间排查不如在编码和设计阶段就建立良好的习惯从根本上减少此类问题。6.1 统一字符编码在整个数据流中强制使用UTF-8。在Java中明确指定字符集读写文件Files.readString(path, StandardCharsets.UTF_8)/FileUtil.readUtf8String网络请求设置HTTP头Content-Type: application/json; charsetutf-8数据库连接在JDBC URL中指定useUnicodetruecharacterEncodingutf8mb4字符串转换避免使用无参的String.getBytes()和new String(byte[])总是带上StandardCharsets.UTF_8。6.2 使用库构建而非拼接这是最重要的原则。99%的JSON生成都应该通过库来完成。Hutool:JSONUtil.createObj(),JSONUtil.parseObj()。Jackson:ObjectMapper().writeValueAsString(object)。Gson:Gson().toJson(object)。 手动拼接不仅容易引入语法错误还可能造成严重的JSON注入安全漏洞。6.3 对输入进行验证和清洗对于任何来自外部用户输入、第三方接口、文件上传的JSON字符串在解析前进行预处理。Trim操作StrUtil.trim(jsonStr)可以去除首尾的空白符包括换行符但注意它不会去除中间的BOM。BOM处理使用前面提到的StrUtil.removePrefix。使用健壮的解析库一些库提供了“非严格模式”或“容错模式”可以解析一些不那么标准的JSON如尾随逗号、注释。但生产环境谨慎使用最好在入口处就规范数据格式。6.4 添加详细的日志和监控在解析JSON的关键位置记录原始字符串的长度、哈希值或前N个字符。当发生错误时这些信息能帮你快速判断是否是数据本身发生了变化或损坏。import lombok.extern.slf4j.Slf4j; Slf4j public class JsonService { public JSONObject parseExternalJson(String rawJson) { log.debug(尝试解析JSON长度: {}, 前50字符: {}, rawJson.length(), rawJson.length() 50 ? rawJson.substring(0, 50) ... : rawJson); try { String cleaned StrUtil.removePrefix(StrUtil.trim(rawJson), \uFEFF); return JSONUtil.parseObj(cleaned); } catch (JSONException e) { log.error(JSON解析失败。原始字符串Hex: {}, StrUtil.hex(rawJson), e); throw new BusinessException(数据格式错误, e); } } }6.5 编写单元测试为JSON解析逻辑编写单元测试覆盖各种边界情况正常JSON。带BOM的JSON。包含特殊空白符的JSON。空字符串、null。格式错误缺失引号、冒号、逗号的JSON验证其是否按预期抛出异常。通过这次对Expected a ‘:‘ after a key错误的深入排查我再次深刻体会到在软件开发中最“简单”的字符串处理往往隐藏着最棘手的编码和边界问题。面对这类问题一套科学的排查方法打印长度、查看原始字节、最小化复现远比盲目猜测有效。而养成良好的编码习惯统一编码、库构建JSON、输入清洗则是避免问题的最佳防线。希望我的这次踩坑经历能帮你下次遇到类似问题时快速定位从容解决。