sycommon-python-lib 0.1.46__py3-none-any.whl → 0.1.56b5__py3-none-any.whl

sycommon/services.py

@@ -7,6 +7,7 @@ from fastapi import FastAPI, applications
 from pydantic import BaseModel
 from typing import Any, Callable, Dict, List, Tuple, Union, Optional, AsyncGenerator
 from sycommon.config.Config import SingletonMeta
+from sycommon.logging.logger_levels import setup_logger_levels
 from sycommon.models.mqlistener_config import RabbitMQListenerConfig
 from sycommon.models.mqsend_config import RabbitMQSendConfig
 from sycommon.rabbitmq.rabbitmq_service import RabbitMQService
@@ -18,12 +19,14 @@ class Services(metaclass=SingletonMeta):
     _config: Optional[dict] = None
     _initialized: bool = False
     _registered_senders: List[str] = []
-    _mq_tasks: List[asyncio.Task] = []
     _instance: Optional['Services'] = None
     _app: Optional[FastAPI] = None
     _user_lifespan: Optional[Callable] = None
     _shutdown_lock: asyncio.Lock = asyncio.Lock()
 
+    # 用于存储待执行的异步数据库初始化任务
+    _pending_async_db_setup: List[Tuple[Callable, str]] = []
+
     def __init__(self, config: dict, app: FastAPI):
         if not Services._config:
             Services._config = config
@@ -49,33 +52,32 @@ class Services(metaclass=SingletonMeta):
         nacos_service: Optional[Callable[[dict], None]] = None,
         logging_service: Optional[Callable[[dict], None]] = None,
         database_service: Optional[Union[
-            Tuple[Callable[[dict, str], None], str],
-            List[Tuple[Callable[[dict, str], None], str]]
+            Tuple[Callable, str],
+            List[Tuple[Callable, str]]
         ]] = None,
         rabbitmq_listeners: Optional[List[RabbitMQListenerConfig]] = None,
         rabbitmq_senders: Optional[List[RabbitMQSendConfig]] = None
     ) -> FastAPI:
         load_dotenv()
-        # 保存应用实例和配置
+        setup_logger_levels()
         cls._app = app
         cls._config = config
         cls._user_lifespan = app.router.lifespan_context
-        # 设置文档
+
         applications.get_swagger_ui_html = custom_swagger_ui_html
         applications.get_redoc_html = custom_redoc_html
-        # 设置app.state host, port
+
         if not cls._config:
             config = yaml.safe_load(open('app.yaml', 'r', encoding='utf-8'))
             cls._config = config
-        # 使用config
+
         app.state.config = {
             "host": cls._config.get('Host', '0.0.0.0'),
             "port": cls._config.get('Port', 8080),
             "workers": cls._config.get('Workers', 1),
-            "h11_max_incomplete_event_size": cls._config.get('H11MaxIncompleteEventSize', 1024 * 1024 * 1024)
+            "h11_max_incomplete_event_size": cls._config.get('H11MaxIncompleteEventSize', 1024 * 1024 * 10)
         }
 
-        # 立即配置非异步服务（在应用启动前）
         if middleware:
             middleware(app, config)
 
@@ -85,25 +87,62 @@ class Services(metaclass=SingletonMeta):
         if logging_service:
             logging_service(config)
 
+        # ========== 处理数据库服务 ==========
+        # 清空之前的待执行列表（防止热重载时重复）
+        cls._pending_async_db_setup = []
+
         if database_service:
-            cls._setup_database_static(database_service, config)
+            # 解析配置并区分同步/异步
+            items = [database_service] if isinstance(
+                database_service, tuple) else database_service
+            for item in items:
+                db_setup_func, db_name = item
+                if asyncio.iscoroutinefunction(db_setup_func):
+                    # 如果是异步函数，加入待执行列表
+                    logging.info(f"检测到异步数据库服务: {db_name}，将在应用启动时初始化")
+                    cls._pending_async_db_setup.append(item)
+                else:
+                    # 如果是同步函数，立即执行
+                    logging.info(f"执行同步数据库服务: {db_name}")
+                    try:
+                        db_setup_func(config, db_name)
+                    except Exception as e:
+                        logging.error(
+                            f"同步数据库服务 {db_name} 初始化失败: {e}", exc_info=True)
+                        raise
 
         # 创建组合生命周期管理器
         @asynccontextmanager
         async def combined_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
             # 1. 执行Services自身的初始化
             instance = cls(config, app)
-            has_listeners = bool(
+
+            # ========== 执行挂起的异步数据库初始化 ==========
+            if cls._pending_async_db_setup:
+                logging.info("开始执行异步数据库初始化...")
+                for db_setup_func, db_name in cls._pending_async_db_setup:
+                    try:
+                        await db_setup_func(config, db_name)
+                        logging.info(f"异步数据库服务 {db_name} 初始化成功")
+                    except Exception as e:
+                        logging.error(
+                            f"异步数据库服务 {db_name} 初始化失败: {e}", exc_info=True)
+                        raise
+
+            # ========== 初始化 MQ ==========
+            has_valid_listeners = bool(
                 rabbitmq_listeners and len(rabbitmq_listeners) > 0)
-            has_senders = bool(rabbitmq_senders and len(rabbitmq_senders) > 0)
+            has_valid_senders = bool(
+                rabbitmq_senders and len(rabbitmq_senders) > 0)
 
             try:
-                await instance._setup_mq_async(
-                    rabbitmq_listeners=rabbitmq_listeners,
-                    rabbitmq_senders=rabbitmq_senders,
-                    has_listeners=has_listeners,
-                    has_senders=has_senders
-                )
+                if has_valid_listeners or has_valid_senders:
+                    await instance._setup_mq_async(
+                        rabbitmq_listeners=rabbitmq_listeners if has_valid_listeners else None,
+                        rabbitmq_senders=rabbitmq_senders if has_valid_senders else None,
+                        has_listeners=has_valid_listeners,
+                        has_senders=has_valid_senders
+                    )
                 cls._initialized = True
                 logging.info("Services初始化完成")
             except Exception as e:
@@ -115,28 +154,18 @@ class Services(metaclass=SingletonMeta):
             # 2. 执行用户定义的生命周期
             if cls._user_lifespan:
                 async with cls._user_lifespan(app):
-                    yield  # 应用运行阶段
+                    yield
             else:
-                yield  # 没有用户生命周期时直接 yield
+                yield
 
             # 3. 执行Services的关闭逻辑
             await cls.shutdown()
             logging.info("Services已关闭")
 
-        # 设置组合生命周期
         app.router.lifespan_context = combined_lifespan
-
         return app
 
-    @staticmethod
-    def _setup_database_static(database_service, config):
-        """静态方法：设置数据库服务"""
-        if isinstance(database_service, tuple):
-            db_setup, db_name = database_service
-            db_setup(config, db_name)
-        elif isinstance(database_service, list):
-            for db_setup, db_name in database_service:
-                db_setup(config, db_name)
+    # 移除了 _setup_database_static，因为逻辑已内联到 plugins 中
 
     async def _setup_mq_async(
         self,
@@ -145,53 +174,47 @@ class Services(metaclass=SingletonMeta):
         has_listeners: bool = False,
         has_senders: bool = False,
     ):
-        """异步设置MQ相关服务（适配新的RabbitMQService）"""
-        # 初始化RabbitMQ服务，传递状态
+        """异步设置MQ相关服务"""
+        if not (has_listeners or has_senders):
+            logging.info("无RabbitMQ监听器/发送器配置，跳过RabbitMQService初始化")
+            return
+
         RabbitMQService.init(self._config, has_listeners, has_senders)
 
-        # 等待RabbitMQ连接池初始化完成（最多等待30秒）
         start_time = asyncio.get_event_loop().time()
-        while not RabbitMQService._connection_pool and not RabbitMQService._is_shutdown:
+        while not (RabbitMQService._connection_pool and RabbitMQService._connection_pool._initialized) and not RabbitMQService._is_shutdown:
             if asyncio.get_event_loop().time() - start_time > 30:
-                raise TimeoutError("RabbitMQ连接池初始化超时")
+                raise TimeoutError("RabbitMQ连接池初始化超时（30秒）")
             logging.info("等待RabbitMQ连接池初始化...")
-            await asyncio.sleep(1)
+            await asyncio.sleep(0.5)
 
-        # 设置发送器，传递是否有监听器的标志
-        if rabbitmq_senders:
-            # 判断是否有监听器，如果有遍历监听器列表，队列名一样将prefetch_count属性设置到发送器对象中
-            if rabbitmq_listeners:
+        if has_senders and rabbitmq_senders:
+            if has_listeners and rabbitmq_listeners:
                 for sender in rabbitmq_senders:
                     for listener in rabbitmq_listeners:
                         if sender.queue_name == listener.queue_name:
                             sender.prefetch_count = listener.prefetch_count
             await self._setup_senders_async(rabbitmq_senders, has_listeners)
 
-        # 设置监听器，传递是否有发送器的标志
-        if rabbitmq_listeners:
+        if has_listeners and rabbitmq_listeners:
             await self._setup_listeners_async(rabbitmq_listeners, has_senders)
 
-        # 验证初始化结果
         if has_listeners:
-            # 异步获取客户端数量（适配新的RabbitMQService）
-            listener_count = len(RabbitMQService._clients)
+            listener_count = len(RabbitMQService._consumer_tasks)
             logging.info(f"监听器初始化完成，共启动 {listener_count} 个消费者")
             if listener_count == 0:
-                logging.warning("未成功初始化任何监听器，请检查配置")
+                logging.warning("未成功初始化任何监听器，请检查配置或MQ服务状态")
 
     async def _setup_senders_async(self, rabbitmq_senders, has_listeners: bool):
-        """设置发送器（适配新的RabbitMQService异步方法）"""
+        """设置发送器"""
         Services._registered_senders = [
             sender.queue_name for sender in rabbitmq_senders]
-
-        # 将是否有监听器的信息传递给RabbitMQService（异步调用）
         await RabbitMQService.setup_senders(rabbitmq_senders, has_listeners)
-        # 更新已注册的发送器（从RabbitMQService获取实际注册的名称）
         Services._registered_senders = RabbitMQService._sender_client_names
         logging.info(f"已注册的RabbitMQ发送器: {Services._registered_senders}")
 
     async def _setup_listeners_async(self, rabbitmq_listeners, has_senders: bool):
-        """设置监听器（适配新的RabbitMQService异步方法）"""
+        """设置监听器"""
         await RabbitMQService.setup_listeners(rabbitmq_listeners, has_senders)
 
     @classmethod
@@ -202,7 +225,7 @@ class Services(metaclass=SingletonMeta):
         max_retries: int = 3,
         retry_delay: float = 1.0, **kwargs
     ) -> None:
