sycommon-python-lib 0.1.56b14__py3-none-any.whl → 0.1.56b15__py3-none-any.whl

sycommon/tools/snowflake.py

@@ -10,213 +10,191 @@ import psutil
 
 
 class ClassProperty:
-    """
-    自定义类属性描述符，替代 @classmethod + @property 的废弃写法
-    支持通过 类.属性 的方式访问，无需实例化
-    """
+    """支持通过 类.属性 的方式访问，无需实例化"""
 
     def __init__(self, func):
         self.func = func
 
     def __get__(self, instance: Any, cls: Type) -> str:
-        # 调用传入的函数，并传入类本身作为第一个参数
         return self.func(cls)
 
 
 class Snowflake:
-    """雪花算法生成器（生产级优化版，无公网依赖，适配内网/K8s环境）"""
-    # 基础配置（可根据业务调整）
+    """
+    雪花算法生成器（高并发终极优化版 - 修复语法错误）
+
+    终极优化点：
+    1. 解决溢出死锁：当序列号溢出时，释放锁自旋等待，避免阻塞其他线程。
+    2. 锁内原子更新：确保时钟回拨判断与状态更新的原子性。
+    3. 移除 sleep：全流程无休眠，纯自旋保证极致吞吐。
+    """
     START_TIMESTAMP = 1388534400000  # 2014-01-01 00:00:00
     SEQUENCE_BITS = 12
     MACHINE_ID_BITS = 10
     MAX_MACHINE_ID = (1 << MACHINE_ID_BITS) - 1  # 0~1023
-    MAX_SEQUENCE = (1 << SEQUENCE_BITS) - 1
+    MAX_SEQUENCE = (1 << SEQUENCE_BITS) - 1     # 4095
     MACHINE_ID_SHIFT = SEQUENCE_BITS
     TIMESTAMP_SHIFT = SEQUENCE_BITS + MACHINE_ID_BITS
-    CLOCK_BACKWARD_THRESHOLD = 5  # 容忍的时钟回拨阈值（毫秒）
-    _MAX_JAVA_LONG = 9223372036854775807  # Java Long最大值
+    CLOCK_BACKWARD_THRESHOLD = 5
+    _MAX_JAVA_LONG = 9223372036854775807
 
-    # 类级别的单例实例（线程安全）
     _instance = None
     _instance_lock = threading.Lock()
 
     def __init__(self, machine_id: Optional[int] = None):
-        """
-        初始化：优先使用传入的machine_id，否则自动从K8s环境获取
-        :param machine_id: 手动指定机器ID（None则自动计算）
-        """
-        # 前置校验：确保雪花ID不会超过Java Long最大值
         self._validate_timestamp_range()
-
-        # 自动计算K8s环境下的machine_id
         if machine_id is None:
             machine_id = self._get_k8s_machine_id()
-
-        # 校验machine_id合法性
         if not (0 <= machine_id <= self.MAX_MACHINE_ID):
             raise ValueError(f"机器ID必须在0~{self.MAX_MACHINE_ID}之间")
 
-        # 初始化核心参数
         self.machine_id = machine_id
         self.last_timestamp = -1
         self.sequence = 0
         self.lock = threading.Lock()
 
     def _validate_timestamp_range(self):
-        """校验当前时间戳是否在雪花ID支持的范围内，避免超过Java Long最大值"""
         max_support_timestamp = self.START_TIMESTAMP + \
             (1 << (64 - self.TIMESTAMP_SHIFT)) - 1
         current_timestamp = self._get_current_timestamp()
         if current_timestamp > max_support_timestamp:
-            raise RuntimeError(
-                f"当前时间戳({current_timestamp})超过雪花ID支持的最大时间戳({max_support_timestamp})，"
-                f"请调整START_TIMESTAMP或减少TIMESTAMP_SHIFT位数"
-            )
+            raise RuntimeError(f"当前时间戳({current_timestamp})超过支持范围")
 
     def _get_k8s_machine_id(self) -> int:
