使用psycopg2的JsonOut方法时如何解决"TypeError: dict is not a JSON serializable"错误

问题场景分析

在使用Python的psycopg2库与PostgreSQL数据库交互时，JsonOut方法是将数据库中的JSON/JSONB类型数据转换为Python对象的重要接口。一个常见错误是当尝试处理包含非标准JSON类型的字典数据时，系统抛出TypeError: dict is not a JSON serializable异常。这种情况通常发生在以下场景：

字典中包含Python特有的数据类型（如datetime对象）
自定义对象未经序列化直接传入
嵌套数据结构包含不可序列化元素

根本原因探究

PostgreSQL的JSONB类型要求严格遵循JSON规范，而Python字典可能包含以下不符合规范的元素：

problem_dict = {
    'date': datetime.now(),  # 日期时间对象
    'binary': b'some_bytes',  # 字节串
    'custom': CustomClass()   # 自定义类实例
}

五种解决方案对比

1. 使用默认的json模块序列化

通过json.dumps()预转换数据，但需要处理特殊类型：

import json
from datetime import datetime

def default_serializer(obj):
    if isinstance(obj, datetime):
        return obj.isoformat()
    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")

safe_data = json.dumps(problem_dict, default=default_serializer)

2. 使用psycopg2.extras.Json包装

psycopg2提供的专用包装器可自动处理常见类型：

from psycopg2.extras import Json

cursor.execute(
    "INSERT INTO table (json_data) VALUES (%s)",
    (Json(problem_dict),)
)

3. 实现自定义JSON编码器

继承json.JSONEncoder创建更强大的序列化逻辑：

class ExtendedEncoder(json.JSONEncoder):
    def default(self, obj):
        # 添加自定义序列化逻辑
        if hasattr(obj, '__json__'):
            return obj.__json__()
        return super().default(obj)

4. 数据库端类型转换

在SQL语句中直接使用PostgreSQL的类型转换函数：

INSERT INTO table (json_data) 
VALUES (to_jsonb(%s::text))

5. 数据预处理策略

建立数据清洗管道，确保入库前完成类型转换：

def sanitize_json(data):
    # 递归处理嵌套结构
    if isinstance(data, dict):
        return {k: sanitize_json(v) for k,v in data.items()}
    # 添加特定类型处理
    elif isinstance(data, datetime):
        return data.isoformat()
    return data

性能优化建议

方法	执行速度	内存消耗	适用场景
json.dumps()	中等	低	简单数据结构
psycopg2.extras.Json	快	中等	标准类型混合数据
自定义编码器	慢	高	复杂业务对象

错误预防体系

建立多层防御机制可显著降低运行时错误：

单元测试：验证所有可能的输入类型
类型注解：使用mypy进行静态检查
数据验证：Pydantic模型校验入库数据
监控报警：捕获生产环境序列化异常