Decorator -- staticmethod

🚀 1. staticmethod 是什么？

@staticmethod 用来把类中的一个方法标记为静态方法：

不会接收 self
不会接收 cls
和类实例 / 类本身没有关联
本质上就是一个放在类里面的普通函数

它只因为逻辑相关，而被组织在类里。

📌 2. 最简单示例

class MathUtils:
    @staticmethod
    def add(a, b):
        return a + b

print(MathUtils.add(1, 2))   # 3
print(MathUtils().add(1, 2)) # 3，实例也能调用

特点：

类可以调用
实例也可以调用
永远不会自动传入 self / cls

📌 3. staticmethod vs classmethod vs 普通方法

类型	是否有 self？	是否有 cls？	用途
普通方法	✅ 有自带 self	❌	操作实例数据
类方法	❌	✅ 自带 cls	操作类的数据、工厂函数
静态方法	❌	❌	工具函数，与类只在逻辑上相关

📌 4. 为什么要用 @staticmethod？

✅ 把逻辑相关的工具函数放在类中，而不是放在全局
✅ 保持命名空间干净
✅ 避免误传 self 或 cls

📌 5. 常见场景（最重要）

5.1 工具函数封装（最常见）

很多函数就适合放在 class 里做静态方法。

class StringUtils:
    @staticmethod
    def is_empty(s: str):
        return not s or s.strip() == ""

5.2 数据转换函数

stock code 转换、日期转换都很适合 staticmethod：

class StockHelper:
    @staticmethod
    def coderename(code: str, restore=False):
        if restore:
            return code.replace("sz", "00").replace("sh", "60")
        return code

5.3 工厂方法的一部分逻辑（不依赖 cls）

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

    @staticmethod
    def validate_age(age):
        return 0 <= age <= 120

    @classmethod
    def create(cls, name, age):
        if not cls.validate_age(age):
            raise ValueError("invalid age")
        return cls(name, age)

5.4 与类逻辑有关，但不应该访问类/实例

常见于：

数学运算工具
字符串工具
日期转换
编码/解码工具
参数检查逻辑

你的项目中 utils.isTrue 非常适合作为静态方法！

📌 6. staticmethod 实际上做了什么？

@staticmethod
def func(...):
    ...

等价于：

func = staticmethod(func)

它把函数包装成一个描述符对象，使它不会变成绑定方法。

📌 7. staticmethod 的错误使用（要避免）

❌ 不要在需要 self 的方法上用 staticmethod
❌ 不要把本来应该放在 utils 的函数硬塞进类里
❌ 不要把需要访问类属性的方法写成 staticmethod（应该是 classmethod）

📌 8. 什么时候用 classmethod，而不是 staticmethod？

需要访问类数据时：

class Config:
    version = "1.0"

    @classmethod
    def get_version(cls):
        return cls.version

📌 9. 在 FastAPI 项目中的最佳实践

强烈推荐如下组织结构：

utils/
  ├── string.py   -> StringUtils
  ├── date.py     -> DateUtils
  ├── stock.py    -> StockUtils

每个 utils 类里封装静态方法：

class DateUtils:
    @staticmethod
    def string_to_date(s: str):
        return datetime.strptime(s, "%Y-%m-%d")

调用时：

from utils.date import DateUtils
DateUtils.string_to_date("2025-01-01")

非常清晰。

📌 10. 重构你项目中的一段代码示例（真实参考）

你之前写的：

if utils.isTrue(df, bool):

推荐重构为：

class TypeUtils:
    @staticmethod
    def is_true(value, t):
        return isinstance(value, t)

调用：

if TypeUtils.is_true(df, bool):

命名更规范。

总结

✅ staticmethod：逻辑相关但不依赖类/实例

✅ classmethod：需要 cls

✅ 普通方法：需要 self

你选择 @staticmethod 的最佳场景：

工具函数
转换函数
纯逻辑函数
参数检查函数
不希望接收 self 的方法