sycommon-python-lib 0.1.56b5__py3-none-any.whl → 0.1.57b4__py3-none-any.whl

sycommon/synacos/nacos_service_discovery.py

@@ -0,0 +1,157 @@
+import threading
+from typing import List, Dict
+from sycommon.logging.kafka_log import SYLogger
+from sycommon.synacos.nacos_client_base import NacosClientBase
+from sycommon.synacos.nacos_service_registration import NacosServiceRegistration
+
+
+class NacosServiceDiscovery:
+    """Nacos服务发现类 - 负责服务实例发现和轮询"""
+
+    def __init__(self, client_base: NacosClientBase):
+        self.client_base = client_base
+
+        # 轮询管理
+        self._round_robin_index = 0
+        self._round_robin_lock = threading.Lock()
+
+        # 连接监控配置
+        self.connection_check_interval = self.client_base.nacos_config.get(
+            'connectionCheckInterval', 30)
+        self._monitor_thread_started = False
+        self._monitor_thread_lock = threading.Lock()
+
+    def discover_services(self, service_name: str, group: str = "DEFAULT_GROUP", version: str = None) -> List[Dict]:
+        """发现服务实例列表 (与Java格式兼容)"""
+        if not self.client_base.ensure_client_connected():
+            return []
+
+        return self.get_service_instances(service_name, group, version)
+
+    def get_service_instances(self, service_name: str, group: str = "DEFAULT_GROUP", target_version: str = None) -> List[Dict]:
+        """
+        获取服务实例列表，并按照以下优先级规则筛选：
+        1. 相同版本号的实例
+        2. 无版本号的实例
+        3. 所有实例中轮询
+        """
+        try:
+            namespace_id = self.client_base.nacos_config['namespaceId']
+            instances = self.client_base.nacos_client.list_naming_instance(
+                service_name,
+                namespace_id=namespace_id,
+                group_name=group,
+                healthy_only=True,
+            )
+
+            if not instances or 'hosts' not in instances:
+                SYLogger.info(f"nacos:未发现 {service_name} 的服务实例")
+                return []
+
+            all_instances = instances.get('hosts', [])
+            all_instances = [
+                instance for instance in all_instances
+                if instance.get('enabled', True)
+            ]
+            SYLogger.info(
+                f"nacos:共发现 {len(all_instances)} 个 {service_name} 服务实例")
+
+            version_to_use = target_version
+
+            if version_to_use:
+                same_version_instances = [
+                    instance for instance in all_instances
+                    if instance.get('metadata', {}).get('version') == version_to_use
+                ]
+
+                if same_version_instances:
+                    SYLogger.info(
+                        f"nacos:筛选出 {len(same_version_instances)} 个与当前版本({version_to_use})匹配的实例")
+                    return same_version_instances
+
+                no_version_instances = [
+                    instance for instance in all_instances
+                    if 'version' not in instance.get('metadata', {})
+                ]
+
+                if no_version_instances:
+                    SYLogger.info(
+                        f"nacos:未找到相同版本({version_to_use})的实例，筛选出 {len(no_version_instances)} 个无版本号的实例")
+                    return no_version_instances
+            else:
+                no_version_instances = [
+                    instance for instance in all_instances
+                    if 'version' not in instance.get('metadata', {})
+                ]
+
+                if no_version_instances:
+                    # 从通用实例中轮询
+                    with self._round_robin_lock:
+                        selected_index = self._round_robin_index % len(
+                            no_version_instances)
+                        self._round_robin_index = (
+                            selected_index + 1) % len(no_version_instances)
+
+                    SYLogger.info(
+                        f"nacos:无版本请求，从 {len(no_version_instances)} 个通用实例中选择")
+                    return [no_version_instances[selected_index]]
+
+            SYLogger.info(
+                f"nacos:使用轮询方式从 {len(all_instances)} 个实例中选择")
+
+            with self._round_robin_lock:
+                selected_index = self._round_robin_index % len(all_instances)
+                self._round_robin_index = (
+                    selected_index + 1) % len(all_instances)
+
+            return [all_instances[selected_index]]
+
+        except Exception as e:
+            SYLogger.error(f"nacos:服务发现失败: {service_name}: {str(e)}")
+            return []
+
+    def monitor_connection(self, registration: NacosServiceRegistration):
+        """连接监控线程"""
+        with self._monitor_thread_lock:
+            if self.client_base._shutdown_event.is_set() or self._monitor_thread_started:
+                SYLogger.warning("nacos:监控线程已启动/已关闭，拒绝重复启动")
+                return
+            self._monitor_thread_started = True
+
+        check_interval = self.connection_check_interval
+        SYLogger.info(
+            f"nacos:连接监控线程启动 - 线程ID: {threading.current_thread().ident}")
+
+        while not self.client_base._shutdown_event.is_set():
+            try:
+                if not self.client_base.is_connected:
+                    SYLogger.warning("nacos:客户端未连接，尝试重新初始化")
+                    self.client_base.ensure_client_connected()
+                else:
+                    current_registered = registration.check_service_registered()
+
+                    if current_registered != registration.registered:
+                        registration.registered = current_registered
+                        if not current_registered:
+                            SYLogger.warning("nacos:服务实例未注册，触发单次重新注册")
+                            retry_thread = threading.Thread(
+                                target=registration.register,
+                                args=(True,),
+                                daemon=True,
+                                name="NacosSingleRetryThread"
+                            )
+                            retry_thread.start()
+                        else:
+                            SYLogger.info("nacos:服务实例已注册，触发单次验证")
+                            registration.verify_registration()
+
+                self.client_base._shutdown_event.wait(check_interval)
+
+            except Exception as e:
+                SYLogger.error(f"nacos:连接监控异常: {str(e)}")
+                self.client_base._shutdown_event.wait(5)
+
+        with self._monitor_thread_lock:
+            self._monitor_thread_started = False
+        SYLogger.info(
+            f"nacos:连接监控线程退出 - 线程ID: {threading.current_thread().ident}")

