真实项目里摸爬滚打的同学大概率都遇到过这种场面接口文档写得清清楚楚联调时返回的 JSON 却一个比一个“野”。字段时有时无价格一会儿是数字一会儿是字符串嵌套结构深浅不一偶尔还直接甩给你一个 JSONDecodeError。Python 解析这类不规则 JSON如果只会json.loads加 for 循环大概率会被数据“教育”。这篇文章把实战中摸出来的几个解析技巧整理出来该兜底的时候兜底该容忍的时候容忍该规范的时候规范。适合做爬虫、数据接入、API 联调、日志分析的朋友直接抄作业也适合刚接触 Python 数据处理的人建立正确的容错意识。1. 需求拆解为什么 JSON 会变“脏乱差”1.1 常见的不规则类型归纳我遇到的“脏乱差”JSON基本可以归纳成下面五类。第一类是字段缺失接口版本升级后有些字段不再返回或者后端只在下单用户才会返回手机号导致同一条记录的结构不一致。第二类是类型漂移同一个 price 字段第一批数据是数字 299第二批变成了字符串 299.0第三批干脆是 null还有可能混进一个空数组。第三类是结构歧义后端心情好的时候返回单个对象心情不好就返回数组甚至把整个数据包再包一层。第四类是最折磨人的语法瑕疵单引号、尾逗号、NaN、裸 undefined、BOM 头json.loads一看就直接翻脸。第五类是超大文件几十 GB 的 JSON 日志文件json.load读一次内存直接爆炸。这五类问题通常不会单独出现而是叠在一起。比如我接过的一个数据源前三万条记录都很正常三万零一条开始字段名突然变成驼峰格式四万条之后 price 字段变成了数组最后几万条干脆混进了坏语法。这种数据如果不在解析阶段做处理后面所有下游逻辑都会跟着遭殃。所以解析不规则 JSON 的核心不是“把某个具体坑填平”而是建立一套容错管道先修复语法再安全取值再统一类型最后规范化结构。1.2 盲目使用 json.loads 会踩的坑很多刚入门的同学习惯直接data json.loads(response.text)然后data[user][address][city]一路取下去。这种写法遇到不规则数据时到处都是坑。最轻的是 KeyError 和 IndexError某个字段没返回程序直接中断重一点的可能不报错但取回来一个 None后面不检查就直接拼字符串最后写进数据库变成 None排查起来比报错还恶心。类型不一致的坑更隐蔽。比如item[price]在大部分场景下是浮点数但突然有一条记录返回字符串 99.90你拿它做price * 0.8时直接抛 TypeError而更阴险的是布尔值Python 里True和1在某些场景下相等如果你用v 1去判断字段返回的结果会让人摸不着头脑。还有结构歧义后端把{products: [{id: 1}, {id: 2}]}改成{products: {id: 1}}你的遍历循环会瞬间失效。所以我的建议是把 json.loads 当成“最后的手段”而不是默认手段。在它外面套一层防护再进入取值逻辑这才是稳定的做法。下面几个技巧就是围绕这个思路展开的。2. 四个核心技巧逐个攻克不规则数据2.1 技巧一语法瑕疵用 json_repair 兜底标准库json.loads对语法非常严格稍微有一点不符合 RFC 8259 的内容就会报错。比如接口返回{name: 耳机, price: 299}单引号直接导致 JSONDecodeError又比如返回[1, 2, 3, ]尾逗号直接翻脸再比如{sold: NaN}这在 JS 里合法Python 标准库却不认识。解析这类内容我的第一道防线是第三方库json_repair。先安装pip install json-repair使用方式很直接from json_repair import repair_json text {name: 耳机, price: 299, sold: NaN, tags: [数码,],} data repair_json(text, return_objectsTrue) print(data) # {name: 耳机, price: 299, sold: nan, tags: [数码]}注意repair_json默认返回的是修复后的 JSON 字符串加上return_objectsTrue才能直接拿到 Python 对象。网上很多教程只写repair_json(text)结果拿到字符串又去json.loads一次多此一举。这个库的原理是先把输入切成 token再用容错状态机重组能修的单引号、尾逗号、不规范小数、NaN/Infinity 都会尽量修修不了的会返回修复后的最佳结果不会整个解析崩溃。不过要明确一点json_repair 是兜底工具不是万能药。它处理的是语法层的问题对语义问题无能为力。比如字段缺失、类型漂移、结构歧义这些它一概不管。所以我的习惯是两段式解析先用标准库json.loads快速尝试只有失败时才去调用repair_json。这样既保证速度快也不至于为了几个坏数据牺牲整体性能。import json def safe_loads(text): try: return json.loads(text) except json.JSONDecodeError: from json_repair import repair_json return repair_json(text, return_objectsTrue)这个安全加载函数是整个解析管道的入口后面所有处理都建立在它返回的 Python 对象之上。实际使用时如果repair_json修出来的结果类型不对比如本应是 dict 却返回了一个空字符串你可以在safe_loads里再加一个类型校验确保外层调用者拿到的肯定是 dict否则抛出业务异常。这一步能在源头拦截大量因解析失败导致的后续连锁反应。2.2 技巧二安全取值与默认值策略拿到对象之后第二步是安全取值。我强烈建议不要在业务代码里裸写data[user][address][city]这种链条。规则很简单能取到就取取不到就给默认值但默认值要明确区分“缺字段”和“字段值就是 None”。最基础的做法是dict.getuser data.get(user, {}) address user.get(address, {}) city address.get(city, 未知)如果你觉得链式 get 写起来太啰嗦可以封装一个deep_get接受一个键列表def deep_get(data, keys, defaultNone): cur data for k in keys: if isinstance(cur, dict) and k in cur: cur cur[k] else: return default return cur city deep_get(data, [user, address, city], 未知)这个函数的好处是中间任何一层不是字典都会安全返回默认值不会抛 KeyError 或 TypeError。另外一个我常用的技巧是引入一个哨兵对象用来区分“字段压根不存在”和“字段存在但值为 None”因为两者在真实数据里含义完全不同MISSING object() def deep_get_strict(data, keys): cur data for k in keys: if isinstance(cur, dict) and k in cur: cur cur[k] else: return MISSING return cur拿到 sentinel 后你可以决定这条记录是跳过、用默认值还是专门标记为异常。我在清洗阶段通常会把“字段缺失”的记录单独挑出来放到异常队列里而不是默默填一个默认值这样下游同事能一眼看到数据质量问题。2.3 技巧三类型漂移的统一与强转第三步是处理类型漂移。这类问题最常见的就是数字字段。一个 price有时是 int有时是 str有时是 float偶尔还可能给你一个空字符串。我的做法是写一个宽容的类型转换函数把所有形态统一成 int 或 floatdef to_int(value, default0): if isinstance(value, bool): return 1 if value else 0 if isinstance(value, int): return value if isinstance(value, float): return int(value) if isinstance(value, str): text value.strip().replace(,, ).replace(元, ) try: return int(float(text)) except ValueError: return default if isinstance(value, list): return to_int(value[0], default) if value else default return default def to_float(value, default0.0): if isinstance(value, bool): return 1.0 if value else 0.0 if isinstance(value, (int, float)): return float(value) if isinstance(value, str): text value.strip().replace(,, ).replace(元, ) try: return float(text) except ValueError: return default if isinstance(value, list): return to_float(value[0], default) if value else default return default字符串处理里先去千分位逗号再处理货币单位这样能兼容 1,299、99.9元 这类野路子写法。类似的还可以写to_bool把字符串 true、yes、1、数字 1/0 都统一成布尔值def to_bool(value, defaultFalse): if isinstance(value, bool): return value if isinstance(value, (int, float)): return value ! 0 if isinstance(value, str): return value.strip().lower() in (1, true, yes, y, on, 是) return default写这种函数时有一个理念问题需要想清楚统一的规则要放到解析阶段还是放到使用阶段我的经验是尽量在解析阶段完成越快统一越好。因为下游的计算、入库、报警都可能直接消费这个字段让每个业务方自己去处理 99.9 和 99.9元 的差别迟早会出事。我见过最惨的一次线上事故就是因为一个价格字段被写成了字符串报表那边求和时静默变成了字符串拼接数字全乱套事后查了很久才发现是解析层没有统一类型。2.4 技巧四递归提取与结构扁平化第四步处理嵌套结构不一致的问题。真实数据里同一个业务含义的字段可能出现在不同层级或者同一个 value 一会儿是{price: 100}一会儿是{detail: {price: 100}}。这时候与其写死路径不如写一个递归提取器把所有键和值拍平再搜索目标键def flatten_json(data, parent_key, sep_): items {} if isinstance(data, dict): for k, v in data.items(): new_key f{parent_key}{sep}{k} if parent_key else k if isinstance(v, dict): items.update(flatten_json(v, new_key, sepsep)) elif isinstance(v, list): for i, item in enumerate(v): items.update(flatten_json(item, f{new_key}{sep}{i}, sepsep)) else: items[new_key] v return items flat flatten_json({product: {name: 耳机, detail: {price: 299}}}) print(flat) # {product_name: 耳机, product_detail_price: 299}拍平之后再配合一个按 key 模糊搜索的函数就能在结构不确定的数据里快速捞字段def extract_by_key(data, target_key): results [] if isinstance(data, dict): for k, v in data.items(): if k target_key: results.append(v) results.extend(extract_by_key(v, target_key)) elif isinstance(data, list): for item in data: results.extend(extract_by_key(item, target_key)) return results这个函数会把所有层级的同名 key 都捞出来返回一个列表。如果数据规范时列表只有一个元素如果出现多个说明数据结构比预期还乱正好可以触发人工检查。扁平化的另一个好处是方便调试你可以在报错时直接打印 flat 字典一眼看出哪个字段被吞了不用在十几层嵌套里翻找。3. 实战演练多源商品数据的清洗管道3.1 构造一个“脏乱差”的数据样例技巧单独看都没什么问题但真正考验人的是把它们组合起来。我构造一个实际接过的场景需要合并三个来源的商品数据三个来源的结构完全不一致。来源 A 返回的是正常的单条 JSON{product_id: 1, name: 无线耳机, price: 299}来源 B 稍微野一点字段名不一样价格是字符串还多了嵌套标签{id: 2, title: 蓝牙耳机, amount: 199.90, tags: {category: [数码, 音乐]}}来源 C 是整个数据被包了一层数组单个商品页用数组包装字段也杂{products: [{product_id: 3, name: 耳机, price: 99, active: yes}]}另外还有一个坏数据文件里面混着单引号、尾逗号还有一条记录把 price 写成了nullname 字段直接缺失。我需要把这三个来源的数据统一清洗成同样结构id整数、name字符串、price浮点数、tags列表、active布尔值。3.2 完整解析管道的代码实现先写好前面提到的几个工具函数safe_loads、deep_get、to_int、to_float、to_bool、flatten_json。然后把规范化的逻辑放进一个normalize_product函数def normalize_product(raw): if isinstance(raw, list): raw raw[0] if raw else {} if isinstance(raw, dict) and isinstance(raw.get(products), list): raw raw[products][0] if raw[products] else {} if not isinstance(raw, dict): return None flat flatten_json(raw) def first_present(data, keys): for k in keys: if k in data and data[k] is not None: return data[k] return None def extract_tags(flat): keys sorted(k for k in flat if k.startswith(tags_category_)) return [flat[k] for k in keys] product { id: to_int(first_present(flat, [product_id, id]), 0), name: first_present(flat, [name, title]) or , price: to_float(first_present(flat, [price, amount]), 0.0), active: to_bool(first_present(flat, [active])), tags: extract_tags(flat) or first_present(flat, [tags, category]) or [], } return product注意几个细节。第一先用flatten_json把来源 C 里的products_0_product_id这类键展开这样first_present才能在同一层拿到所有候选 key第二用is not None判断而不是or因为我踩过坑price 是 0 的时候first_present(flat, [price]) or 0.0会把 0 误判成缺失最后错误地把默认值填进去第三tags 字段来源 B 是一个嵌套字典{category: [数码, 音乐]}拍平后会出现tags_category_0这样的键所以要先通过extract_tags把拍平后的标签列表重新组装回来。实际测试时我用一个混合列表模拟三个来源的数据然后把normalize_product套在一个循环里跑raw_list [ {product_id: 1, name: 无线耳机, price: 299}, {id: 2, title: 蓝牙耳机, amount: 199.90, tags: {category: [数码, 音乐]}}, {products: [{product_id: 3, name: 耳机, price: 99, active: yes}]}, bad syntax {, ] for raw in raw_list: parsed safe_loads(raw) if isinstance(raw, str) else raw print(normalize_product(parsed))输出结果{id: 1, name: 无线耳机, price: 299.0, active: False, tags: []} {id: 2, name: 蓝牙耳机, price: 199.9, active: False, tags: [数码, 音乐]} {id: 3, name: 耳机, price: 99.0, active: True, tags: []} None最后一条坏数据safe_loads修复失败后返回 Nonenormalize_product直接返回 None在真实管道里我会把它记入异常队列而不是让整个任务中断。3.3 参数选择与执行效率考量代码跑通只是第一步实际生产中还要考虑效率。我这里重点说一下性能取舍。第一safe_loads里的 try/except 是零成本的只要不抛出异常json.loads本身走的是 C 扩展速度非常快而repair_json是纯 Python 实现速度慢一个量级所以我只在语法解析失败时才调用它这就是“两段式解析”的价值。第二如果数据量很大比如一次要清洗 100 万条记录不要在每条记录里都调用repair_json或者flatten_json特别是flatten_json会在每条记录上重新分配字典内存开销不小。我通常会给解析管道加一层缓存和提前退出先用json.loads快速判断是否是合法 JSON如果不合法再走修复对于flatten_json如果记录本身是单层结构就别递归直接返回原始 dict。简单判断any(isinstance(v, (dict, list)) for v in raw.values())就能提前决定。第三source C 这种外层数组的包装可能是批量接口格式。如果数据是{products: [...]}最好是先取出 products 数组再批量解析而不是把整个大对象传进去。这样既能减少内存压力也能让每条记录的错误独立处理一条坏了不影响其他条。我项目里通常写一个生成器函数按记录 yield配合 tqdm 看进度条清洗百万级数据也就一两分钟的事。4. 高频问题排查与避坑记录4.1 JSONDecodeError 的不同报错形态实际用下来JSONDecodeError 的报错信息能透露很多线索。最常见的是Expecting property name enclosed in double quotes说明有单引号字段名这类数据八成来自 JavaScript 或者人工粘贴Expecting value一般发生在字符串开头可能是空字符串、undefined 或者 BOM 头Extra data说明一段文本里塞了多个 JSON 对象常见于多行日志拼接Unterminated string starting at则是字符串被截断通常和网络请求失败或文件被截断有关。我的排查顺序一般是先用repr(text[:200])打印出原始文本前 200 个字符确认有没有 BOM、单引号、undefined 这些东西再用编辑器或命令行看文件尾有没有截断痕迹最后才决定是走repair_json还是在源头修。很多时候报错只是表象根因其实是对方接口编码问题或者网络传输丢数据解析层的兜底只能帮你处理格式问题不能帮你掩盖数据链路的问题。4.2 编码、BOM 与 Unicode 乱码读到 JSON 文件乱码90% 是编码问题。标准json.load默认按 UTF-8 解码但很多老旧系统导出的文件是 GBK 或 GB2312甚至带上 BOM 头。遇到这种情况先用二进制模式打开再探测编码会更稳import chardet with open(data.json, rb) as f: raw f.read() encoding chardet.detect(raw)[encoding] text raw.decode(encoding, errorsreplace) data json.loads(text)BOM 头会导致json.loads直接报Unexpected UTF-8 BOM解码时用utf-8-sig就能自动去掉。写文件时也注意如果你需要输出中文用json.dump(data, f, ensure_asciiFalse)否则默认会把中文转成\uXXXX序列人读起来全是乱码虽然数据没错但给下游非技术同事看文件时体验非常差。4.3 超大 JSON 文件的内存危机单文件几百 MB 甚至几十 GB 时json.load和json.loads都会一次性把整个对象读进内存前面数据解析得再优雅这一步就已经扛不住了。对于由多个 JSON 对象组成的流式文件我用ijson做增量解析pip install ijsonimport ijson with open(big_log.json, rb) as f: for obj in ijson.items(f, item): process(obj)ijson的底层是拉模式词法分析边读边 yield 对象内存占用能控制在很小的常数范围内。如果文件刚好是 JSONL 格式每行一个 JSON 对象根本不用ijson直接逐行readline再json.loads即可还能配合失败的 record 编号定位数据问题。另外很多“超大 JSON”其实是数组但数组元素彼此独立这时你也完全可以改造成 JSONL 输出让下游消费者按行读取这是最实际的一个架构建议。4.4 深层嵌套定位与 JSONPath 应用嵌套特别深的数据手动一层层从 data 往下翻容易看花眼。我常用两个工具一个是自己写的递归搜索函数也就是前面提到的extract_by_key适合“我知道某个 key 名但不确定它在几层”的场景另一个是jsonpath-ng适合“我知道路径结构想按表达式取一批节点”的场景pip install jsonpath-ngfrom jsonpath_ng import parse import json data json.loads(open(nested.json, encodingutf-8).read()) expr parse($.store.book[*].author) authors [match.value for match in expr.find(data)]JSONPath 的表达式语法和 XPATH 类似*通配、..递归下降都用得到。遇到不确定路径时先打印数据里的 key 出现次数比如枚举所有 key 并统计判断有没有拼写差异productId vs product_id、price vs Price。这类大小写不一致问题在真实数据里非常普遍我一般会先把所有 key 转成统一的小写下划线风格再做后续处理。4.5 不规则数据解析速查表现象可能原因推荐解法json.loads 报单引号错误JS 或手工生成的非标准 JSONjson_repair 或正则替换单引号字段缺失 / KeyError接口版本不一致、条件字段deep_get 默认值缺失记录进异常队列数字字段是字符串后端格式化输出to_int / to_float 统一强转去千分位和货币符号布尔字段是 yes/1不同语言布尔表示不同to_bool 统一归一单个对象变数组接口包装策略调整检测类型统一拆包为列表再取首元素超大文件内存溢出一次性 json.loadijson 流式解析或改 JSONL中文乱码编码或 BOMchardet 探测 utf-8-sig 解码深层 key 找不到结构层级不一致extract_by_key 递归搜索 jsonpath-ng最后再分享一个经验。解析不规则 JSON 时真正要避免的不是报错而是“静默出错”。字段缺了就填默认值类型不对就强转这原本没问题但如果你不记录哪些数据被改动过、哪些字段是默认值补上的后续排查会非常痛苦。我在项目里会在清洗结果里加一个_warnings字段把每次动过的字段名记下来这样既不影响下游读取又能随时回溯数据质量。这个习惯帮我省了很多次“背锅”式的查问题时间。