在Python編程中，類定義是組織數據與封裝邏輯的核心範式。然而，當需要創建僅用於數據存儲的簡單類時，開發者往往需編寫大量重複機械的樣板代碼。例如用於屬性初始化的__init__方法、支持對象信息友好展示的__repr__方法、實現對象相等性比較的__eq__方法等。這類代碼不僅耗費開發精力，還容易因細節疏忽引入潛在錯誤，導致代碼可讀性與維護性下降。

為解決這一行業痛點，Python 3.7引入了dataclasses模塊，其提供的@dataclass裝飾器堪稱數據類開發的高效編程利器。該裝飾器能夠自動生成上述常用魔術方法，讓開發者無需關注冗餘的底層實現，僅需聚焦核心屬性定義，即可快速構建出功能完備、易用性高的數據類。

本文將從基礎概念切入，結合實際案例詳細拆解@dataclass的核心用法。

1 基礎使用

1.1 基礎方法

傳統方式下，定義一個簡單的數據類需要手動編寫大量樣板代碼：

class Person:
    def __init__(self, name: str, age: int, email: str = "unknown@example.com"):
        self.name = name
        self.age = age
        self.email = email
    
    def __repr__(self):
        return f"Person(name='{self.name}', age={self.age}, email='{self.email}')"
    
    def __eq__(self, other):
        if not isinstance(other, Person):
            return False
        return (self.name == other.name and 
                self.age == other.age and 
                self.email == other.email)

# 使用示例
p1 = Person("Alice", 25)
p2 = Person("Bob", 30, "bob@example.com")

print(p1)
print(p1 == Person("Alice", 25))

藉助@dataclass裝飾器，我們可以用極少的代碼實現相同功能：

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int
    email: str = "unknown@example.com"  # 默認值

# 使用示例
p1 = Person("Alice", 25)
p2 = Person("Bob", 30, "bob@example.com")

print(p1)
print(p1 == Person("Alice", 25))

@dataclass默認會為我們生成以下方法：

• __init__：初始化方法，根據定義的字段創建實例；
• __repr__： 提供友好的字符串表示，便於調試和日誌記錄；
• __eq__： 基於字段值的相等性比較；
• __hash__： 默認情況下，如果所有字段都是不可變類型，則生成哈希方法（可通過unsafe_hash參數控制）。

還可以在數據類中添加自定義方法和@property計算屬性，兼顧數據存儲與簡單業務邏輯：

from dataclasses import dataclass
from datetime import datetime

@dataclass
class Person:
    name: str
    age: int 
    email: str = "unknown@example.com"  # 默認值
    
    # 自定義方法：打招呼
    def greet(self) -> str:
        """返回一個個性化的問候語"""
        return f"Hello, my name is {self.name} and I'm {self.age} years old!"
    
    # 自定義方法：檢查是否成年
    def is_adult(self) -> bool:
        """判斷是否達到成年年齡（18歲）"""
        return self.age >= 18
    
    # @property計算屬性：出生年份（基於當前年齡推算）
    @property
    def birth_year(self) -> int:
        """根據當前年齡和年份，計算出生年份"""
        current_year = datetime.now().year
        return current_year - self.age

# 使用示例
p1 = Person("Alice", 25)
p2 = Person("Bob", 17, "bob@example.com")

# 原有功能保持不變
print(p1)
print(p1 == Person("Alice", 25))

# 調用自定義方法
print(p1.greet())          # 輸出: Hello, my name is Alice and I'm 25 years old!
print(f"Alice is adult? {p1.is_adult()}")  # 輸出: Alice is adult? True
print(f"Bob is adult? {p2.is_adult()}")    # 輸出: Bob is adult? False

# 訪問計算屬性（像訪問普通屬性一樣）
print(f"Alice was born in {p1.birth_year}")  

1.2 進階使用

@dataclass的強大之處不僅在於簡化基礎代碼，更在於支持複雜場景的定製化開發。藉助它提供的配置函數或參數設定，我們能解決可變類型默認值、字段定製化這類問題，甚至結合自定義方法落地業務邏輯。本節內容將針對這些核心能力展開具體解析，若需進一步的延展學習，可參考：Data Classes: @dataclass Decorator。

可變類型的默認值陷阱

在Python中，列表、字典等可變對象不適合作為函數或方法的默認參數。這是因為默認參數的值是在函數定義時計算並初始化的，而非每次調用時。這意味着，所有函數調用都會共享同一個可變對象實例，從而導致意外的行為。例如：

# 錯誤示例：所有實例共享同一個列表
class BadPerson:
    def __init__(self, name: str, hobbies: list = []):  # 危險！
        self.name = name
        self.hobbies = hobbies

