直接用 json.dump() 报错是因为其默认只支持 str、int、float、list、dict、bool 和 None,遇到 datetime、Decimal 等非标类型即抛 TypeError;需通过 default 函数、orjson 或 pydantic 预处理为原生类型。

为什么直接用 json.dump() 会报 TypeError: Object of type XXX is not JSON serializable
多级嵌套字典里常混入 datetime、Decimal、numpy.int64、自定义类实例等非标准类型,json.dump() 默认只认 str、int、float、list、dict、bool 和 None。遇到不支持的类型就立刻抛错,不会尝试递归转换。
常见错误现象:写入含 datetime.now() 的字典时卡在 TypeError: Object of type datetime is not JSON serializable;或 pandas DataFrame 转成 dict 后仍有 numpy.float64 字段导致失败。
- 不要依赖
default参数硬写类型判断逻辑——容易漏判嵌套深层的非标类型 - 避免用
str(obj)粗暴转字符串——丢失语义,且可能引入非法 JSON 字符(如换行、未转义引号) - 优先把数据“清洗”成纯 Python 原生结构,而不是让 JSON 库临时适配
用 json.dumps() + default 参数做轻量级序列化
适用于嵌套不深、非标类型种类少(比如只有 datetime 和 Decimal)的场景。关键是写一个健壮的 default 函数,能递归处理任意层级的值。
一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。
import json
from datetime import datetime
from decimal import Decimal
def json_friendly(obj):
if isinstance(obj, datetime):
return obj.isoformat()
elif isinstance(obj, Decimal):
return float(obj)
elif hasattr(obj, '__dict__'):
return obj.__dict__
raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
data = {"time": datetime.now(), "price": Decimal("29.99"), "meta": {"id": 123}}
with open("output.json", "w", encoding="utf-8") as f:
json.dump(data, f, default=json_friendly, indent=2)
-
default函数必须只返回 JSON 可序列化的类型,不能返回自定义对象或 bytes - 对
hasattr(obj, '__dict__')的 fallback 要谨慎——它可能暴露私有属性或引发无限递归(如循环引用),仅作兜底,不建议用于生产环境复杂对象 - 如果嵌套中有
bytes,需额外加elif isinstance(obj, bytes): return obj.decode("utf-8")
用 orjson 替代标准库,省去手动处理
orjson 是高性能替代方案,原生支持 datetime、dataclass、numpy 类型,序列化速度比标准库快 3–5 倍,且默认输出 UTF-8 bytes,适合写入文件时直接调用 .decode() 或用 open(..., "wb")。
立即学习“Python免费学习笔记(深入)”;
import orjson
data = {"created": datetime.now(), "score": np.float64(95.5)}
with open("output.json", "wb") as f:
f.write(orjson.dumps(data, option=orjson.OPT_INDENT_2))
- 安装:
pip install orjson;注意 Windows 上需预装 Visual Studio Build Tools -
orjson.dumps()返回bytes,不能直接传给以文本模式打开的文件(会报TypeError: a bytes-like object is required),务必用"wb"模式 - 不支持
default参数,所以对自定义类仍需提前转成 dict;但它对常见科学计算类型(np.int64,pd.Timestamp)开箱即用
真正健壮的做法:先用 pydantic 模型做数据标准化
当你的嵌套字典来自 API 响应、数据库查询或用户输入,且结构相对固定时,定义 pydantic.BaseModel 子类是最省心的长期方案。它自动完成类型转换、嵌套校验和 JSON 序列化。
from pydantic import BaseModel, Field
from datetime import datetime
from typing import List, Optional
class User(BaseModel):
id: int
name: str
joined_at: datetime
tags: List[str]
class Report(BaseModel):
title: str
author: User
generated: datetime
data = Report(
title="Q3 Summary",
author=User(id=101, name="Alice", joined_at=datetime(2022, 3, 15), tags=["admin"]),
generated=datetime.now()
)
with open("report.json", "w") as f:
f.write(data.json(indent=2))
- 即使输入是普通 dict(比如
Report(**raw_dict)),pydantic 也会把joined_at字符串自动转成datetime,再序列化为 ISO 格式 - 字段缺失、类型错误会在初始化时抛出清晰异常,而不是等到写 JSON 才崩
- 注意
data.json()输出的是字符串,用文本模式写文件即可;若需 bytes,用data.json().encode("utf-8")

