-        """发送消息，添加重试机制（适配新的RabbitMQService异步API）"""
+        """发送消息"""
         if not cls._initialized or not cls._loop:
             logging.error("Services not properly initialized!")
             raise ValueError("服务未正确初始化")
@@ -213,18 +236,15 @@ class Services(metaclass=SingletonMeta):
 
         for attempt in range(max_retries):
             try:
-                # 验证发送器是否注册
                 if queue_name not in cls._registered_senders:
                     cls._registered_senders = RabbitMQService._sender_client_names
                     if queue_name not in cls._registered_senders:
                         raise ValueError(f"发送器 {queue_name} 未注册")
 
-                # 获取发送器（适配新的异步get_sender方法）
                 sender = await RabbitMQService.get_sender(queue_name)
                 if not sender:
                     raise ValueError(f"发送器 '{queue_name}' 不存在或连接无效")
 
-                # 发送消息（调用RabbitMQService的异步send_message）
                 await RabbitMQService.send_message(data, queue_name, **kwargs)
                 logging.info(f"消息发送成功（尝试 {attempt+1}/{max_retries}）")
                 return
@@ -234,35 +254,18 @@ class Services(metaclass=SingletonMeta):
                     logging.error(
                         f"消息发送失败（已尝试 {max_retries} 次）: {str(e)}", exc_info=True)
                     raise