p1 = BadPerson("Alice")
p1.hobbies.append("reading")
p2 = BadPerson("Bob")
print(p2.hobbies)  # 輸出['reading']——p2意外共享了p1的列表！

dataclasses模塊的field函數可通過default_factory參數指定默認值生成的工廠函數，為可變類型默認值問題提供完美的解決方案：

from dataclasses import dataclass, field  # 導入field函數

@dataclass
class GoodPerson:
    name: str
    # 使用list作為工廠函數，每次創建實例時生成新列表
    hobbies: list = field(default_factory=list)

p1 = GoodPerson("Alice")
p1.hobbies.append("reading")
p2 = GoodPerson("Bob")
print(p2.hobbies)  # 輸出[]，每個實例有獨立的列表！

field函數的核心參數：

• default_factory：指定一個無參函數（工廠函數），用於生成字段的默認值（如 list、dict、lambda 或自定義函數）；
• default：指定不可變類型的默認值（等同於直接賦值，如 field(default=0)）；
• init=False：表示該字段不參與 __init__ 方法的參數列表（需手動賦值或通過其他方式初始化）；
• repr=False：表示該字段不顯示在 __repr__ 方法的輸出中；
• compare=False：表示該字段不參與 __eq__ 等比較方法的邏輯。

from dataclasses import dataclass, field
import uuid
from datetime import date

@dataclass
class Book:
    """一個表示圖書信息的數據類"""
    
    # 圖書的基本信息，創建實例時必須提供
    title: str          # 書名
    author: str         # 作者
    price: float        # 價格
    
    # 圖書的唯一標識，使用UUID自動生成，比較對象時忽略此字段
    book_id: str = field(
        default_factory=lambda: str(uuid.uuid4())[:6],  # 生成6位的唯一ID
        compare=False                                   # 比較對象時不考慮這個字段
    )
    # 出版日期，默認使用當前日期，比較對象時忽略此字段
    publish_date: date = field(
        default_factory=date.today                     # 默認使用今天的日期
    )
    # 內部庫存編碼，有默認值，打印對象時不顯示此字段
    inventory_code: str = field(
        default="N/A",                                  # 默認值為"N/A"
        compare=False,
        repr=False                                      # 打印對象時不顯示這個字段
    )

# 創建兩本內容相同的圖書實例
book1 = Book("Python編程", "張三", 59.90, inventory_code="PY-001")
book2 = Book("Python編程", "張三", 59.90, inventory_code="PY-002")

# 打印第一本書的信息（不會顯示inventory_code）
print("第一本書信息:", book1)
# 比較兩本書是否相等（只會比較title, author, price）
print("兩本書是否相等?", book1 == book2)

# 訪問被隱藏的字段
print("第一本書的庫存編碼:", book1.inventory_code)
print("第一本書的ID:", book1.book_id)

輔助函數

除了field輔助函數外，Python的dataclasses模塊還提供了一系列實用的工具函數與特殊類型，極大地擴展了數據類的靈活性與功能性：

• asdict()：將數據類實例轉換為標準字典，
• astuple()：將數據類實例轉換為元組，
• replace()：創建數據類實例的副本，並按需替換指定字段值，
• fields()：獲取數據類的字段元數據信息，
• is_dataclass()：判斷對象（類或實例）是否為數據類，
• make_dataclass()：動態編程方式創建數據類（無需裝飾器），
• InitVar：標記僅用於__init__初始化的臨時變量（不會成為實例屬性）。

示例代碼如下：

from dataclasses import (
    dataclass, asdict, astuple, replace, fields, 
    is_dataclass, make_dataclass, InitVar,field
)

# 定義基礎數據類（含InitVar演示）
@dataclass
class Person:
    name: str
    age: int
    # InitVar標記：address僅用於初始化，不會成為實例屬性
    address: InitVar[str] = field(default="未知地址")  # 設置默認值

    def __post_init__(self, address):
        # 利用InitVar參數初始化實例屬性
        self.full_info = f"{self.name} ({self.age}), 地址: {address}"

# 創建實例
person = Person("Alice", 30, "123 Main St")

# 1. asdict()：轉字典
print("asdict結果:", asdict(person))

# 2. astuple()：轉元組
print("astuple結果:", astuple(person))

# 3. replace()：創建副本並修改字段
new_person = replace(person, age=31)
print("replace後的實例:", new_person)

# 4. fields()：獲取字段信息
print("\n字段信息:")
for field_info in fields(person):
    print(f"字段名: {field_info.name}, 類型: {field_info.type}, 是否InitVar: {isinstance(field_info.type, InitVar)}")

