Python dataclass 完全指南：数据类从入门到精通 | Python 进阶核心知识

1
# ❌ 传统写法：大量样板代码
2
class UserOld:
3
    def __init__(self, name, age, email):
4
        self.name = name
5
        self.age = age
6
        self.email = email
7

8
    def __repr__(self):
9
        return f"UserOld(name={self.name!r}, age={self.age!r}, email={self.email!r})"
10

11
    def __eq__(self, other):
12
        if not isinstance(other, UserOld):
13
            return NotImplemented
14
        return (self.name, self.age, self.email) == (other.name, other.age, other.email)
15

16
# ✅ dataclass 写法：自动生成上述方法
17
from dataclasses import dataclass
18

19
@dataclass
20
class User:
21
    name: str
22
    age: int
23
    email: str
24

25
# 使用
26
user1 = User("Alice", 30, "alice@example.com")
27
user2 = User("Alice", 30, "alice@example.com")
28

29
print(user1)        # User(name='Alice', age=30, email='alice@example.com')
30
print(user1 == user2)  # True（自动生成 __eq__）

1
from dataclasses import dataclass
2

3
@dataclass(
4
    init=True,          # 生成 __init__（默认 True）
5
    repr=True,          # 生成 __repr__（默认 True）
6
    eq=True,            # 生成 __eq__（默认 True）
7
    order=False,        # 生成 __lt__/__le__/__gt__/__ge__（默认 False）
8
    unsafe_hash=False,  # 生成 __hash__（默认 False）
9
    frozen=False,       # 不可变（默认 False）
10
    match_args=True,    # 生成 __match_args__（Python 3.10+，默认 True）
11
    slots=False,        # 使用 __slots__（Python 3.10+，默认 False）
12
    kw_only=False,      # 关键字参数模式（Python 3.10+，默认 False）
13
)
14
class Config:
15
    debug: bool = False
16
    timeout: int = 30

1
from dataclasses import dataclass
2

3
@dataclass
4
class Server:
5
    host: str = "localhost"
6
    port: int = 8080
7
    debug: bool = False
8
    max_connections: int = 100
9

10
# 使用默认值
11
server = Server()
12
print(server)  # Server(host='localhost', port=8080, debug=False, max_connections=100)
13

14
# 部分赋值
15
server = Server(port=3000, debug=True)
16
print(server)  # Server(host='localhost', port=3000, debug=True, max_connections=100)

1
from dataclasses import dataclass, field
2

3
# ❌ 错误：可变默认值
4
# @dataclass
5
# class BadExample:
6
#     items: list = []  # ValueError: mutable default not allowed
7

8
# ✅ 正确：使用 default_factory
9
@dataclass
10
class GoodExample:
11
    items: list = field(default_factory=list)       # 每次创建新列表
12
    tags: set = field(default_factory=set)           # 每次创建新集合
13
    metadata: dict = field(default_factory=dict)    # 每次创建新字典
14

15
obj1 = GoodExample()
16
obj2 = GoodExample()
17
obj1.items.append("item1")
18

19
print(obj1.items)  # ['item1']
20
print(obj2.items)  # []  （独立的新列表）

1
from dataclasses import dataclass, field
2

3
@dataclass
4
class Product:
5
    name: str
6
    price: float
7

8
    # default：不可变默认值
9
    category: str = "general"
10

11
    # default_factory：可变默认值
12
    tags: list = field(default_factory=list)
13

14
    # init：是否在 __init__ 中包含
15
    internal_id: int = field(default=0, init=False)
16

17
    # repr：是否在 __repr__ 中显示
18
    secret_key: str = field(default="", repr=False)
19

20
    # compare：是否参与比较
21
    created_at: str = field(default="", compare=False)
22

23
    # metadata：自定义元数据
24
    description: str = field(
25
        default="",
26
        metadata={"max_length": 500, "description": "产品描述"}
27
    )
28

29
# 使用
30
product = Product(name="Laptop", price=999.99, tags=["electronics"])
31
print(product)
32
# Product(name='Laptop', price=999.99, category='general', tags=['electronics'],
33
#         internal_id=0, created_at='', description='')
34