-
                 logging.warning(
-                    f"消息发送失败（尝试 {attempt+1}/{max_retries}）: {str(e)}，"
-                    f"{retry_delay}秒后重试..."
-                )
+                    f"消息发送失败（尝试 {attempt+1}/{max_retries}）: {str(e)}，{retry_delay}秒后重试...")
                 await asyncio.sleep(retry_delay)
 
     @classmethod
     async def shutdown(cls):
-        """关闭所有服务（线程安全，适配新的RabbitMQService关闭逻辑）"""
+        """关闭所有服务"""
         async with cls._shutdown_lock:
             if RabbitMQService._is_shutdown:
                 logging.info("RabbitMQService已关闭，无需重复操作")
                 return
-
-            # 取消所有MQ任务
-            for task in Services._mq_tasks:
-                if not task.done():
-                    task.cancel()
-                    try:
-                        await task
-                    except asyncio.CancelledError:
-                        logging.info(f"MQ任务 {task.get_name()} 已取消")
-
-            # 关闭RabbitMQ服务（异步调用）
             await RabbitMQService.shutdown()
-
-            # 清理全局状态
             cls._initialized = False
             cls._registered_senders.clear()
-            cls._mq_tasks.clear()
             logging.info("所有服务已关闭")

sycommon/synacos/feign.py

@@ -2,6 +2,9 @@ import io
 import os
 import time
 
+from sycommon.tools.merge_headers import merge_headers
+from sycommon.tools.snowflake import Snowflake
+
 import aiohttp
 from sycommon.logging.kafka_log import SYLogger
 from sycommon.synacos.nacos_service import NacosService
