1. 项目概述1.1 一句话搞懂这行代码在干什么先直接说结论json.dumps(filter_dict, ensure_asciiFalse, separators(,, :))这行代码干的事就是把一个 Python 字典filter_dict序列化成 JSON 格式的字符串同时保证中文不被转义成\uXXXX并且去掉 JSON 里多余的空格让输出结果更紧凑。我在实际开发里第一次被这行代码救了一命是在做接口联调的时候。当时后端返回的数据结构比较复杂需要把筛选条件filter_dict传给下游服务结果下游同学反馈说日志里全是\u4e2d\u6587这种天书压根没法排查问题。后来把ensure_ascii改成False中文正常显示了整个排查效率直接翻倍。这行代码适合的人群非常广刚入门 Python 的爬虫新手、做 Web 开发的工程师、写自动化脚本的测试同学甚至偶尔处理数据的运维都会在某个时刻需要它。原因很简单——json模块是 Python 标准库里的常客你只要跟接口、数据文件、日志打交道就绕不开它。1.2 在动手之前先想清楚三个问题在深入拆解参数之前我建议大家先带着问题去看后面的内容这样吸收效率更高为什么默认情况下中文会变成\uXXXX这类转义字符这背后的设计逻辑是什么separators参数具体怎么控制输出格式默认值和自定义值有什么区别这行代码在实际工程里最常见的应用场景有哪些有没有什么容易踩的坑后面的内容会逐一回答这些问题。对于刚接触 Python 序列化的新手这行代码是一把很好的钥匙对于有经验的开发者它也是日常高频出现的老朋友。无论你处于哪个阶段这篇文章都会尽量讲透它的每一个细节。2. json.dumps 的核心逻辑与参数拆解2.1 从一个翻译官的视角理解 json.dumps要真正理解json.dumps我建议你把它想象成一个翻译官。Python 里的字典、列表、字符串、数字这些都是 Python 自己的数据类型但外部系统比如 JavaScript 前端、Java 后端、或者其他微服务不一定认识它们。JSON 格式就是大家约定好的通用语言。json.dumps这个翻译官的任务就是把 Python 对象翻译成 JSON 字符串。它的签名长这样json.dumps(obj, *, skipkeysFalse, ensure_asciiTrue, check_circularTrue, allow_nanTrue, clsNone, indentNone, separatorsNone, defaultNone, sort_keysFalse, **kw)注意看*后面这些参数它们都是关键字参数也就是说你必须写成ensure_asciiFalse这样的形式不能只写一个False丢进去。很多新手在这里吃过亏以为位置对就行结果直接报TypeError。这个接口的核心能力可以归纳为三点类型转换把 Python 对象转成 JSON 支持的格式。比如dict→{}list→[]str→int/float→ 数字bool→true/falseNone→null。格式控制通过indent和separators控制输出的缩进和分隔符样式。编码处理通过ensure_ascii控制非 ASCII 字符比如中文的转义方式。filter_dict就是示例里的那个 Python 字典它包含了你要序列化的数据。这个名字也透露出一个常见的使用场景——在数据筛选、过滤后把结果序列化输出。2.2 为什么要强调序列化而不是转换这里多说一句很多入门教程会把json.dumps说成字典转字符串这个说法没有错但不够准确。序列化Serialization强调的是把内存中的对象状态保存为可存储或可传输的格式而不仅仅是类型转换。反序列化Deserialization则是反向操作由json.loads完成。为什么这个概念很重要因为序列化背后涉及一个关键问题数据在传输或存储后能不能被完整、无歧义地还原。ensure_ascii和separators这两个参数本质上都是在调节序列化过程中的信息表达方式而不是简单的格式美化。比如ensure_ascii如果保持默认值True中文筛选会被表示为\u7b5b\u9009。它在信息上是等价的json.loads能正确还原但可读性极差。这就引出了下一个核心话题。3. ensure_ascii为什么中文不能直接显示3.1 默认值 True 的来历与弊端ensure_ascii的默认值是True这意味着json 模块在序列化时会把所有非 ASCII 字符都转成\uXXXX形式的转义序列。ASCII 字符集只包含 128 个字符主要覆盖英文字母、数字和常见符号。中文字符的 Unicode 码点都在\u4e00到\u9fff之间超出了 ASCII 范围。有人会问为什么 Python 要这么设计原因很现实早期网络环境和存储系统对 Unicode 的支持并不完善很多传输协议只认 ASCII 字符。把中文转成\uXXXX可以保证数据在传输过程中不出现乱码或编码错误是一种保守但安全的策略。但问题也随之而来。看看下面这个对比import json filter_dict {keyword: 数据分析, status: active} # 默认情况ensure_asciiTrue result_1 json.dumps(filter_dict) print(result_1) # 输出{keyword: \u6570\u636e\u5206\u6790, status: active} # 修改后ensure_asciiFalse result_2 json.dumps(filter_dict, ensure_asciiFalse) print(result_2) # 输出{keyword: 数据分析, status: active}看到区别了吗ensure_asciiFalse之后JSON 字符串里直接就是可读的中文。这在日志输出、接口调试、数据库存储的场景下简直太重要了。你不需要在脑子里做Unicode 码点翻译直接就能看到原始内容。3.2 什么时候非改不可什么时候无所谓根据我的项目经验ensure_asciiFalse在以下场景几乎是必选日志打印排查问题时如果日志全是\uXXXX你能疯掉。可读性直接决定了排查效率。接口响应自己开发的接口返回给前端的数据前端同学可不想先解码再看。数据落盘把 JSON 写入文件后可能用文本编辑器直接查看。转义字符会让文件失去可读性。对接第三方服务某些服务不支持\uXXXX转义或者处理转义时容易出 bug老老实实用原始中文最稳妥。但也有一些场景保持默认即可传输数据量极大的场景转义后的 ASCII 字符在某些传输协议下效率更高不过现代协议基本都是 UTF-8这个优势已经很小了。你明确知道下游系统对非 ASCII 字符处理有兼容性问题。注意ensure_asciiFalse只是把转义行为关了但输出的字符串本身是 Python 的str类型在 Python 3 里就是 Unicode 字符串。如果你要写入文件仍然需要指定正确的文件编码通常是utf-8。3.3 一个隐藏的关键细节编码落地很多新手在写完ensure_asciiFalse后往文件里写数据发现还是乱码。问题往往出在文件写入方式上。正确写法是这样import json filter_dict {keyword: 数据分析, count: 1024} # 情况一直接写入会报错或乱码 with open(output.json, w) as f: # 默认编码跟系统有关Windows 下可能是 gbk f.write(json.dumps(filter_dict, ensure_asciiFalse)) # 情况二指定 UTF-8 编码推荐 with open(output.json, w, encodingutf-8) as f: f.write(json.dumps(filter_dict, ensure_asciiFalse))encodingutf-8这个参数绝不能省。我之前在 Windows 机器上跑脚本时就踩过这个坑——不指定编码默认为gbk写出来的文件在自己的机器上打开没问题部署到 Linux 服务器上就乱码了。这类问题在日志里很难排查因为报错往往不会立刻暴露而是到下游消费者那里才爆发。4. separators细节里藏着性能与可读性的权衡4.1 默认分隔符与自定义分隔符的差异separators参数控制的是 JSON 里元素之间的分隔符格式。默认值是(, , : )注意逗号后面有个空格冒号后面也有个空格。自定义值(,, :)则是把空格全部去掉。看个直观对比import json filter_dict {name: 张三, age: 28, tags: [Python, JSON]} # 默认分隔符 default_result json.dumps(filter_dict, ensure_asciiFalse) print(default_result) # 输出{name: 张三, age: 28, tags: [Python, JSON]} # 紧凑分隔符 compact_result json.dumps(filter_dict, ensure_asciiFalse, separators(,, :)) print(compact_result) # 输出{name:张三,age:28,tags:[Python,JSON]}第二种输出明显更紧凑。每个key-value之间没有多余空格读起来像压缩过的数据。4.2 为什么有人愿意去掉空格去掉空格最直接的好处是减小数据体积。别小看这几个空格在大规模数据传输场景里它们会被反复复制、发送、解析。比如你有一个数组里面有 10 万个对象每个对象就算只省 10 个字节总容量也能省下 1MB 左右。在移动端弱网环境、物联网设备上报数据、微服务间高频调用这些场景这个差距相当可观。第二个好处是格式更规范。有团队会规定接口统一返回紧凑型 JSON不保留多余空格这样日志里的链路追踪记录更整齐也方便做字符串匹配。第三个好处藏在日志系统的存储成本里。日志数据通常按字符数计费或者按存储量归档压缩 JSON 格式可以省下成本。我在一个日活百万的项目里仅仅把默认分隔符改为紧凑格式日志存储量就下降了约 8%。这个数字背后是实打实的服务器成本。4.3 什么时候该用默认可读格式强调一点紧凑格式不总是最优解。以下场景我建议保留默认分隔符开发调试阶段你需要快速浏览数据结构人眼可读性优先。输出给外部团队看的数据文件对方可能需要手动检查或编辑。接口返回体里的 JSON如果下游有类似按 key 排序后对比的测试逻辑带空格的格式更不容易引起歧义。另外如果你需要格式化输出美观的 JSON比如把配置信息展示给用户那应该用indent4而不是纠结separators。indent和separators并不冲突可以同时使用。提示indent与separators同时设置时separators的显示效果会被indent重新格式化影响。如果先设置了indent4再设separators(,, :)输出里的换行和缩进会保留但对象内部的key-value分隔符会使用自定义的紧凑写法。这个细节挺容易让人疑惑的实测一下最好。5. 从头到尾拆解一遍完整运行过程5.1 准备一份示例数据为了把整个过程讲透我准备了一份更接近真实业务的数据——模拟一个电商平台的后台筛选条件import json from datetime import date # 模拟从用户请求中提取的筛选条件 filter_dict { supplier: 华东供应商, order_status: [pending, paid, shipped], amount_range: {min: 100, max: 9999}, is_vip: True, remark: None, deadline: 2025-06-30 }注意这里的数据类型很全字符串、列表、嵌套字典、布尔值、None、日期格式的字符串。这能帮我们观察 json 模块在不同类型上的行为差异。5.2 三种参数组合的运行结果对照我写了段测试代码把三种典型参数组合跑了一遍import json filter_dict { supplier: 华东供应商, order_status: [pending, paid, shipped], amount_range: {min: 100, max: 9999}, is_vip: True, remark: None, deadline: 2025-06-30 } print( 组合一默认参数 ) print(json.dumps(filter_dict)) print(\n 组合二仅关闭 ASCII 转义 ) print(json.dumps(filter_dict, ensure_asciiFalse)) print(\n 组合三关闭 ASCII 转义 紧凑分隔符 ) print(json.dumps(filter_dict, ensure_asciiFalse, separators(,, :)))运行结果如下 组合一默认参数 {supplier: \u534e\u4e1c\u4f9b\u5e94\u5546, order_status: [pending, paid, shipped], amount_range: {min: 100, max: 9999}, is_vip: true, remark: null, deadline: 2025-06-30} 组合二仅关闭 ASCII 转义 {supplier: 华东供应商, order_status: [pending, paid, shipped], amount_range: {min: 100, max: 9999}, is_vip: true, remark: null, deadline: 2025-06-30} 组合三关闭 ASCII 转义 紧凑分隔符 {supplier:华东供应商,order_status:[pending,paid,shipped],amount_range:{min:100,max:9999},is_vip:true,remark:null,deadline:2025-06-30}5.3 运行结果给我带来的三个复现结论看完结果有几个细节值得写进笔记第一None变成了null。这是 JSON 的标准格式。Python 里的None在 JavaScript / Java 体系里对应nulljson 模块会做自动转换。第二True变成了true。注意大小写。JSON 标准里布尔值是小写true/falsePython 里是大写True/False。序列化会自动转换反序列化时也会自动转回。第三嵌套字典也能被正确处理。amount_range这个嵌套结构在两种separators设置下都能正常输出说明 json 模块是递归遍历整个数据结构的。这保证了多层级的数据也能无损序列化。另外我们注意到输入里的deadline的值是字符串2025-06-30不是 Python 的datetime对象。如果你直接传date.today()这种对象给json.dumps会报TypeError: Object of type date is not JSON serializable。这是个非常常见的坑后面第 7 部分会专门讲。6. 实际业务落地filter_dict 在工程里的三种典型用法6.1 用法一把筛选条件序列化后写入日志在真实的后端系统里用户每次发起列表查询都会带上一堆筛选条件。为了审计和排查问题我们需要把筛选条件打进日志。使用ensure_asciiFalse后日志内容对运维和开发都非常友好import json import logging logger logging.getLogger(__name__) def search_orders(filter_dict): # 记录请求参数方便后期排查 logger.info(Search orders with filter: %s, json.dumps(filter_dict, ensure_asciiFalse, separators(,, :))) # 省略后续查询逻辑...在 ELK 这类日志系统里如果日志里是\u534e\u4e1c这种内容搜索华东两个字根本搜不到。保持中文原样输出直接就能在 Kibana 里做全文检索排查问题的体验完全不一样。6.2 用法二构造 API 请求体当你的 Python 服务需要调用下游 HTTP 接口时请求体几乎都是 JSON 字符串。紧凑格式能减少网络传输字节数import json import requests def call_analytic_service(filter_dict): url https://api.example.com/v1/analytics/query payload json.dumps(filter_dict, ensure_asciiFalse, separators(,, :)) headers {Content-Type: application/json} resp requests.post(url, datapayload, headersheaders) print(resp.json())这里有个小建议requests库的json参数会自动帮你做序列化但它默认用的是ensure_asciiTrue。如果你传的是纯英文字段还好如果有中文最好手动用json.dumps先序列化再放进data这样能完全掌控序列化行为。6.3 用法三将数据写入文件做离线分析数据分析场景里经常要把用户筛选条件保存下来供后续训练模型或做统计报表。紧凑格式在这里既省空间又保留可读性import json from pathlib import Path def save_filter_snapshot(filter_dict, file_path): data json.dumps(filter_dict, ensure_asciiFalse, separators(,, :), sort_keysTrue) Path(file_path).write_text(data, encodingutf-8)sort_keysTrue是我额外加的参数。它能保证字典里的 key 按字母序排列这样同一份数据不管生成顺序如何最终落地文件的内容都一样。这在做数据比对、增量同步时非常有用——重复生成的 JSON 文件可以直接用 diff 工具对比差异。6.4 使用 JSONL 格式时的独特优势顺便说一个工程里容易被忽略的好用技巧当你要把大量 JSON 逐行写入文件JSONL 格式时separators(,, :)几乎是标配。每行一个 JSON 对象用紧凑格式能保证行内不换行方便逐行读取和处理import json with open(events.jsonl, w, encodingutf-8) as f: for event in events: line json.dumps(event, ensure_asciiFalse, separators(,, :)) f.write(line \n)如果保留默认的separatorsJSON 里会有空格虽然不影响行解析但文件体积更大。JSONL 配合紧凑格式是处理海量事件日志的推荐组合。7. 常见问题与排查技巧实录7.1 传入非基础类型数据导致 TypeError报错信息TypeError: Object of type date is not JSON serializable原因json.dumps默认只能处理dict、list、str、int、float、bool、NoneType。碰到datetime、Decimal、set等类型会直接报错。解决方案给default参数传一个转换函数import json from datetime import datetime, date def json_default(obj): if isinstance(obj, (datetime, date)): return obj.isoformat() if isinstance(obj, set): return list(obj) if isinstance(obj, Decimal): return float(obj) raise TypeError(fType {type(obj)} not serializable) data {created_at: datetime.now(), tags: {a, b}} print(json.dumps(data, defaultjson_default, ensure_asciiFalse))default参数的作用是当遇到无法序列化的对象时调用它来做自定义转换。把datetime转成 ISO 格式字符串是最常见的做法。7.2 中文写入文件后变乱码现象ensure_asciiFalse已经设置了控制台打印正常但用记事本打开 JSON 文件还是乱码。原因文件写入时指定了系统默认编码Windows 下是gbk或者终端工具用错了解码方式。解决方案写入文件时必须显式指定encodingutf-8import json # 错误示范 with open(data.json, w) as f: f.write(json.dumps({region: 华东}, ensure_asciiFalse)) # 正确示范 with open(data.json, w, encodingutf-8) as f: f.write(json.dumps({region: 华东}, ensure_asciiFalse))另外读取时同样需要指定encodingutf-8保持编解码一致。7.3 排序不稳定明明同一份数据输出却不同现象两次执行json.dumps同一个字典输出结果的 key 顺序不同。原因Python 3.7 之前字典不保证顺序Python 3.7 字典默认保持插入顺序但插入顺序本身可能不同。如果你的程序里字典是通过不同路径构建的顺序自然不同。解决方案使用sort_keysTrue强制按键排序。这不仅让输出更稳定还能让 JSON 在文本对比工具中更容易 diff。print(json.dumps(filter_dict, sort_keysTrue, ensure_asciiFalse, separators(,, :)))7.4 浮点数精度丢失现象序列化和反序列化后浮点数精度发生变化。比如0.1 0.2的结果0.30000000000000004。原因这是 IEEE 754 浮点数表示法的固有问题不是 json 模块的 bug。解决方案对精度要求高的业务用Decimal并在default函数中转为字符串from decimal import Decimal def json_default(obj): if isinstance(obj, Decimal): return str(obj) # 转为字符串保留原始精度 raise TypeError(...) data {price: Decimal(199.90)} print(json.dumps(data, defaultjson_default))7.5 常见问题速查表问题类型典型现象核心处理方案中文被转义输出\uXXXX不可读设置ensure_asciiFalse文件乱码打开文件后中文异常写入时指定encodingutf-8非序列化类型TypeError: Object of type X使用default参数自定义转换key 顺序不稳定多次输出顺序不同设置sort_keysTrue输出体积过大JSON 字符串很长使用separators(,, :)紧凑模式浮点精度丢失小数位异常用Decimal结合default转字符串7.6 关于 ensure_ascii 的一个反向思考有些开发者会担心ensure_asciiFalse输出的中文在网络上传输会乱码。其实这个担心是多余的——UTF-8 编码的中文在 HTTP 协议里完全正常。只要发送端和接收端都使用 UTF-8就不会有问题。真正导致乱码的往往是编码声明不一致比如一端用 GBK另一端用 UTF-8这时候不管你ensure_ascii设成什么都会出问题。所以我的建议是在团队内部统一使用ensure_asciiFalse并且统一字符编码为 UTF-8。这样调试和日志的可读性都能得到保障且不会带来传输副作用。8. 写在最后的一点实操心得做 Python 开发这些年我最大的体会是真正影响开发效率的往往不是那些高大上的框架而是这些最基础、最常用的接口到底用得好不好。json.dumps这行代码看起来简单但如果能把ensure_ascii、separators、sort_keys、default这几个参数理解透彻并灵活组合在日常项目里能省下非常多的时间。我个人平时还会把下面这个小工具函数放在项目公共模块里用它来统一项目里的 JSON 序列化行为import json def dump_json(data, *, ensure_asciiTrue, compactFalse, sort_keysFalse): if compact: separators (,, :) else: separators None return json.dumps(data, ensure_asciiensure_ascii, separatorsseparators, sort_keyssort_keys)这样团队里每个人调用时只要显式声明自己想要的格式其他细节由函数处理不容易出偏差。最后再分享一个小技巧在调试输出字典内容时可以用pprint模块搭配json.dumps先序列化再格式化打印效果比直接print一个大字典清晰得多。这个方法帮我在排查复杂嵌套数据时节省了不少眼睛疲劳度。