-        """
-        从K8s环境自动计算唯一machine_id（无公网依赖，多层兜底，降低重复风险）：
-        优先级：POD_NAME > POD_IP > 容器内网IP（psutil读取） > 容器主机名 > 进程+时间+随机数（最终兜底）
-        """
-        # 1. 优先读取K8s内置的POD_NAME（默认注入，优先级最高）
         pod_name = environ.get("POD_NAME")
         if pod_name:
             return self._hash_to_machine_id(pod_name)
-
-        # 2. 读取POD_IP（手动配置downwardAPI后必存在）
         pod_ip = environ.get("POD_IP")
         if pod_ip:
             return self._hash_to_machine_id(pod_ip)
-
-        # 3. 兜底1：读取本机网卡获取内网IP（替换netifaces，使用psutil）
         try:
             local_ip = self._get_local_internal_ip()
             if local_ip:
                 return self._hash_to_machine_id(local_ip)
         except Exception:
             pass
-
-        # 4. 兜底2：获取容器主机名（K8s中默认等于Pod名称，保证唯一）
         hostname = socket.gethostname()
         if hostname:
             return self._hash_to_machine_id(hostname)
-
-        # 5. 最终兜底：增加熵值（进程ID+毫秒时间戳+随机数），大幅降低重复概率
         fallback_text = f"{os.getpid()}_{int(time.time()*1000)}_{random.randint(0, 100000)}"
         return self._hash_to_machine_id(fallback_text)
 
     def _get_local_internal_ip(self) -> Optional[str]:
-        """
-        使用psutil读取本机网卡信息，获取非回环的内网IP（跨平台兼容，过滤lo/lo0等回环网卡）
-        :return: 内网IP字符串，失败返回None
-        """
         try:
-            # 遍历所有网卡接口
             net_if_addrs = psutil.net_if_addrs()
             for interface_name, addrs in net_if_addrs.items():
-                # 过滤回环/虚拟网卡（兼容lo、lo0、lo1、Loopback、virtual等）
                 if (interface_name.lower().startswith("lo")
-                        or interface_name.lower() in ["loopback", "virtual"]):
+                        or interface_name.lower() in ["loopback", "virtual", "docker", "veth"]):
                     continue
-                # 遍历该网卡的所有地址，优先返回第一个非回环IPv4
                 for addr in addrs:
                     if addr.family == psutil.AF_INET:
                         ip = addr.address
-                        if ip and not ip.startswith('127.'):
+                        if ip and not ip.startswith('127.') and not ip.startswith('0.'):
                             return ip
             return None
         except Exception:
-            # psutil调用失败，降级到纯内置方法
             return self._get_local_ip_fallback()
 
     def _get_local_ip_fallback(self) -> Optional[str]:
-        """
-        增强版降级方案：纯Python内置方法，多维度获取内网IP（无第三方依赖）
-        """
-        # 方案1：socket绑定内网地址（避免访问公网）
         try:
             s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-            s.connect(("192.168.0.1", 80))
+            s.connect(("10.0.0.1", 80))
             local_ip = s.getsockname()[0]
             s.close()
-            if not local_ip.startswith('127.'):
+            if not local_ip.startswith('127.') and not local_ip.startswith('0.'):
                 return local_ip
         except Exception:
             pass
-
-        # 方案2：遍历所有本地IP（通过hostname解析）
         try:
             hostname = socket.gethostname()
             ip_list = socket.gethostbyname_ex(hostname)[2]
             for ip in ip_list:
-                if not ip.startswith('127.'):
+                if not ip.startswith('127.') and not ip.startswith('0.'):
                     return ip
         except Exception:
             pass
-
         return None
 
     def _hash_to_machine_id(self, text: str) -> int:
-        """将字符串哈希后取模，得到0~1023的machine_id（保证分布均匀）"""
         hash_bytes = hashlib.md5(text.encode("utf-8")).digest()