@@ -22,12 +25,18 @@ async def feign(service_name, api_path, method='GET', params=None, headers=None,
     try:
         # 初始化headers，确保是可修改的字典
         headers = headers.copy() if headers else {}
+        headers = merge_headers(SYLogger.get_headers(), headers)
+        if "x-traceId-header" not in headers:
+            headers["x-traceId-header"] = SYLogger.get_trace_id() or Snowflake.id
 
         # 处理JSON请求的Content-Type
         is_json_request = method.upper() in ["POST", "PUT", "PATCH"] and not (
             files or form_data or file_path)
-        if is_json_request and "Content-Type" not in headers:
-            headers["Content-Type"] = "application/json"
+        if is_json_request:
+            # 将headers的key全部转为小写，统一判断
+            headers_lower = {k.lower(): v for k, v in headers.items()}
+            if "content-type" not in headers_lower:
+                headers["Content-Type"] = "application/json"
 
         nacos_service = NacosService(None)
         version = headers.get('s-y-version')
@@ -43,7 +52,7 @@ async def feign(service_name, api_path, method='GET', params=None, headers=None,
         instance = instances[int(time.time()) % len(instances)]
 
         SYLogger.info(f"nacos:开始调用服务: {service_name}")
-        SYLogger.info(f"nacos:请求头: {headers}")
+        # SYLogger.info(f"nacos:请求头: {headers}")
 
         ip = instance.get('ip')
         port = instance.get('port')
@@ -131,13 +140,15 @@ async def _handle_feign_response(response, service_name: str, api_path: str):
     """
     try:
         status_code = response.status
-        content_type = response.headers.get('Content-Type', '').lower()
+        content_type = response.headers.get('Content-Type', '')
+        content_type = content_type.lower() if content_type else ''
+
         response_body = None
 
         if status_code == 200:
-            if 'application/json' in content_type:
+            if content_type and 'application/json' in content_type:
                 response_body = await response.json()
-            elif 'text/' in content_type:
+            elif content_type and 'text/' in content_type:
                 # 文本类型（text/plain、text/html等）：按文本读取
                 try:
                     response_body = await response.text(encoding='utf-8')
@@ -154,7 +165,7 @@ async def _handle_feign_response(response, service_name: str, api_path: str):
         else:
             # 非200状态：统一读取响应体（兼容文本/二进制错误信息）
             try:
-                if 'application/json' in content_type:
+                if content_type and 'application/json' in content_type:
                     response_body = await response.json()
                 else:
                     response_body = await response.text(encoding='utf-8', errors='ignore')

sycommon/synacos/feign_client.py

@@ -5,6 +5,9 @@ import inspect
 from typing import Any, Dict, Optional, Literal, Type, TypeVar
 from urllib.parse import urljoin
 
+from sycommon.tools.merge_headers import merge_headers
+from sycommon.tools.snowflake import Snowflake
+
 import aiohttp
 from pydantic import BaseModel
 from sycommon.synacos.param import Body, Cookie, File, Form, Header, Param, Path, Query
@@ -26,6 +29,9 @@ def feign_client(
     default_headers: Optional[Dict[str, str]] = None
 ):
     default_headers = default_headers or {}
+    default_headers = {k.lower(): v for k, v in default_headers.items()}
+    default_headers = merge_headers(SYLogger.get_headers(), default_headers)
+    default_headers["x-traceId-header"] = SYLogger.get_trace_id() or Snowflake.id
 
     def decorator(cls):
         class FeignClient:
@@ -33,7 +39,8 @@ def feign_client(
                 self.service_name = service_name
                 self.path_prefix = path_prefix
                 self.default_timeout = default_timeout
-                self.default_headers = default_headers.copy()
+                self.default_headers = {
+                    k.lower(): v for k, v in default_headers.copy().items()}
                 self.nacos_manager: Optional[NacosService] = None
                 self.session: Optional[aiohttp.ClientSession] = None
 
@@ -62,7 +69,8 @@ def feign_client(
                         method = request_meta.get("method", "GET").upper()
                         path = request_meta.get("path", "")
                         is_upload = request_meta.get("is_upload", False)
-                        method_headers = request_meta.get("headers", {})
+                        method_headers = {
+                            k.lower(): v for k, v in request_meta.get("headers", {}).items()}
                         timeout = request_meta.get(
                             "timeout", self.default_timeout)
 
@@ -152,11 +160,16 @@ def feign_client(
             def _build_headers(self, param_meta: Dict[str, Param], bound_args: Dict[str, Any], method_headers: Dict[str, str]) -> Dict[str, str]:
                 headers = self.default_headers.copy()
                 headers.update(method_headers)
+                headers = merge_headers(SYLogger.get_headers(), headers)
+                headers["x-traceId-header"] = SYLogger.get_trace_id() or Snowflake.id
+
+                # 处理参数中的Header类型
                 for name, meta in param_meta.items():
                     if isinstance(meta, Header) and name in bound_args:
                         value = bound_args[name]
                         if value is not None:
-                            headers[meta.get_key(name)] = str(value)
+                            header_key = meta.get_key(name).lower()
+                            headers[header_key] = str(value)
                 return headers
 
             def _replace_path_params(self, path: str, param_meta: Dict[str, Param], bound_args: Dict[str, Any]) -> str:
@@ -221,10 +234,14 @@ def feign_client(
                             value) if not isinstance(value, dict) else value)
                     return form_data
 
-                # 处理表单提交（x-www-form-urlencoded）
+                # 从headers中获取Content-Type（已小写key）
                 content_type = self.default_headers.get(
-                    "Content-Type") or method_headers.get("Content-Type", "")
-                if "application/x-www-form-urlencoded" in content_type:
+                    "content-type") or method_headers.get("content-type", "")
+                # 转为小写进行判断
+                content_type_lower = content_type.lower()
+
+                # 处理表单提交（x-www-form-urlencoded）
+                if "application/x-www-form-urlencoded" in content_type_lower:
                     form_data = {}
                     for name, value in bound_args.items():
                         meta = param_meta.get(name)
@@ -270,7 +287,8 @@ def feign_client(
                 """处理响应（支持 Pydantic 模型解析）"""
                 status = response.status
                 if 200 <= status < 300:
-                    content_type = response.headers.get("Content-Type", "")
+                    content_type = response.headers.get(
+                        "content-type", "").lower()
                     if "application/json" in content_type:
                         json_data = await response.json()
                         # 若指定了 Pydantic 响应模型，自动解析
@@ -299,7 +317,7 @@ def feign_request(
         func._feign_meta = {
             "method": method.upper(),
             "path": path,
-            "headers": headers.copy() if headers else {},
+            "headers": {k.lower(): v for k, v in headers.items()} if headers else {},
             "is_upload": False,
             "timeout": timeout
         }

sycommon/synacos/nacos_service.py

@@ -11,7 +11,7 @@ import time
 import atexit
 import random
 
-from sycommon.config.Config import SingletonMeta
+from sycommon.config.Config import Config, SingletonMeta
 from sycommon.logging.kafka_log import SYLogger
 
 
@@ -40,7 +40,7 @@ class NacosService(metaclass=SingletonMeta):
             # 心跳间隔：优先从配置读取，默认15秒（可通过配置修改）
             self.heartbeat_interval = self.nacos_config.get(
                 'heartbeatInterval', 15)
-            # 心跳超时：固定设置为10秒（需求指定）
+            # 心跳超时：固定设置为15秒
             self.heartbeat_timeout = 15
             self.register_retry_interval = self.nacos_config.get(
                 'registerRetryInterval', 15)  # 注册重试间隔
@@ -75,6 +75,8 @@ class NacosService(metaclass=SingletonMeta):
                 SYLogger.info("nacos:本地开发模式，不初始化Nacos客户端")
 
             self.share_configs = self.read_configs()
+            # 设置llm相关配置
+            Config().set_attr(self.share_configs)
 
             # 配置监听器
             self._config_listeners = {}
@@ -774,6 +776,15 @@ class NacosService(metaclass=SingletonMeta):
                         # 直接执行回调（替换原线程池，配置回调通常为轻量操作）
                         callback(new_config)
                         self._config_cache[data_id] = new_config
+                        try:
+                            self.share_configs[data_id] = json.loads(
+                                new_config)
+                        except json.JSONDecodeError:
+                            try:
+                                self.share_configs[data_id] = yaml.safe_load(
+                                    new_config)
+                            except yaml.YAMLError:
+                                SYLogger.error(f"nacos:无法解析 {data_id} 的内容")
             except Exception as e:
                 SYLogger.error(f"nacos:配置监视线程异常: {str(e)}")
             self._shutdown_event.wait(check_interval)
@@ -806,6 +817,11 @@ class NacosService(metaclass=SingletonMeta):
                 return []
 
             all_instances = instances.get('hosts', [])
+            # 筛选已上线实例
+            all_instances = [
+                instance for instance in all_instances
+                if instance.get('enabled', True)  # 默认True担心阿里变更sdk
+            ]
             SYLogger.info(
                 f"nacos:共发现 {len(all_instances)} 个 {service_name} 服务实例")
 

sycommon/tools/merge_headers.py

@@ -0,0 +1,97 @@
+def merge_headers(
+    source_headers,  # 来源headers（支持多种格式：字典/MutableHeaders/键值对列表/元组）
+    target_headers,  # 目标headers（原有值需保留，同名覆盖source）
+    keep_keys=None,  # 需保留的key集合（None表示保留所有）
+    delete_keys={'content-length', 'accept',
+                 'content-type', 'sec-fetch-mode',
+                 'sec-fetch-dest', 'sec-fetch-site',
+                 'pragma', 'cache-control',
+                 'accept-encoding', 'priority'},  # 需删除的source key集合
+    encoding='utf-8'  # 字符编码（处理bytes转换）
+) -> dict:
+    """
+    合并headers，最终规则：
+    1. 所有key统一转为小写进行比较判断（完全大小写无关）
+    2. target_headers 同名key 完全覆盖 source_headers（source同名key不生效）
+    3. delete_keys 作用于source_headers：source中所有该列表内的key一律不添加（无论是否新增）
+    4. target_headers 中的key即使在delete_keys也始终保留，不受删除规则影响
+    5. 自动处理bytes/其他类型的键值转换为字符串
+    6. 最终输出的key全部为小写
+    """
+    # 初始化并统一转为小写集合
+    keep_keys = {k.lower() for k in keep_keys} if keep_keys else set()
+    delete_keys = {k.lower() for k in delete_keys} if delete_keys else set()
+
+    # 修复1：兼容 MutableHeaders/普通字典/None 等 target_headers 类型
+    if target_headers is None:
+        target_dict = {}
+    elif hasattr(target_headers, 'items'):
+        # 支持 MutableHeaders/Headers/普通字典（都有items()方法）
+        target_dict = dict(target_headers.items())
+    else:
+        # 兜底：可迭代对象转为字典
+        target_dict = dict(target_headers) if isinstance(
+            target_headers, (list, tuple)) else {}
+
+    # 标准化target_headers：key转为小写，保留原有值
+    processed_headers = {k.lower(): v for k, v in target_dict.items()}
+    target_original_keys = set(processed_headers.keys())
+
+    # 修复2：统一处理 source_headers 格式，确保是键值对迭代器
+    # 步骤1：将source_headers转为标准的键值对列表
+    if source_headers is None:
+        source_kv_list = []
+    elif hasattr(source_headers, 'items'):
+        # 字典/MutableHeaders → 转为键值对列表
+        source_kv_list = list(source_headers.items())
+    elif isinstance(source_headers, (list, tuple)):
+        # 列表/元组 → 校验并过滤合法的键值对（仅保留长度为2的元组/列表）
+        source_kv_list = []
+        for item in source_headers:
+            if isinstance(item, (list, tuple)) and len(item) == 2:
+                source_kv_list.append(item)
+            else:
+                # 跳过非法格式（如长度≠2的元素），避免解包报错
+                continue
+    else:
+        # 其他类型 → 空列表（避免迭代报错）
+        source_kv_list = []
+
+    # 处理来源headers的键值转换和合并（遍历标准化后的键值对）
+    for key, value in source_kv_list:
+        # 转换key为字符串并统一转为小写（判断用）
+        if not isinstance(key, str):
+            try:
+                key = key.decode(encoding, errors='replace') if isinstance(
+                    key, bytes) else str(key)
+            except Exception:
+                # 极端情况：无法转换的key直接跳过
+                continue
+
+        key_lower = key.lower()
+
+        # 转换value为字符串
+        if not isinstance(value, str):
+            try:
+                value = value.decode(encoding, errors='replace') if isinstance(
+                    value, bytes) else str(value)
+            except Exception:
+                # 无法转换的value设为空字符串
+                value = ""
+
+        # 过滤1：source的key在删除列表 → 直接跳过
+        if key_lower in delete_keys:
+            continue
+
+        # 过滤2：仅保留指定的key（如果设置了keep_keys）
+        if keep_keys and key_lower not in keep_keys:
+            continue
+
+        # 过滤3：target已有同名key → 直接跳过（target值覆盖source）
+        if key_lower in target_original_keys:
+            continue
+
+        # 仅添加符合条件的key-value（最终key为小写）
+        processed_headers[key_lower] = value
+
+    return processed_headers