把 Python 的类写“顺手”：从定义到最佳实践的一次梳理

在 Python 里写类，说难不难，说简单也不简单。很多人一开始能写出 class A:，但过一阵子就会遇到各种“写起来别扭”的点：构造函数放什么、属性怎么设计、__repr__ 要不要写、什么时候该用 @property，以及最常见的——到底什么时候该写类？

这篇文章不打算堆概念，而是用一套更“工程化”的写法，把 Python 类定义从入门到可维护，梳理一遍。希望你写完之后能有一种感觉：类这东西，写起来是顺手的，而不是硬凑出来的。

---

1. 类到底解决什么问题？

如果一句话总结：类用于管理“状态 + 行为”。

• 状态：对象有哪些数据（属性）
• 行为：对象能做什么事（方法）

举个很具体的小例子：你有一个“订单”，它有金额、折扣、状态；它会计算应付金额、能否取消、能否退款。这种“一个实体 + 一堆行为”的结构，用类通常比散落的函数更清晰。

当然，别为了面向对象而面向对象 🙃
如果只是一次性的数据处理，一个函数就够了；如果是可复用、多状态、多行为的实体，类会让代码更稳。

---

2. 最基本的类定义：class + __init__

一个最小可用的类通常长这样：

• class Xxx: 声明类
• __init__ 初始化对象状态
• 实例方法用 self 访问属性

关键点：self 不是关键字，而是约定俗成的第一个参数名。**它代表当前实例**。

---

3. 属性怎么放？先想清楚“对象的边界”

很多类一上来就写一堆属性，最后变成“万能对象”。一个经验是：

✅ 把必须且稳定的字段放 __init__
✅ 把可推导的值做成 @property
✅ 把可能变化的状态，用明确的方法去修改，而不是随手改字段

这样读者（以及未来的你）会更容易理解：对象“允许哪些变化”。

---

4. dataclass：写业务实体类的常用解法

如果你的类主要是“装数据，并提供少量行为”，dataclasses 往往是更省心的写法。它能帮你生成：

• __init__
• __repr__
• __eq__
• 默认值处理等

而且读起来更像“数据结构”，少了很多样板代码。

---

5. 方法的三种形态：实例方法、类方法、静态方法

这部分容易混，但其实只要抓住一个问题：这段逻辑属于谁？

5.1 实例方法（最常见）

需要访问实例状态（属性）时，用实例方法。

5.2 类方法 @classmethod

当你需要“用不同方式创建对象”时很适合。比如从字典、从 JSON、从环境变量等构造对象——这类通常做成 from_xxx 的工厂方法。

5.3 静态方法 @staticmethod

逻辑与类_和实例_都无关，只是碰巧放在类里更聚合。能不用就不用，因为它容易让类变成工具箱。

---

6. __repr__、__str__：让对象“可读”是一种工程素养

调试时最崩溃的体验之一就是打印对象看到 <xxx object at 0x...> 😅

• __repr__ 面向开发者：尽量包含关键信息，最好可重建
• __str__ 面向用户：更友好更简洁

如果你用 dataclass，通常 __repr__ 已经够用了。

---

7. @property：把“字段”升级为“受控接口”

@property 的价值在于：你可以在不改调用方代码的情况下，把简单字段变成计算属性或加校验逻辑。

一个很典型的例子：金额、数量等需要保证非负数。与其让别人随手赋值，不如统一入口做校验。

但也要克制：不要把复杂业务塞进 property。property 适合轻量、无副作用、可预测的逻辑。

---

8. 继承 vs 组合：优先组合

Python 支持继承，但工程上更推荐“组合优先”。

• 继承：适合明确的 is_a 关系，比如 Dog is a Animal
• 组合：适合 has_a 关系，比如 Order has a PaymentMethod

继承写得不当会让层级越来越深，类之间强耦合；组合更灵活，你可以替换组件而不影响整体结构。

经验法则：当你需要覆写多个父类方法、或者父类接口很“胖”时，先暂停一下，看看组合是不是更自然。

---

9. 一份“写起来顺手”的类模板（可直接套用）

下面这个模板不追求炫技，但很贴近实际工程需求：清晰的字段、可读的表示、受控的状态修改、合适的构造入口。

你可以把它当成日常写业务类的默认起点 ✅

from __future__ import annotations

from dataclasses import dataclass
from decimal import Decimal
from typing import Any, Mapping


@dataclass(frozen=False, slots=True)
class Order:
    """一个更像工程代码的订单类示例。"""

    order_id: str
    amount: Decimal
    discount: Decimal = Decimal("0")
    status: str = "CREATED"

    def __post_init__(self) -> None:
        if self.amount < 0:
            raise ValueError("amount 不能为负数")
        if self.discount < 0:
            raise ValueError("discount 不能为负数")
        if self.discount > self.amount:
            raise ValueError("discount 不能大于 amount")

    @property
    def payable(self) -> Decimal:
        """应付金额（轻量、无副作用，适合 property）。"""
        return self.amount - self.discount

    def apply_discount(self, discount: Decimal) -> None:
        """通过方法修改折扣，集中校验逻辑。"""
        if discount < 0:
            raise ValueError("discount 不能为负数")
        if discount > self.amount:
            raise ValueError("discount 不能大于 amount")
        self.discount = discount

    def cancel(self) -> None:
        """状态变更用明确方法表达，避免外部随意改 status。"""
        if self.status != "CREATED":
            raise RuntimeError(f"当前状态为 {self.status}，不能取消")
        self.status = "CANCELED"

    @classmethod
    def from_mapping(cls, data: Mapping[str, Any]) -> "Order":
        """常见的工厂方法：从 dict/配置构造对象。"""
        return cls(
            order_id=str(data["order_id"]),
            amount=Decimal(str(data["amount"])),
            discount=Decimal(str(data.get("discount", "0"))),
            status=str(data.get("status", "CREATED")),
        )

---

10. 写类时我常用的“自检清单”

写完一个类，问自己几件事，能显著减少后期返工：

• ✅ 这个类的职责是不是单一？有没有开始“万物皆类”？
• ✅ 初始化参数是否最小化？是否把可推导数据做成了 @property？
• ✅ 关键状态的修改有没有入口方法？还是随便改属性？
• ✅ 对象打印是否可读（__repr__/dataclass）？
• ✅ 是否真的需要继承？组合是否更合适？
• ✅ 是否有必要把某些字段设为只读（frozen=True 或只暴露 property）？

---

结语

Python 的类并不神秘，难的是把它写成“工程可维护”的样子：边界清晰、状态受控、打印友好、扩展自然。做到这些，你会发现类不再是负担，反而是让系统变稳定的工具。

如果你最近正好在重构一段“函数堆出来的业务逻辑”，不妨尝试把核心实体抽成类：先把数据放进去，再把行为放进去，最后再把状态修改收口。过程会很踏实，也很舒服。✨