# 5. is_dataclass()：判斷是否為數據類
print("\nis_dataclass(Person):", is_dataclass(Person))
print("is_dataclass(person):", is_dataclass(person))
print("is_dataclass(dict):", is_dataclass(dict))

# 6. make_dataclass()：動態創建數據類
DynamicPerson = make_dataclass(
    "DynamicPerson",  # 類名
    [("name", str), ("age", int)],  # 字段列表
    namespace={"greet": lambda self: f"Hello, {self.name}!"}  # 額外方法/屬性
)
dynamic_person = DynamicPerson("Bob", 25)
print("\n動態創建的數據類實例:", dynamic_person)
print("動態類方法調用:", dynamic_person.greet())

初始化後處理

在dataclasses模塊中，__post_init__是一個魔術方法，會在自動生成的__init__方法執行完畢後立即被調用，主要用於實現初始化後的自動處理邏輯（例如計算派生字段、補充屬性賦值等）；當與指定init=False的字段配合使用時，該方法可靈活處理無需作為構造函數參數傳入、僅需通過初始化後邏輯生成的派生屬性。

from dataclasses import dataclass, field

@dataclass
class Product:
    name: str
    price: float
    quantity: int = 1
    total_price: float = field(init=False)  # 總價由其他字段計算
    
    def __post_init__(self):
        """初始化後自動計算總價"""
        self.total_price = self.price * self.quantity

# 使用示例
apple = Product("Apple", 5.5, 10)
banana = Product("Banana", 3.0)

print(f"Apple total: ${apple.total_price}")  # 輸出: 55.0
print(f"Banana total: ${banana.total_price}")  # 輸出: 3.0

字段順序要求

在定義dataclass類字段時，無默認值的字段必須放在有默認值的字段之前。

• 錯誤寫法：先聲明帶默認值的address，再聲明無默認值的id → 引發語法錯誤。
• 正確寫法：先聲明無默認值的id，再聲明帶默認值的address → 正常運行。

這並非dataclass的專屬限制，而是Python語言的基礎語法規則。

@dataclass裝飾器的核心功能之一，是根據類中定義的字段，自動生成__init__構造方法。

• 當你這樣寫：

  @dataclass
  class InvalidFieldOrder:
      address: str = "Beijing"
      id: int
  

  它會嘗試生成這樣的__init__：

  def __init__(self, address: str = "Beijing", id: int):
      ...
  

但這在Python中是完全不允許的！函數定義時，帶默認值的參數（可選參數）不能出現在無默認值的參數（必填參數）之前。

• 而正確的寫法：

  @dataclass
  class ValidFieldOrder:
      id: int
      address: str = "Beijing"
  

  會生成合法的 __init__：

  def __init__(self, id: int, address: str = "Beijing"):
      ...
  

這完全符合Python的語法規範：必填參數在前，可選參數在後。

數據類繼承

數據類既可以作為父類被其他數據類繼承，也可以被普通Python類繼承：當數據類繼承另一個數據類時，子類會自動合併父類的字段；而普通類繼承數據類時，若需使用父類的字段和構造邏輯，則必須手動調用父類的構造函數並處理相關參數。

from dataclasses import dataclass

# 🟡 基類：形狀（數據類）
@dataclass
class Shape:
    color: str

# 🟦 子類：正方形（數據類）
@dataclass
class Square(Shape):
    side_length: float = 1.0  # 默認邊長為1

# 🟢 子類：圓形（普通類，不是數據類）
class Circle(Shape):
    def __init__(self, color: str, radius: float = 1.0):
        # 必須手動調用父類的構造函數來初始化 color
        super().__init__(color)
        self.radius = radius
    
    # 如果需要友好的打印格式，必須自己實現 __repr__ 方法
    def __repr__(self):
        return f"Circle(color='{self.color}', radius={self.radius})"

# 使用示例
red_square = Square("red")
print(red_square) 

blue_circle = Circle("blue", 5.0)
print(blue_circle) 

default_circle = Circle("green")
print(default_circle) 

@dataclass裝飾器參數詳解

@dataclass裝飾器提供了多個可靈活配置的參數，適配各類開發場景。以下為核心參數的詳細説明，涵蓋功能作用、使用約束及版本要求：

1. init=True

   • 控制是否自動生成 __init__() 方法。
   • 如果設為 False，你需要自己定義 __init__ 方法。

2. repr=True

   • 控制是否自動生成 __repr__() 方法。
   • 生成的 repr 會包含類名和所有字段及其值。

3. eq=True

   • 控制是否自動生成 __eq__() 方法。
   • 基於類的字段值進行相等性比較。

