python 学习: dataclasses_json的使用-程序员充电站

想要系统学习 Python 中dataclasses_json库的使用方法，核心是掌握如何利用这个库实现 Python 数据类（dataclass）与 JSON 格式的高效、类型安全的序列化（转 JSON）和反序列化（解析 JSON），替代原生json模块需要手动处理类型转换的繁琐操作。

一、核心概念与前置准备

1. 什么是 dataclasses_json？

dataclasses_json是 Python 3.7 + 的第三方库，是对标准库dataclasses的扩展，专门解决数据类 ↔ JSON的转换问题：

序列化（Serialize）：将@dataclass装饰的类实例 → JSON 字符串 / 字典
反序列化（Deserialize）：将 JSON 字符串 / 字典 →@dataclass装饰的类实例
优势：自动处理基础类型转换（如int/str/bool），支持嵌套数据类、可选类型、自定义字段映射等，无需手动写to_dict()/from_dict()方法。

2. 安装依赖

bash

pip install dataclasses-json # 注意库名带短横线 # 若使用Python 3.6，需额外安装dataclasses：pip install dataclasses

二、基础使用（核心示例）

1. 最简示例：基础类型转换

python

from dataclasses import dataclass from dataclasses_json import dataclass_json # 核心装饰器 # 1. 定义带JSON转换能力的数据类 @dataclass_json # 必须放在@dataclass上方/下方（推荐上方） @dataclass class Product: """商品数据类""" id: int # 基础类型：整数 name: str # 基础类型：字符串 price: float # 基础类型：浮点数 is_in_stock: bool# 基础类型：布尔值 # 2. 序列化：数据类实例 → JSON字符串/字典 # 创建实例 product = Product(id=1001, name="手机", price=2999.99, is_in_stock=True) # 转JSON字符串 json_str = product.to_json() print("JSON字符串：", json_str) # 输出：{"id":1001,"name":"手机","price":2999.99,"is_in_stock":true} # 转Python字典 json_dict = product.to_dict() print("Python字典：", json_dict) # 输出：{'id': 1001, 'name': '手机', 'price': 2999.99, 'is_in_stock': True} # 3. 反序列化：JSON → 数据类实例 # 从JSON字符串解析 product_from_json = Product.from_json(json_str) print("从JSON解析的实例：", product_from_json) # 输出：Product(id=1001, name='手机', price=2999.99, is_in_stock=True) # 从字典解析 product_from_dict = Product.from_dict(json_dict) print("从字典解析的实例：", product_from_dict) # 输出：Product(id=1001, name='手机', price=2999.99, is_in_stock=True)

2. 关键装饰器说明

@dataclass_json：为数据类注入to_json()/from_json()/to_dict()/from_dict()四个核心方法，是使用该库的核心。
装饰器顺序：@dataclass_json可放在@dataclass上方或下方，推荐放在上方以明确扩展关系。

三、进阶用法

1. 自定义字段映射（JSON 字段名≠类属性名）

实际场景中，JSON 的字段名（如下划线 / 驼峰）可能和 Python 类属性名不一致，可通过field配置映射：

python

from dataclasses import dataclass, field from dataclasses_json import dataclass_json, LetterCase, config @dataclass_json @dataclass class User: user_id: int = field(metadata=config(field_name="userId")) # JSON字段名：userId user_name: str = field(metadata=config(field_name="userName")) # JSON字段名：userName age: int # 序列化：类属性 → JSON驼峰字段 user = User(user_id=1, user_name="张三", age=20) print(user.to_json()) # 输出：{"userId":1,"userName":"张三","age":20} # 反序列化：JSON驼峰字段 → 类属性 json_str = '{"userId":2,"userName":"李四","age":25}' user2 = User.from_json(json_str) print(user2) # 输出：User(user_id=2, user_name='李四', age=25)

2. 处理嵌套数据类

支持多层嵌套的数据类转换，只需确保嵌套的类也被@dataclass_json装饰：

python

@dataclass_json @dataclass class Address: province: str city: str @dataclass_json @dataclass class Order: order_id: str user: User # 嵌套User类 address: Address # 嵌套Address类 total_amount: float # 构建嵌套实例 user = User(user_id=1, user_name="张三", age=20) address = Address(province="广东省", city="深圳市") order = Order(order_id="OD123456", user=user, address=address, total_amount=5999.99) # 序列化 print(order.to_json(indent=2)) # indent=2：格式化输出JSON # 输出： # { # "order_id": "OD123456", # "user": { # "userId": 1, # "userName": "张三", # "age": 20 # }, # "address": { # "province": "广东省", # "city": "深圳市" # }, # "total_amount": 5999.99 # } # 反序列化 json_str = order.to_json() order2 = Order.from_json(json_str) print(order2.address.city) # 输出：深圳市

3. 处理可选字段（Optional 类型）

支持Optional（可选）类型，JSON 中缺失该字段时会自动赋值为None：

python

from typing import Optional @dataclass_json @dataclass class Book: id: int title: str author: Optional[str] = None # 可选字段，默认None # JSON缺失author字段 json_str = '{"id": 101, "title": "Python入门"}' book = Book.from_json(json_str) print(book) # 输出：Book(id=101, title='Python入门', author=None) # JSON包含author字段 json_str2 = '{"id": 102, "title": "Java入门", "author": "李四"}' book2 = Book.from_json(json_str2) print(book2) # 输出：Book(id=102, title='Java入门', author='李四')

4. 自定义类型转换（如日期类型）

默认不支持datetime等复杂类型，需自定义序列化 / 反序列化逻辑：

python

from datetime import datetime from dataclasses_json import config from typing import Optional # 定义日期转换函数 def date_to_str(dt: Optional[datetime]) -> Optional[str]: """datetime → 字符串（格式：%Y-%m-%d %H:%M:%S）""" return dt.strftime("%Y-%m-%d %H:%M:%S") if dt else None def str_to_date(s: Optional[str]) -> Optional[datetime]: """字符串 → datetime""" return datetime.strptime(s, "%Y-%m-%d %H:%M:%S") if s else None @dataclass_json @dataclass class Article: id: int title: str create_time: Optional[datetime] = field( metadata=config( encoder=date_to_str, # 序列化：datetime→字符串 decoder=str_to_date # 反序列化：字符串→datetime ), default=None ) # 序列化 article = Article(id=1, title="dataclasses_json教程", create_time=datetime.now()) print(article.to_json()) # 输出示例：{"id":1,"title":"dataclasses_json教程","create_time":"2026-01-12 15:30:00"} # 反序列化 json_str = '{"id":2,"title":"Python教程","create_time":"2026-01-01 10:00:00"}' article2 = Article.from_json(json_str) print(article2.create_time) # 输出：2026-01-01 10:00:00 print(type(article2.create_time)) # 输出：<class 'datetime.datetime'>

四、常见问题与注意事项

类型匹配：反序列化时 JSON 字段类型必须与类属性类型匹配（如 JSON 的"id":"1001"无法转int类型的id），否则会抛出类型错误。
默认值：可选字段建议设置默认值（如None），避免 JSON 缺失字段时反序列化失败。
空值处理：JSON 中的null会被反序列化为 Python 的None，需确保类属性支持None（通过Optional）。

总结

dataclasses_json的核心是@dataclass_json装饰器，为数据类注入to_json()/from_json()等方法，实现数据类与 JSON 的一键转换；
支持自定义字段映射、嵌套数据类、可选类型，通过metadata=config()可扩展复杂类型（如日期）的转换逻辑；
相比原生json模块，dataclasses_json更类型安全、代码更简洁，是处理结构化 JSON 数据的首选方案。