35
# 访问 metadata
36
fields = Product.__dataclass_fields__
37
print(fields['description'].metadata)
38
# {'max_length': 500, 'description': '产品描述'}

1
from dataclasses import dataclass, field, InitVar
2

3
@dataclass
4
class DatabaseConfig:
5
    host: str
6
    port: int
7
    # InitVar：仅用于 __init__ 传递，不存储为实例属性
8
    password: InitVar[str] = ""
9

10
    # 连接字符串在 __post_init__ 中生成
11
    connection_string: str = field(init=False)
12

13
    def __post_init__(self, password: str):
14
        """__init__ 执行后调用"""
15
        if password:
16
            self.connection_string = f"postgresql://{self.host}:{self.port}?password={password}"
17
        else:
18
            self.connection_string = f"postgresql://{self.host}:{self.port}"
19

20
# 使用
21
db = DatabaseConfig("localhost", 5432, password="secret123")
22
print(db.connection_string)
23
# postgresql://localhost:5432?password=secret123
24

25
# password 不存储为实例属性
26
print(hasattr(db, 'password'))  # False

1
from dataclasses import dataclass
2

3
@dataclass(frozen=True)
4
class Point:
5
    x: float
6
    y: float
7

8
p = Point(1.0, 2.0)
9

10
# 不可修改
11
try:
12
    p.x = 3.0  # FrozenInstanceError
13
except Exception as e:
14
    print(f"Error: {e}")
15

16
# 可以比较和哈希（作为字典键或集合元素）
17
p1 = Point(1.0, 2.0)
18
p2 = Point(1.0, 2.0)
19
print(p1 == p2)  # True
20
print(hash(p1))  # 可哈希
21

22
# 作为字典键
23
points = {p1: "origin"}
24
print(points[Point(1.0, 2.0)])  # "origin"

1
from dataclasses import dataclass
2

3
@dataclass(frozen=True)
4
class Color:
5
    r: int
6
    g: int
7
    b: int
8

9
    def to_hex(self) -> str:
10
        return f"#{self.r:02x}{self.g:02x}{self.b:02x}"
11

12
@dataclass(frozen=True)
13
class Config:
14
    host: str
15
    port: int
16
    debug: bool = False
17

18
    @property
19
    def url(self) -> str:
20
        return f"http://{self.host}:{self.port}"
21

22
# 不可变配置对象
23
config = Config("example.com", 443)
24
print(config.url)  # http://example.com:443
25

26
# 颜色对象
27
red = Color(255, 0, 0)
28
print(red.to_hex())  # #ff0000

1
from dataclasses import dataclass
2

3
@dataclass(order=True)
4
class Student:
5
    # 按分数排序（降序需要反向）
6
    score: float
7
    name: str
8
    age: int = 18
9

10
students = [
11
    Student(85.5, "Alice"),
12
    Student(92.0, "Bob"),
13
    Student(78.0, "Charlie", 20),
14
    Student(92.0, "David", 19),
15
]
16

17
# 排序
18
sorted_students = sorted(students)
19
for s in sorted_students:
20
    print(s)
21
# Student(score=78.0, name='Charlie', age=20)
22
# Student(score=85.5, name='Alice', age=18)
23
# Student(score=92.0, name='Bob', age=18)    # 分数相同时按 name 排序
24
# Student(score=92.0, name='David', age=19)
25

26
# 比较
27
s1 = Student(90.0, "Alice")
28
s2 = Student(85.0, "Bob")
29
print(s1 > s2)  # True（按 score 比较）

1
from dataclasses import dataclass, field
2

3
@dataclass(order=True)
4
class Priority:
5
    # 只按 priority 排序
6
    priority: int
7
    name: str = field(compare=False)
8
    description: str = field(compare=False)
9

10
tasks = [
11
    Priority(3, "Low", "可选任务"),
12
    Priority(1, "High", "紧急任务"),
13
    Priority(2, "Medium", "普通任务"),
14
]
15

16
for task in sorted(tasks):
17
    print(f"{task.priority}: {task.name}")
18
# 1: High
19
# 2: Medium
20
# 3: Low