4. order=False

   • 控制是否生成比較運算符方法 (__lt__, __le__, __gt__, __ge__)。
   • 設為 True 時，會根據字段定義的順序進行比較。
   • 注意：設置 order=True 時，eq 必須為 True（默認）。

5. unsafe_hash=False

   • 控制是否生成 __hash__() 方法。
   • 默認情況下：
     • 如果 frozen=True，會生成基於字段的 __hash__
     • 如果 frozen=False，__hash__ 會被設為 None
   • 設為 True 會強制生成 __hash__，但在實例可變時使用可能導致問題。

6. frozen=False

   • 如果設為 True，會創建一個“凍結”的類，實例屬性無法被修改。
   • 嘗試修改會拋出 dataclasses.FrozenInstanceError。

7. match_args=True (Python 3.10+)

   • 控制是否生成 __match_args__ 屬性，用於模式匹配。

8. kw_only=False (Python 3.10+)

   • 如果設為True，所有字段都將成為關鍵字參數，實例化時必須通過關鍵字形式傳參，不能使用位置參數。

9. slots=False (Python 3.10+)

   • 如果設為 True，會生成 __slots__ 屬性，能限制類實例只能擁有預定義的屬性，同時節省內存並提高屬性訪問速度。

10. weakref_slot=False (Python 3.11+)

    • 當 slots=True 時，如果設為 True，會添加一個用於弱引用的槽位。

示例代碼如下：

from dataclasses import dataclass, FrozenInstanceError
import weakref

# 1. init=False 示例
@dataclass(init=False)
class Person:
    name: str
    age: int
    
    # 手動定義 __init__ 方法
    def __init__(self, name):
        self.name = name
        self.age = 0  # 設置默認年齡

# 2. repr=False 示例
@dataclass(repr=False)
class Point:
    x: int
    y: int
    
    # 自定義 repr
    def __repr__(self):
        return f"Point at ({self.x}, {self.y})"

# 3. eq=True示例
@dataclass(eq=True)
class Product:
    id: int
    name: str

# 4. order=True 示例
@dataclass(order=True)
class Student:
    score: int
    name: str

# 5. unsafe_hash=True 示例
@dataclass(unsafe_hash=True)
class Book:
    title: str
    author: str

# 6. frozen=True 示例
@dataclass(frozen=True)
class ImmutablePoint:
    x: int
    y: int

# 7. match_args=True 示例 (Python 3.10+)
@dataclass(match_args=True)
class Shape:
    type: str
    size: int

# 8. kw_only=True 示例 (Python 3.10+)
@dataclass(kw_only=True)
class Car:
    brand: str
    model: str

# 9. slots=True 示例 (Python 3.10+)
@dataclass(slots=True)
class User:
    id: int
    username: str

# 10. weakref_slot=True 示例 (Python 3.11+)
@dataclass(slots=True, weakref_slot=True)
class Node:
    value: int

# 測試代碼
if __name__ == "__main__":
    # 1. 測試 init=False
    p = Person("Alice")
    print(f"1. Person: {p.name}, {p.age}")
    
    # 2. 測試 repr=False
    point = Point(3, 4)
    print(f"2. Point: {point}")
    
    # 3. 測試 eq=True
    p1 = Product(1, "Apple")
    p2 = Product(1, "Apple")
    print(f"3. Products equal? {p1 == p2}")
    
    # 4. 測試 order=True
    s1 = Student(90, "Bob")
    s2 = Student(85, "Alice")
    print(f"4. s1 > s2? {s1 > s2}") # 按照參數定義順序比較
    
    # 5. 測試 unsafe_hash=True
    book = Book("Python", "Guido")
    print(f"5. Book hash: {hash(book)}")
    
    # 6. 測試 frozen=True
    immutable_point = ImmutablePoint(1, 2)
    try:
        immutable_point.x = 3
    except FrozenInstanceError as e:
        print(f"6. Frozen error: {e}")
    
    # 7. 測試 match_args=True (Python 3.10+)
    shape = Shape("circle", 5)
    match shape:
        case Shape("circle", size):
            print(f"7. Circle with size {size}")
        case Shape("square", size):
            print(f"7. Square with size {size}")
    
    # 8. 測試 kw_only=True
    car = Car(brand="Toyota", model="Camry")
    print(f"8. Car: {car}")
    
    # 9. 測試 slots=True
    user = User(1, "admin")
    print(f"9. User: {user}")
    try:
        user.email = "admin@example.com"
    except AttributeError as e:
        print(f"9. Slots error: {e}")
    
    # 10. 測試 weakref_slot=True
    node = Node(10)
    ref = weakref.ref(node)
    print(f"10. Weakref node value: {ref().value}")

2 參考

• Data Classes: @dataclass Decorator