sycommon/synacos/nacos_service_registration.py

@@ -0,0 +1,270 @@
+import threading
+import time
+import atexit
+from sycommon.logging.kafka_log import SYLogger
+from sycommon.synacos.nacos_client_base import NacosClientBase
+
+
+class NacosServiceRegistration:
+    """Nacos服务注册类 - 负责服务注册、注销和状态验证"""
+
+    def __init__(self, client_base: NacosClientBase, service_name: str, real_ip: str, port: int, version: str):
+        self.client_base = client_base
+        self.service_name = service_name
+        self.real_ip = real_ip
+        self.port = port
+        self.version = version
+
+        # 注册配置
+        self.register_retry_interval = self.client_base.nacos_config.get(
+            'registerRetryInterval', 15)
+        self.long_term_retry_delay = self.client_base.nacos_config.get(
+            'longTermRetryDelay', 30)
+        self.max_long_term_retries = self.client_base.nacos_config.get(
+            'maxLongTermRetries', -1)
+
+        # 验证配置
+        self.registration_verify_count = self.client_base.nacos_config.get(
+            'registrationVerifyCount', 1)
+        self.registration_verify_interval = self.client_base.nacos_config.get(
+            'registrationVerifyInterval', 1)
+        self.registration_post_delay = self.client_base.nacos_config.get(
+            'registrationPostDelay', 3)
+
+        # 状态管理
+        self.registered = False
+        self._long_term_retry_count = 0
+        self._verify_lock = threading.Lock()
+        self._last_verify_time = 0
+        self._atexit_registered = False
+
+    def _cleanup_stale_instance(self):
+        """清理可能存在的残留实例"""
+        if not self.client_base.is_connected:
+            return
+
+        try:
+            self.client_base.nacos_client.remove_naming_instance(
+                service_name=self.service_name,
+                ip=self.real_ip,
+                port=int(self.port),
+                cluster_name="DEFAULT"
+            )
+            SYLogger.warning(f"nacos:清理残留实例: {self.real_ip}:{self.port}")
+        except Exception as e:
+            SYLogger.error(f"nacos:清理残留实例异常: {e}")
+
+    def check_service_registered(self) -> bool:
+        """检查服务是否已注册（基于实例列表）"""
+        if not self.client_base.enable_register_nacos:
+            return True
+
+        if not self.client_base.ensure_client_connected():
+            return False
+
+        try:
+            namespace_id = self.client_base.nacos_config['namespaceId']
+            instances = self.client_base.nacos_client.list_naming_instance(
+                service_name=self.service_name,
+                namespace_id=namespace_id,
+                group_name="DEFAULT_GROUP",
+                healthy_only=True,
+            )
+
+            found = False
+            for instance in instances.get('hosts', []):
+                if (instance.get('ip') == self.real_ip and
+                        instance.get('port') == int(self.port)):
+                    SYLogger.info(f"nacos:找到已注册实例: {self.real_ip}:{self.port}")
+                    found = True
+                    break
+
+            if not found:
+                SYLogger.warning(f"nacos:未找到注册实例: {self.real_ip}:{self.port}")
+
+            self.registered = found
+            return found
+        except Exception as e:
+            SYLogger.error(f"nacos:检查服务注册状态失败: {e}")
+            return False
+
+    def verify_registration(self) -> bool:
+        """多次验证服务是否成功注册（加锁防止重复执行）"""
+        if self._verify_lock.locked():
+            SYLogger.warning("nacos:注册验证已在执行中，跳过重复调用")
+            return self.registered
+
+        with self._verify_lock:
+            current_time = time.time()
+            if current_time - self._last_verify_time < 15:  # 15秒冷却
+                return True
+
+            success_count = 0
+            verify_count = self.registration_verify_count
+            SYLogger.info(
+                f"nacos:开始验证服务注册状态，共验证 {verify_count} 次，间隔 {self.registration_verify_interval} 秒")
+
+            self._last_verify_time = current_time
+
+            for i in range(verify_count):
+                if self.check_service_registered():
+                    success_count += 1
+
+                if i < verify_count - 1:
+                    self.client_base._shutdown_event.wait(
+                        self.registration_verify_interval)
+                    if self.client_base._shutdown_event.is_set():
+                        SYLogger.warning("nacos:应用正在关闭，终止注册验证")
+                        break
+
+            pass_threshold = verify_count / 2
+            result = success_count >= pass_threshold
+
+            if result:
+                SYLogger.info(
+                    f"nacos:服务注册验证成功，{success_count}/{verify_count} 次验证通过")
+            else:
+                SYLogger.error(
+                    f"nacos:服务注册验证失败，仅 {success_count}/{verify_count} 次验证通过")
+
+            return result
+
+    def register(self, force: bool = False) -> bool:
+        """注册服务到Nacos"""
+        if self.registered and not force and self.check_service_registered():
+            return True
+
+        if self.registered and not force:
+            self.registered = False
+            SYLogger.warning("nacos:本地状态显示已注册，但Nacos中未找到服务实例，准备重新注册")
+
+        metadata = {
+            "ignore-metrics": "true",
+        }
+        if self.version:
+            metadata["version"] = self.version
+
+        for attempt in range(self.client_base.max_retries):
+            if not self.client_base.ensure_client_connected():
+                return False
+
+            try:
+                self.client_base.nacos_client.add_naming_instance(
+                    service_name=self.service_name,
+                    ip=self.real_ip,
+                    port=int(self.port),
+                    metadata=metadata,
+                    cluster_name="DEFAULT",
+                    healthy=True,
+                    ephemeral=True,
+                    heartbeat_interval=15  # 心跳间隔默认15秒
+                )
+                SYLogger.info(
+                    f"nacos:服务 {self.service_name} 注册请求已发送: {self.real_ip}:{self.port}")
+
+                if not self._atexit_registered:
+                    atexit.register(self.deregister_service)
+                    self._atexit_registered = True
+
+                return True
+            except Exception as e:
+                if "signal only works in main thread" in str(e):
+                    return True
+                elif attempt < self.client_base.max_retries - 1:
+                    SYLogger.warning(
+                        f"nacos:服务注册失败 (尝试 {attempt+1}/{self.client_base.max_retries}): {e}")
+                    time.sleep(self.client_base.retry_delay)
+                else:
+                    SYLogger.error(f"nacos:服务注册失败，已达到最大重试次数: {e}")
+                    return False
+
+    def register_with_retry(self) -> bool:
+        """带重试机制的服务注册（基于实例列表检查）"""
+        retry_count = 0
+        last_error = None
+        self.registered = False
+        # 首次注册尝试标记
+        first_attempt = True
+
+        while (not self.registered) and (self.max_long_term_retries < 0 or retry_count < self.max_long_term_retries):
+            if self.registered:
+                return True
+
+            try:
+                register_success = self.register(force=True)
+                if not register_success:
+                    raise RuntimeError("nacos:服务注册请求失败")
+
+                SYLogger.info(
+                    f"nacos:服务注册请求已发送，{'首次启动信任注册，跳过阻塞验证' if first_attempt else f'延迟 {self.registration_post_delay} 秒后开始验证'}")
+
+                # 核心逻辑：首次注册跳过阻塞验证，非首次按原逻辑
+                if first_attempt:
+                    # 首次注册：直接标记成功，不阻塞
+                    self.registered = True
+                    self.client_base._client_initialized = True
+                    self.client_base._shutdown_event.set()
+                    self.client_base._shutdown_event.clear()
+                    self._long_term_retry_count = 0
+
+                    SYLogger.info(f"nacos:首次启动信任注册成功: {self.service_name}")
+                    first_attempt = False  # 标记为非首次
+                    return True
+                else:
+                    # 非首次/重试：保留原有阻塞验证逻辑
+                    time.sleep(self.registration_post_delay)
+                    registered = self.verify_registration()
+                    self.registered = registered
+
+                    if self.registered:
+                        self.client_base._client_initialized = True
+                        self.client_base._shutdown_event.set()
+                        self.client_base._shutdown_event.clear()
+                        self._long_term_retry_count = 0
+
+                        SYLogger.info(
+                            f"nacos:服务注册成功并通过验证: {self.service_name}")
+                        return True
+                    else:
+                        raise RuntimeError("nacos:服务注册验证失败")
+
+            except Exception as e:
+                last_error = str(e)
+                retry_count += 1
+                first_attempt = False  # 失败后标记为非首次
+                delay = min(self.register_retry_interval,
+                            self.client_base.max_retry_delay)
+
+                SYLogger.warning(
+                    f"nacos:服务注册尝试 {retry_count} 失败: {last_error}，{delay}秒后重试")
+                time.sleep(delay)
+
+        if self.registered:
+            return True
+
+        if last_error:
+            SYLogger.error(f"nacos:服务注册失败，最终错误: {last_error}")
+        else:
+            SYLogger.error(f"nacos:服务注册失败，已达到最大重试次数: {self.service_name}")
+
+        return False
+
+    def deregister_service(self):
+        """从Nacos注销服务"""
+        if not self.registered or not self.client_base.is_connected:
+            return
+
+        SYLogger.info("nacos:正在注销服务...")
+        try:
+            self.client_base.nacos_client.remove_naming_instance(
+                service_name=self.service_name,
+                ip=self.real_ip,
+                port=int(self.port),
+                cluster_name="DEFAULT"
+            )
+            self.registered = False
+            SYLogger.info(f"nacos:服务 {self.service_name} 已注销")
+        except Exception as e:
+            SYLogger.error(f"nacos:注销服务时发生错误: {e}")
+        finally:
+            self.client_base._shutdown_event.set()