1
from dataclasses import dataclass, field
2

3
@dataclass
4
class BaseUser:
5
    id: int
6
    name: str
7
    email: str
8

9
@dataclass
10
class AdminUser(BaseUser):
11
    role: str = "admin"
12
    permissions: list = field(default_factory=list)
13

14
@dataclass
15
class GuestUser(BaseUser):
16
    expires_at: str = ""
17

18
# 使用
19
admin = AdminUser(
20
    id=1,
21
    name="Alice",
22
    email="alice@example.com",
23
    permissions=["read", "write", "delete"]
24
)
25
print(admin)
26
# AdminUser(id=1, name='Alice', email='alice@example.com',
27
#           role='admin', permissions=['read', 'write', 'delete'])
28

29
guest = GuestUser(id=2, name="Bob", email="bob@example.com", expires_at="2026-12-31")
30
print(guest)
31
# GuestUser(id=2, name='Bob', email='bob@example.com', expires_at='2026-12-31')

1
from dataclasses import dataclass
2

3
@dataclass
4
class Animal:
5
    name: str
6
    age: int = 0
7

8
@dataclass
9
class Dog(Animal):
10
    # 子类新增字段必须有默认值（如果父类字段有默认值）
11
    breed: str = "Unknown"
12
    tricks: list = field(default_factory=list)
13

14
# 正确：所有参数都有默认值
15
dog = Dog("Buddy")
16
print(dog)  # Dog(name='Buddy', age=0, breed='Unknown', tricks=[])
17

18
# 带所有参数
19
dog = Dog("Buddy", 3, "Golden Retriever", ["sit", "roll"])
20
print(dog)

1
from dataclasses import dataclass, field
2
from typing import List
3

4
@dataclass
5
class Address:
6
    street: str
7
    city: str
8
    zip_code: str
9

10
@dataclass
11
class Contact:
12
    phone: str
13
    email: str
14

15
@dataclass
16
class Person:
17
    name: str
18
    age: int
19
    address: Address        # 组合
20
    contact: Contact        # 组合
21
    tags: List[str] = field(default_factory=list)
22

23
# 使用
24
person = Person(
25
    name="Alice",
26
    age=30,
27
    address=Address("123 Main St", "New York", "10001"),
28
    contact=Contact("555-1234", "alice@example.com"),
29
    tags=["friend", "colleague"]
30
)
31

32
print(person.address.city)   # New York
33
print(person.contact.email)  # alice@example.com

1
from dataclasses import dataclass
2
import sys
3

4
# 传统 dataclass
5
@dataclass
6
class PointDict:
7
    x: float
8
    y: float
9

10
# slots 优化
11
@dataclass(slots=True)
12
class PointSlots:
13
    x: float
14
    y: float
15

16
# 内存对比
17
p1 = PointDict(1.0, 2.0)
18
p2 = PointSlots(1.0, 2.0)
19

20
print(sys.getsizeof(p1.__dict__))  # ~104 bytes（字典开销）
21
# PointSlots 没有 __dict__
22
print(hasattr(p2, '__dict__'))  # False
23

24
# slots 优势：
25
# 1. 更低的内存占用（约 40-50%）
26
# 2. 更快的属性访问
27
# 3. 防止动态添加属性

1
import timeit
2

3
# 访问性能对比
4
p_dict = PointDict(1.0, 2.0)
5
p_slots = PointSlots(1.0, 2.0)
6

7
time_dict = timeit.timeit(lambda: p_dict.x, number=10_000_000)
8
time_slots = timeit.timeit(lambda: p_slots.x, number=10_000_000)
9

10
print(f"Dict:  {time_dict:.3f}s")
11
print(f"Slots: {time_slots:.3f}s")
12
print(f"Speedup: {time_dict / time_slots:.2f}x")
13
# Slots 通常快 20-30%

1
from dataclasses import dataclass, asdict, astuple
2
import json
3

4
@dataclass
5
class User:
6
    name: str
7
    age: int
8
    email: str
9
    tags: list = None
10

11
user = User("Alice", 30, "alice@example.com", ["admin", "user"])
12