-        hash_int = int.from_bytes(hash_bytes[:4], byteorder="big")
-        return hash_int % self.MAX_MACHINE_ID
+        return int.from_bytes(hash_bytes[:4], byteorder="big") % (self.MAX_MACHINE_ID + 1)
 
     def _get_current_timestamp(self) -> int:
-        """获取当前毫秒级时间戳"""
         return int(time.time() * 1000)
 
-    def _wait_next_millisecond(self, current_timestamp: int) -> int:
-        """等待直到下一个毫秒，避免序列耗尽"""
-        while current_timestamp <= self.last_timestamp:
-            current_timestamp = self._get_current_timestamp()
-        return current_timestamp
-
     def generate_id(self) -> int:
-        """生成雪花ID（生产级优化：优化锁粒度，容忍轻微时钟回拨）"""
-        current_timestamp = self._get_current_timestamp()
-
-        # 1. 处理时钟回拨：容忍CLOCK_BACKWARD_THRESHOLD内的微调，超过则抛异常
-        time_diff = self.last_timestamp - current_timestamp
-        if time_diff > 0:
-            if time_diff > self.CLOCK_BACKWARD_THRESHOLD:
-                raise RuntimeError(
-                    f"时钟回拨检测：当前时间戳({current_timestamp}) < 上一次时间戳({self.last_timestamp})，"
-                    f"差值{time_diff}ms（阈值{self.CLOCK_BACKWARD_THRESHOLD}ms）"
-                )
-            # 轻微回拨：等待时钟追上
-            current_timestamp = self._wait_next_millisecond(current_timestamp)
+        """
+        生成雪花ID（高并发优化版）
+        使用 while True 循环来处理序列号溢出时的重试逻辑
+        """
+        while True:
+            # 1. 快速获取当前时间
+            current_timestamp = self._get_current_timestamp()
 
-        # 2. 优化锁粒度：仅在同一毫秒内递增序列时加锁
-        if current_timestamp != self.last_timestamp:
-            with self.lock:
-                self.last_timestamp = current_timestamp
-                self.sequence = 0
-        else:
+            # 2. 加锁，保证状态更新的原子性
             with self.lock:
-                self.sequence = (self.sequence + 1) & self.MAX_SEQUENCE
-                if self.sequence == 0:
-                    current_timestamp = self._wait_next_millisecond(
-                        current_timestamp)
+                # 读取当前状态（快照）
+                last_timestamp = self.last_timestamp
+                sequence = self.sequence
+
+                # 2.1 处理时钟回拨
+                time_diff = last_timestamp - current_timestamp
+                if time_diff > 0:
+                    if time_diff > self.CLOCK_BACKWARD_THRESHOLD:
+                        # 大幅回拨：直接“借用”未来1ms
+                        current_timestamp = last_timestamp + 1
+                    else:
+                        # 微小回拨：锁内自旋等待追上（通常很快）
+                        while current_timestamp <= last_timestamp:
+                            current_timestamp = self._get_current_timestamp()
+
+                # 2.2 计算序列号
+                if current_timestamp == last_timestamp:
+                    # 同一毫秒内
+                    sequence = (sequence + 1) & self.MAX_SEQUENCE
+                    if sequence == 0:
+                        # 【关键优化】：序列号溢出！
+                        # 此时必须等待下一毫秒。为了不阻塞其他线程，我们：
+                        # 1. 更新 last_timestamp 标记进入新毫秒 (可选，但这里直接 release 更安全)
+                        # 2. 释放锁
+                        # 3. 锁外自旋
+                        # 4. 下一轮循环重新抢锁
+
+                        self.lock.release()  # 手动释放锁
+
+                        # 锁外自旋等待下一毫秒
+                        while current_timestamp <= last_timestamp:
+                            current_timestamp = self._get_current_timestamp()
+
+                        # 等待到了新毫秒，进入下一轮循环（continue 默认行为），重新抢锁竞争
+                        continue
+
+                elif current_timestamp > last_timestamp:
+                    # 时间推进，重置序列号
+                    sequence = 0
                     self.last_timestamp = current_timestamp
