本文详解如何使用 pandas 和标准 json 模块，将多个 dataframe 转换为具有自定义键名的嵌套 json 对象，并写入格式化文件，避免常见序列化错误。
本文详解如何使用 pandas 和标准 json 模块，将多个 dataframe 转换为具有自定义键名的嵌套 json 对象，并写入格式化文件，避免常见序列化错误。
在数据处理流程中，常需将多个经过筛选或聚合的 pandas DataFrame 合并输出为一个结构清晰、语义明确的 JSON 文件（例如用于 API 响应、前端配置或跨系统数据交换）。但直接调用 df.to_json() 仅生成扁平数组字符串，无法满足嵌套对象（如 { "StatusTimes": [...], "DtCount": [...] }）的需求；而盲目使用 json.dumps() 对 DataFrame 对象操作则会触发 TypeError: Object of type DataFrame is not JSON serializable。
正确做法是：先将各 DataFrame 转为 Python 原生列表（含字典），再组装为嵌套字典结构，最后用 json.dump() 或 json.dumps() 序列化。核心在于使用 DataFrame.to_dict(orient='records') —— 它将每行转为一个字典，整体返回 list[dict]，完全兼容 JSON 标准。
以下为完整实现示例：
import pandas as pd
import json
# 示例数据（实际中来自你的过滤/计算逻辑）
df1 = pd.DataFrame([
{"time": 1677287760000, "x": 0.001, "y": 0.001, "z": 0.0},
{"time": 1677632400000, "x": 0.0, "y": 0.0, "z": 0.0},
{"time": 1677636000000, "x": 0.0, "y": 0.0, "z": 0.0},
{"time": 1677639600000, "x": 0.0, "y": 0.0, "z": 0.0}
])
df2 = pd.DataFrame([
{"dt": 20, "count": 6},
{"dt": 23, "count": 9},
{"dt": 11, "count": 7},
{"dt": 2, "count": 16},
{"dt": 17, "count": 1},
{"dt": 20, "count": 6}
])
# ✅ 正确构建嵌套 JSON 结构
nested_data = {
"StatusTimes": df1.to_dict(orient="records"),
"DtCount": df2.to_dict(orient="records")
}
# 方式一：直接写入文件（紧凑格式）
with open("output.json", "w", encoding="utf-8") as f:
json.dump(nested_data, f)
# 方式二：写入带缩进的美观格式（推荐调试与交付）
with open("output_pretty.json", "w", encoding="utf-8") as f:
json.dump(nested_data, f, indent=4, ensure_ascii=False)执行后，output_pretty.json 将生成符合预期的嵌套结构，且支持中文字符（ensure_ascii=False 防止 Unicode 转义）。
立即学习“Python免费学习笔记（深入）”；
⚠️ 关键注意事项：
- ❌ 不要对 DataFrame 对象直接调用 json.dumps(df) —— 必报错；
- ✅ 务必使用 to_dict(orient='records')，而非 'dict'、'list' 等其他 orient 参数（它们返回非 JSON 兼容结构）；
- 若 DataFrame 含 datetime、numpy 类型（如 np.int64），建议预处理转换为原生类型：
df1 = df1.astype({col: 'int64' for col in df1.select_dtypes('number').columns}).astype('int64') # 或更通用：df1 = df1.replace({np.nan: None}).applymap(lambda x: int(x) if isinstance(x, (np.integer, float)) and x.is_integer() else x) - 对于大型 DataFrame，可考虑流式写入或分块处理以节省内存，但本方案在万级记录内性能优异。
总结：构建嵌套 JSON 的本质是“数据结构对齐”——确保输入为纯 Python 类型（list + dict + str/int/float/None），再交由 json 模块安全序列化。掌握 to_dict('records') 这一桥梁方法，即可灵活组合任意数量的 DataFrame，生成符合业务语义的标准化 JSON 输出。