13
# 转字典
14
user_dict = asdict(user)
15
print(user_dict)
16
# {'name': 'Alice', 'age': 30, 'email': 'alice@example.com', 'tags': ['admin', 'user']}
17

18
# 转元组
19
user_tuple = astuple(user)
20
print(user_tuple)
21
# ('Alice', 30, 'alice@example.com', ['admin', 'user'])
22

23
# 序列化为 JSON
24
json_str = json.dumps(asdict(user), ensure_ascii=False)
25
print(json_str)

1
from dataclasses import dataclass
2

3
@dataclass
4
class User:
5
    name: str
6
    age: int
7
    email: str
8

9
# 从字典创建
10
data = {"name": "Alice", "age": 30, "email": "alice@example.com"}
11
user = User(**data)
12
print(user)  # User(name='Alice', age=30, email='alice@example.com')
13

14
# 从 JSON 创建
15
json_str = '{"name": "Bob", "age": 25, "email": "bob@example.com"}'
16
data = json.loads(json_str)
17
user = User(**data)
18
print(user)

1
from dataclasses import dataclass, asdict
2
from typing import List
3
import json
4

5
@dataclass
6
class Address:
7
    city: str
8
    street: str
9

10
@dataclass
11
class User:
12
    name: str
13
    address: Address
14
    friends: List[str]
15

16
# 创建嵌套对象
17
user = User(
18
    name="Alice",
19
    address=Address("New York", "5th Avenue"),
20
    friends=["Bob", "Charlie"]
21
)
22

23
# asdict 递归转换
24
user_dict = asdict(user)
25
print(json.dumps(user_dict, indent=2, ensure_ascii=False))
26
# {
27
#   "name": "Alice",
28
#   "address": {
29
#     "city": "New York",
30
#     "street": "5th Avenue"
31
#   },
32
#   "friends": ["Bob", "Charlie"]
33
# }

1
from dataclasses import dataclass, field
2
from typing import Optional
3
import json
4

5
@dataclass
6
class DatabaseConfig:
7
    host: str = "localhost"
8
    port: int = 5432
9
    username: str = ""
10
    password: str = ""
11
    database: str = ""
12
    pool_size: int = 10
13
    timeout: int = 30
14

15
@dataclass
16
class RedisConfig:
17
    host: str = "localhost"
18
    port: int = 6379
19
    password: str = ""
20
    db: int = 0
21

22
@dataclass
23
class AppConfig:
24
    debug: bool = False
25
    database: DatabaseConfig = field(default_factory=DatabaseConfig)
26
    redis: RedisConfig = field(default_factory=RedisConfig)
27

28
    @classmethod
29
    def from_json(cls, json_str: str) -> 'AppConfig':
30
        data = json.loads(json_str)
31
        db_data = data.get('database', {})
32
        redis_data = data.get('redis', {})
33
        return cls(
34
            debug=data.get('debug', False),
35
            database=DatabaseConfig(**db_data),
36
            redis=RedisConfig(**redis_data)
37
        )
38

39
# 从 JSON 加载配置
40
config_json = '''
41
{
42
    "debug": true,
43
    "database": {
44
        "host": "db.example.com",
45
        "port": 5432,
46
        "username": "admin",
47
        "database": "myapp"
48
    },
49
    "redis": {
50
        "host": "redis.example.com"
51
    }
52
}
53
'''
54

55
config = AppConfig.from_json(config_json)
56
print(config.database.host)  # db.example.com
57
print(config.redis.host)     # redis.example.com

1
from dataclasses import dataclass, field
2
from typing import List, Optional
3
from datetime import datetime
4

5
# API 请求模型
6
@dataclass
7
class CreatePostRequest:
8
    title: str
9
    content: str
10
    tags: List[str] = field(default_factory=list)
11
    published: bool = False
12

13
# API 响应模型
14
@dataclass
15
class PostResponse:
16
    id: int
17
    title: str
18
    content: str
19
    tags: List[str]
20
    published: bool
21
    created_at: str
22
    author: str
23

24
    @classmethod
25
    def from_model(cls, post) -> 'PostResponse':
26
        """从数据库模型转换"""