sycommon/tools/env.py

@@ -0,0 +1,62 @@
+import os
+
+
+def _normalize_env_key(key: str) -> str:
+    """
+    环境变量名标准化：
+    1. 转小写
+    2. 中划线(-)和下划线(_)统一替换为下划线(_)
+    :param key: 原始环境变量名
+    :return: 标准化后的key
+    """
+    return key.lower().replace('-', '_')
+
+
+def check_env_flag(target_keys: list, default: str = 'false') -> bool:
+    """
+    检查环境变量是否为"true"（自动兼容：大小写、中划线/下划线）
+    :param target_keys: 目标变量名列表（如 ['REGISTER-NACOS']，无需传双key）
+    :param default: 默认值（未找到变量时使用）
+    :return: 布尔值
+    """
+    # 1. 标准化目标key（小写+统一下划线）
+    target_keys_normalized = [_normalize_env_key(k) for k in target_keys]
+
+    # 2. 遍历所有环境变量，标准化后匹配
+    for env_key, env_val in os.environ.items():
+        env_key_normalized = _normalize_env_key(env_key)
+        if env_key_normalized in target_keys_normalized:
+            # 3. 值去空格 + 转小写 判断
+            return env_val.strip().lower() == 'true'
+
+    # 4. 未找到变量时，判断默认值
+    return default.strip().lower() == 'true'
+
+
+def get_env_var(key: str, default='', case_insensitive: bool = True) -> str:
+    """
+    获取环境变量值（自动兼容：大小写、中划线/下划线）
+    :param key: 目标环境变量名（如 'REGISTER-NACOS'/'version'）
+    :param default: 无匹配时的默认值，默认空字符串
+    :param case_insensitive: 是否忽略变量名大小写（默认True，建议保持）
+    :return: 匹配到的环境变量值 / 默认值
+    """
+    if case_insensitive:
+        # 标准化目标key（小写+统一下划线）
+        target_key_normalized = _normalize_env_key(key)
+
+        # 遍历环境变量，标准化后匹配
+        for env_key, env_val in os.environ.items():
+            env_key_normalized = _normalize_env_key(env_key)
+            if env_key_normalized == target_key_normalized:
+                return env_val
+        return default
+    else:
+        # 不忽略大小写时，仅自动兼容中划线/下划线
+        target_key_1 = key  # 原始key
+        target_key_2 = key.replace(
+            '-', '_') if '-' in key else key.replace('_', '-')  # 替换格式的key
+        val = os.getenv(target_key_1)
+        if val is not None:
+            return val
+        return os.getenv(target_key_2, default)

sycommon/tools/merge_headers.py

@@ -95,3 +95,23 @@ def merge_headers(
         processed_headers[key_lower] = value
 
     return processed_headers
+
+
+def get_header_value(headers: list, target_key: str, default=None):
+    """
+    从列表中查找指定 header 的值
+
+    Args:
+        headers: header 列表，例如 [('Content-Type', 'application/json'), ...]
+        target_key: 要查找的 key
+        default: 如果没找到返回的默认值
+    """
+    if not headers:
+        return default
+
+    for item in headers:
+        # 兼容 list 和 tuple，确保长度为2
+        if isinstance(item, (list, tuple)) and len(item) == 2 and item[0] == target_key:
+            return item[1]
+
+    return default