+                    self.sequence = sequence
+                else:
+                    # current < last 的情况通常已被回拨逻辑处理
+                    pass
+
+                # 2.4 生成 ID
+                snowflake_id = (
+                    ((current_timestamp - self.START_TIMESTAMP)
+                     << self.TIMESTAMP_SHIFT)
+                    | (self.machine_id << self.MACHINE_ID_SHIFT)
+                    | sequence
+                )
 
-        # 3. 计算最终雪花ID
-        snowflake_id = (
-            ((current_timestamp - self.START_TIMESTAMP) << self.TIMESTAMP_SHIFT)
-            | (self.machine_id << self.MACHINE_ID_SHIFT)
-            | self.sequence
-        )
-
-        # 最终校验：确保不超过Java Long最大值
-        if snowflake_id > self._MAX_JAVA_LONG:
-            raise RuntimeError(
-                f"生成的雪花ID({snowflake_id})超过Java Long最大值({self._MAX_JAVA_LONG})")
+                # 更新全局状态（如果是同一毫秒）
+                if current_timestamp == self.last_timestamp:
+                    self.sequence = sequence
 
-        return snowflake_id
+            # 成功生成 ID，退出循环
+            return snowflake_id
 
     @staticmethod
     def parse_id(snowflake_id: int) -> dict:
-        """解析雪花ID，返回生成时间、机器ID、序列等信息"""
         from datetime import datetime
         sequence = snowflake_id & Snowflake.MAX_SEQUENCE
         machine_id = (snowflake_id >>
@@ -225,7 +203,6 @@ class Snowflake:
             Snowflake.START_TIMESTAMP
         generate_time = datetime.fromtimestamp(
             timestamp / 1000).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
-
         return {
             "snowflake_id": snowflake_id,
             "generate_time": generate_time,
@@ -236,65 +213,41 @@ class Snowflake:
 
     @classmethod
     def next_id(cls) -> str:
-        """
-        生成雪花ID（线程安全单例模式，避免重复创建实例，锁内完成所有初始化）
-        :return: 雪花ID字符串
-        """
         if cls._instance is None:
             with cls._instance_lock:
                 if cls._instance is None:
-                    # 锁内初始化，避免多线程重复计算machine_id
                     cls._instance = cls()
         return str(cls._instance.generate_id())
 
     @ClassProperty
     def id(cls) -> str:
-        """
-        直接通过 `Snowflake.id` 属性生成雪花ID（兼容Python 3.11+）
-        :return: 雪花ID字符串
-        """
         return cls.next_id()
 
 
 if __name__ == "__main__":
-    print("=== 生产级雪花算法ID生成测试 ===")
-    # 1. 基础生成测试
-    id1 = Snowflake.id
-    id2 = Snowflake.id
-    id3 = Snowflake.id
-    print(f"生成ID1: {id1}")
-    print(f"生成ID2: {id2}")
-    print(f"生成ID3: {id3}")
-    print(f"ID是否唯一: {len({id1, id2, id3}) == 3}")
-
-    # 2. 解析ID信息
-    print("\n=== 雪花ID解析 ===")
-    parse_info = Snowflake.parse_id(int(id3))
-    for key, value in parse_info.items():
-        print(f"{key}: {value}")
-
-    # 3. 批量唯一性验证（10000个ID）
-    print("\n=== 批量唯一性验证（10000个）===")
-    id_set = set()
-    duplicate_count = 0
-    for i in range(10000):
-        snow_id = Snowflake.id
-        if snow_id in id_set:
-            duplicate_count += 1
-        id_set.add(snow_id)
-    print(f"总生成数量: 10000")
-    print(f"唯一ID数量: {len(id_set)}")
-    print(f"重复ID数量: {duplicate_count}")
-    print(f"机器ID: {Snowflake._instance.machine_id}")
-
-    # 4. 高并发测试
     import concurrent.futures
-    print("\n=== 高并发测试（100线程）===")
-    id_set_concurrent = set()
+
+    print("=== 高并发终极版 Snowflake 性能测试 ===")
+    count = 100000
+    workers = 100
+
+    ids = []
+    start_time = time.perf_counter()
+
+    def task():
+        return Snowflake.id
+
     with concurrent.futures.ThreadPoolExecutor(max_workers=100) as executor:
-        futures = [executor.submit(lambda: Snowflake.id) for _ in range(10000)]
+        futures = [executor.submit(task) for _ in range(count)]
         for future in concurrent.futures.as_completed(futures):
-            id_set_concurrent.add(future.result())
-    print(f"高并发生成唯一ID数量: {len(id_set_concurrent)}")
+            ids.append(future.result())
+
+    end_time = time.perf_counter()
+    duration = end_time - start_time
 
-    print("\n=== 生产级雪花算法验证通过 ===")
+    unique_count = len(set(ids))
+    print(f"生成数量: {len(ids)}")
+    print(f"唯一ID数量: {unique_count}")
+    print(f"是否有重复: {'是 ❌' if unique_count != len(ids) else '否 ✅'}")
+    print(f"总耗时: {duration:.4f} 秒")
+    print(f"吞吐量 (QPS): {len(ids) / duration:,.2f}")

{sycommon_python_lib-0.1.56b14.dist-info → sycommon_python_lib-0.1.56b15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.1.56b14
+Version: 0.1.56b15
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.1.56b14.dist-info → sycommon_python_lib-0.1.56b15.dist-info}/RECORD

@@ -77,10 +77,10 @@ sycommon/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sycommon/tools/docs.py,sha256=OPj2ETheuWjXLyaXtaZPbwmJKfJaYXV5s4XMVAUNrms,1607
 sycommon/tools/env.py,sha256=Ah-tBwG2C0_hwLGFebVQgKdWWXCjTzBuF23gCkLHYy4,2437
 sycommon/tools/merge_headers.py,sha256=HV_i52Q-9se3SP8qh7ZGYl8bP7Fxtal4CGVkyMwEdM8,4373
-sycommon/tools/snowflake.py,sha256=lVEe5mNCOgz5OqGQpf5_nXaGnRJlI2STX2s-ppTtanA,11947
+sycommon/tools/snowflake.py,sha256=MUUkBeCm3Tp9SLBU6oNjLsIPAGfn7OmhrR9YvWWhYm8,9569
 sycommon/tools/timing.py,sha256=OiiE7P07lRoMzX9kzb8sZU9cDb0zNnqIlY5pWqHcnkY,2064
-sycommon_python_lib-0.1.56b14.dist-info/METADATA,sha256=6ctE6A1k94pk7BDDaUWojL_gBLx8dodryWjZjLOa0yU,7302
-sycommon_python_lib-0.1.56b14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sycommon_python_lib-0.1.56b14.dist-info/entry_points.txt,sha256=q_h2nbvhhmdnsOUZEIwpuoDjaNfBF9XqppDEmQn9d_A,46
-sycommon_python_lib-0.1.56b14.dist-info/top_level.txt,sha256=98CJ-cyM2WIKxLz-Pf0AitWLhJyrfXvyY8slwjTXNuc,17
-sycommon_python_lib-0.1.56b14.dist-info/RECORD,,
+sycommon_python_lib-0.1.56b15.dist-info/METADATA,sha256=JGFO7mcs8XAlW3izcvAQEpESd-pK275n-FqUzl1FJfA,7302
+sycommon_python_lib-0.1.56b15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sycommon_python_lib-0.1.56b15.dist-info/entry_points.txt,sha256=q_h2nbvhhmdnsOUZEIwpuoDjaNfBF9XqppDEmQn9d_A,46
+sycommon_python_lib-0.1.56b15.dist-info/top_level.txt,sha256=98CJ-cyM2WIKxLz-Pf0AitWLhJyrfXvyY8slwjTXNuc,17
+sycommon_python_lib-0.1.56b15.dist-info/RECORD,,