27
        return cls(
28
            id=post.id,
29
            title=post.title,
30
            content=post.content,
31
            tags=post.tags,
32
            published=post.published,
33
            created_at=post.created_at.isoformat(),
34
            author=post.author.name
35
        )
36

37
# 错误响应
38
@dataclass
39
class ErrorResponse:
40
    error: str
41
    code: int
42
    details: Optional[str] = None

1
from dataclasses import dataclass, field
2
from typing import Any, Callable, Dict, List
3
from datetime import datetime
4

5
# 事件基类
6
@dataclass(frozen=True)
7
class Event:
8
    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
9

10
    @property
11
    def event_type(self) -> str:
12
        return self.__class__.__name__
13

14
# 具体事件
15
@dataclass(frozen=True)
16
class UserCreated(Event):
17
    user_id: int
18
    name: str
19
    email: str
20

21
@dataclass(frozen=True)
22
class OrderPlaced(Event):
23
    order_id: int
24
    user_id: int
25
    total: float
26
    items: List[dict] = field(default_factory=list)
27

28
# 事件处理器
29
class EventBus:
30
    def __init__(self):
31
        self._handlers: Dict[str, List[Callable]] = {}
32

33
    def subscribe(self, event_type: str, handler: Callable):
34
        self._handlers.setdefault(event_type, []).append(handler)
35

36
    def publish(self, event: Event):
37
        event_type = event.event_type
38
        for handler in self._handlers.get(event_type, []):
39
            handler(event)
40

41
# 使用
42
bus = EventBus()
43

44
def send_welcome_email(event: UserCreated):
45
    print(f"发送欢迎邮件给 {event.name} <{event.email}>")
46

47
bus.subscribe("UserCreated", send_welcome_email)
48

49
# 发布事件
50
event = UserCreated(user_id=1, name="Alice", email="alice@example.com")
51
bus.publish(event)
52
# 发送欢迎邮件给 Alice <alice@example.com>

1
from dataclasses import dataclass
2
from typing import Generic, TypeVar, List
3

4
T = TypeVar('T')
5

6
@dataclass
7
class Result(Generic[T]):
8
    data: T
9
    success: bool = True
10
    error: str = ""
11

12
# 使用
13
result1: Result[int] = Result(data=42)
14
result2: Result[str] = Result(data="hello")
15
result3: Result[List[str]] = Result(data=["a", "b"])
16

17
print(result1)  # Result(data=42, success=True, error='')
18
print(result2)  # Result(data='hello', success=True, error='')

1
from dataclasses import dataclass
2
from typing import Optional, List
3

4
@dataclass
5
class UserProfile:
6
    username: str
7
    email: str
8
    # Optional 字段默认 None
9
    avatar: Optional[str] = None
10
    bio: Optional[str] = None
11
    # 可变默认值用 default_factory
12
    followers: List[str] = field(default_factory=list)
13

14
    def __post_init__(self):
15
        # 后处理：设置默认头像
16
        if self.avatar is None:
17
            self.avatar = f"https://example.com/avatars/default.png"
18

19
profile = UserProfile(username="alice", email="alice@example.com")
20
print(profile.avatar)  # https://example.com/avatars/default.png

1
from dataclasses import dataclass, field
2

3
# ❌ 错误
4
# @dataclass
5
# class Bad:
6
#     items: list = []  # ValueError
7

8
# ✅ 正确
9
@dataclass
10
class Good:
11
    items: list = field(default_factory=list)

1
from dataclasses import dataclass
2

3
# ❌ 错误：父类有默认值，子类新字段不能无默认值
4
# @dataclass
5
# class Parent:
6
#     name: str = ""
7
#
8
# @dataclass
9
# class Child(Parent):
10
#     age: int  # TypeError: non-default argument follows default argument
11

12
# ✅ 正确方案1：子类字段也加默认值
13
@dataclass
14
class Parent:
15
    name: str = ""
16

17
@dataclass
18
class Child(Parent):
19
    age: int = 0  # 加默认值
20

21
# ✅ 正确方案2：使用 kw_only（Python 3.10+）
22
@dataclass
23
class ChildKW(Parent):
24
    age: int = field(kw_only=True, default=0)