Class (类)

官方文档：https://docs.python.org/zh-cn/3.12/tutorial/classes.html

🚀 1. Python 类是什么？

类（class）是 Python 中 封装数据（属性）和行为（方法） 的核心工具。

实例（object）是类的具体对象。

例：

class User:
    def __init__(self, name):
        self.name = name

u = User("jack")

📌 2. 类的基础结构

class MyClass:
    class_var = 123                # 类变量

    def __init__(self, x):         # 构造函数
        self.x = x                 # 实例变量

    def method(self):              # 实例方法
        return self.x * 2

    @classmethod
    def cmethod(cls):              # 类方法
        return cls.class_var

    @staticmethod
    def smethod(a, b):             # 静态方法
        return a + b

    @property
    def doubled(self):             # 计算属性
        return self.x * 2

📦 3. 类的四种方法类型（非常重要）

方法类型	自动传入	用途
普通方法	self（实例）	操作实例数据
类方法	cls（类）	工厂方法、访问类属性、子类适配
静态方法	无	工具函数，与类有关但不需要实例
property	self	优雅访问计算属性

staticmethod / classmethod / property 就是这个部分。

🎯 4. 构造函数（`init`）

构造函数在创建对象时自动执行：

class User:
    def __init__(self, name, age=18):
        self.name = name
        self.age = age

🧱 5. 类变量 vs 实例变量

实例变量（每个对象独立）

self.name

类变量（所有对象共享）

User.role = "guest"

⚠️ 不要滥用类变量（全局共享数据容易带来状态污染）。

☘️ 6. 继承（inheritance）

class Animal:
    def speak(self):
        return "..."

class Dog(Animal):
    def speak(self):
        return "woof"

📌 7. super() 用法

调用父类方法：

class Admin(User):
    def __init__(self, name):
        super().__init__(name)
        self.role = "admin"

🔧 8. 魔术方法（Magic Methods）

魔术方法可以让类表现得像内置类型。

常用的：

例：

class Counter:
    def __init__(self, n):
        self.n = n

    def __len__(self):
        return self.n

🚦 9. dataclass

Python 的最优雅的数据对象写法。

from dataclasses import dataclass

@dataclass
class Stock:
    code: str
    name: str
    price: float

自动生成：

__init__
__repr__
__eq__
结构化支持

⚙️ 10. 类的高级用法

10.1 工厂方法（classmethod）

class User:
    @classmethod
    def from_dict(cls, data):
        return cls(data["name"])

10.2 封装计算字段（property）

class Stock:
    def __init__(self, code):
        self.code = code

    @property
    def market(self):
        return "SZ" if self.code.startswith("00") else "SH"

10.3 单例模式

class Singleton:
    _instance = None

    @classmethod
    def instance(cls):
        if cls._instance is None:
            cls._instance = cls()
        return cls._instance

10.4 类作为命名空间（金典写法）

你可以把一堆工具函数放入类中，不实例化：

class StringUtils:
    @staticmethod
    def is_empty(s):
        return not s

🪛 11. Python 类 vs 函数：何时用类？

用类的场景：

需要保存状态
需要协作多个方法
对象需要具备多种行为
需要 property / staticmethod / classmethod
需要继承 / 多态
复杂对象建模（你常用的 stock/news 数据）

用函数的场景：

单一逻辑
无状态
工具函数（如你 utils 中的大部分）

🧩 12. 在工程中如何正确使用类（针对你的项目）

你 FastAPI + SQLAlchemy 项目里类主要用途：

模型类（SQLAlchemy ORM）

class User(Base):

数据对象（dataclass）

@dataclass
class NewsDetail:

工具类（static/class methods）

class StockUtils:
    @staticmethod
    def normalize(code): ...

配置类

class AppConfig:

Handler / Service 层

class NewsService:
    def get_news(self): ...

☘️ 13. Python 类的常见陷阱

❌ 在类中滥用全局变量
❌ 用静态方法存储状态
❌ 过度面向对象
❌ 工具类使用实例方法
❌ 魔术方法滥用导致可读性差
❌ 误用类变量导致共享数据污染
❌ 不写类型注解（你不会）

🏆 14. 最终总结（适合收藏）

🧩 Python 类核心结构

属性（变量）
行为（方法）
构造（__init__）
静态方法（无self）
类方法（cls）
property（计算属性）
魔术方法（协议）
继承 & super
dataclass（数据类）

🧩 什么时候用类？

有状态 -> 用类
无状态 -> 用函数
有行为组合 -> 用类
需要继承扩展 -> 用类

🧩 工程使用类的三大场景

数据建模（ORM / dataclass）
工具类（static/class）
服务层（业务逻辑封装）