mdbq 3.10.9__py3-none-any.whl → 3.10.11__py3-none-any.whl

mdbq/mysql/uploader.py

@@ -1,17 +1,3 @@
-"""
-MySQL数据上传工具类
-
-这个模块提供了一个用于将数据上传到MySQL数据库的工具类。它支持以下主要功能：
-1. 自动创建数据库和表
-2. 支持数据分表存储
-3. 支持数据重复检查和更新
-4. 支持批量数据插入
-5. 支持多种事务模式
-6. 自动类型转换和验证
-7. 连接池管理
-8. 错误重试机制
-"""
-
 # -*- coding:utf-8 -*-
 import datetime
 import re
@@ -171,9 +157,7 @@ class MySQLUploader:
         """
         if hasattr(self, 'pool') and self.pool is not None and self._check_pool_health():
             return self.pool
-
         self.pool = None
-
         pool_params = {
             'creator': pymysql,
             'host': self.host,
@@ -189,11 +173,10 @@ class MySQLUploader:
             'write_timeout': self.write_timeout,
             'autocommit': False
         }
-
         if self.ssl:
             required_keys = {'ca', 'cert', 'key'}
             if not all(k in self.ssl for k in required_keys):
-                error_msg = "SSL配置必须包含ca、cert和key"
+                error_msg = 'SSL配置必须包含ca、cert和key'
                 logger.error(error_msg)
                 raise ValueError(error_msg)
             pool_params['ssl'] = {
@@ -202,19 +185,14 @@ class MySQLUploader:
                 'key': self.ssl['key'],
                 'check_hostname': self.ssl.get('check_hostname', False)
             }
-
         try:
             pool = PooledDB(**pool_params)
-            logger.info("连接池创建成功", {
-                '连接池': self.pool_size
-            })
+            logger.info('连接池创建成功', {'连接池': self.pool_size, 'host': self.host, 'port': self.port})
             return pool
         except Exception as e:
             self.pool = None
-            logger.error("连接池创建失败", {
-                'error': str(e)
-            })
-            raise ConnectionError(f"连接池创建失败: {str(e)}")
+            logger.error('连接池创建失败', {'error': str(e), 'host': self.host, 'port': self.port})
+            raise ConnectionError(f'连接池创建失败: {str(e)}')
 
     def _execute_with_retry(self, func):
         """
@@ -228,32 +206,17 @@ class MySQLUploader:
         def wrapper(*args, **kwargs):
             last_exception = None
             operation = func.__name__
-
-            logger.debug(f"开始执行操作: {operation}", {
-                'attempt': 1,
-                'max_retries': self.max_retries
-            })
-
+            logger.debug(f'开始执行操作: {operation}', {'max_retries': self.max_retries})
             for attempt in range(self.max_retries):
                 try:
                     result = func(*args, **kwargs)
-
                     if attempt > 0:
-                        logger.info("操作成功(重试后)", {
-                            'operation': operation,
-                            'attempts': attempt + 1
-                        })
+                        logger.info('操作成功(重试后)', {'operation': operation, 'attempts': attempt + 1})
                     else:
-                        logger.debug("操作成功", {
-                            'operation': operation
-                        })
-
+                        logger.debug('操作成功', {'operation': operation})
                     return result
-
                 except (pymysql.OperationalError, pymysql.err.MySQLError) as e:
                     last_exception = e
-
-                    # 记录详细的MySQL错误信息
                     error_details = {
                         'operation': operation,
                         'error_code': e.args[0] if e.args else None,
@@ -261,47 +224,38 @@ class MySQLUploader:
                         'attempt': attempt + 1,
                         'max_retries': self.max_retries
                     }
-
                     if attempt < self.max_retries - 1:
                         wait_time = self.retry_interval * (attempt + 1)
                         error_details['wait_time'] = wait_time
-                        logger.warning(f"数据库操作失败，准备重试 {error_details}", )
+                        logger.warning('数据库操作失败，准备重试', error_details)
                         time.sleep(wait_time)
-
-                        # 尝试重新连接
                         try:
                             self.pool = self._create_connection_pool()
-                            logger.info("成功重新建立数据库连接")
+                            logger.info('成功重新建立数据库连接')
                         except Exception as reconnect_error:
-                            logger.error("重连失败", {
-                                'error': str(reconnect_error)
-                            })
+                            logger.error('重连失败', {'error': str(reconnect_error)})
                     else:
-                        logger.error(f"操作最终失败")
-
+                        logger.error('操作最终失败', error_details)
                 except pymysql.IntegrityError as e:
-                    logger.error("完整性约束错误", {
+                    logger.error('完整性约束错误', {
                         'operation': operation,
                         'error_code': e.args[0] if e.args else None,
                         'error_message': e.args[1] if len(e.args) > 1 else None
                     })
                     raise e
-
                 except Exception as e:
                     last_exception = e
-                    logger.error("发生意外错误", {
+                    logger.error('发生意外错误', {
                         'operation': operation,
                         'error_type': type(e).__name__,
                         'error_message': str(e),
                         'error_args': e.args if hasattr(e, 'args') else None
                     })
                     break
-
-            raise last_exception if last_exception else Exception("发生未知错误")
-
+            raise last_exception if last_exception else Exception('发生未知错误')
         return wrapper
 
-    def _get_connection(self):
+    def _get_connection(self) -> pymysql.connections.Connection:
         """
         从连接池获取数据库连接
 
@@ -310,11 +264,11 @@ class MySQLUploader:
         """
         try:
             conn = self.pool.connection()
-            logger.debug("获取数据库连接")
+            logger.debug('获取数据库连接', {'host': self.host, 'port': self.port})
             return conn
         except Exception as e:
-            logger.error(f'{e}')
-            raise ConnectionError(f"连接数据库失败: {str(e)}")
+            logger.error('获取数据库连接失败', {'error': str(e)})
+            raise ConnectionError(f'连接数据库失败: {str(e)}')
 
     def _check_database_exists(self, db_name: str) -> bool:
         """
@@ -325,23 +279,19 @@ class MySQLUploader:
         :raises: 可能抛出数据库相关异常
         """
         db_name = self._validate_identifier(db_name)
-        sql = "SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = %s"
-
+        sql = 'SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = %s'
         try:
             with self._get_connection() as conn:
                 with conn.cursor() as cursor:
                     cursor.execute(sql, (db_name,))
                     exists = bool(cursor.fetchone())
-                    logger.debug(f"{db_name} 数据库已存在: {exists}")
+                    logger.debug('数据库存在检查', {'库': db_name, '存在': exists})
                     return exists
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                '库': db_name,
-                '检查数据库是否存在时出错': str(e),
-            })
+            logger.error('检查数据库是否存在时出错', {'库': db_name, '错误': str(e)})
             raise
 
-    def _create_database(self, db_name: str):
+    def _create_database(self, db_name: str) -> None:
         """
         创建数据库
 
@@ -349,19 +299,15 @@ class MySQLUploader:
         :raises: 可能抛出数据库相关异常
         """
         db_name = self._validate_identifier(db_name)
-        sql = f"CREATE DATABASE IF NOT EXISTS `{db_name}` CHARACTER SET {self.charset} COLLATE {self.collation}"
-
+        sql = f'CREATE DATABASE IF NOT EXISTS `{db_name}` CHARACTER SET {self.charset} COLLATE {self.collation}'
         try:
             with self._get_connection() as conn:
                 with conn.cursor() as cursor:
                     cursor.execute(sql)
                 conn.commit()
-                logger.info(f"`{db_name}` 数据库已创建")
+                logger.info('数据库已创建', {'库': db_name})
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                '无法创建数据库': str(e),
-                '库': db_name
-            })
+            logger.error('无法创建数据库', {'库': db_name, '错误': str(e)})
             conn.rollback()
             raise
 
@@ -376,24 +322,16 @@ class MySQLUploader:
         :raises ValueError: 如果日期格式无效或分表方式无效
         """
         try:
-            # date_obj = datetime.datetime.strptime(date_value, '%Y-%m-%d')
             date_obj = self._validate_datetime(date_value, True)
         except ValueError:
-            logger.error(sys._getframe().f_code.co_name, {
-                '无效的日期格式1': date_value,
-                '表': table_name
-            })
-            raise ValueError(f"`{table_name}` 无效的日期格式1: `{date_value}`")
-
+            logger.error('无效的日期格式', {'表': table_name, '日期值': date_value})
+            raise ValueError(f"`{table_name}` 无效的日期格式: `{date_value}`")
         if partition_by == 'year':
             return f"{table_name}_{date_obj.year}"
         elif partition_by == 'month':
             return f"{table_name}_{date_obj.year}_{date_obj.month:02d}"
         else:
-            logger.error(sys._getframe().f_code.co_name, {
-                "分表方式必须是 'year' 或 'month' 或 'None'": partition_by,
-                '表': table_name
-            })
+            logger.error('分表方式无效', {'表': table_name, '分表方式': partition_by})
             raise ValueError("分表方式必须是 'year' 或 'month' 或 'None'")
 
     def _validate_identifier(self, identifier: str) -> str:
@@ -405,36 +343,22 @@ class MySQLUploader:
         :raises ValueError: 当标识符无效时抛出
         """
         if not identifier or not isinstance(identifier, str):
-            logger.error(sys._getframe().f_code.co_name, {
-                '无效的标识符': identifier
-            })
+            logger.error('无效的标识符', {'标识符': identifier})
             raise ValueError(f"无效的标识符: `{identifier}`")
-
-        # 统一转为小写(除非明确要求大小写敏感)
         if not self.case_sensitive:
             identifier = identifier.lower()
-
-        # 移除非法字符，只保留字母、数字、下划线和美元符号
-        cleaned = re.sub(r'[^\w\u4e00-\u9fff$]', '_', identifier)
-
-        # 将多个连续的下划线替换为单个下划线, 移除开头和结尾的下划线
+        cleaned = re.sub(r'[^-\w\u4e00-\u9fff$]', '_', identifier)
         cleaned = re.sub(r'_+', '_', cleaned).strip('_')
-
         if not cleaned:
-            logger.error(sys._getframe().f_code.co_name, {
-                '无法清理异常标识符': identifier
-            })
+            logger.error('无法清理异常标识符', {'原始标识符': identifier})
             raise ValueError(f"无法清理异常标识符: `{identifier}`")
-
-        # 检查是否为MySQL保留字
         mysql_keywords = {
             'select', 'insert', 'update', 'delete', 'from', 'where', 'and', 'or',
             'not', 'like', 'in', 'is', 'null', 'true', 'false', 'between'
         }
         if cleaned.lower() in mysql_keywords:
-            logger.debug(f"存在MySQL保留字: `{cleaned}`")
+            logger.debug('存在MySQL保留字', {'标识符': cleaned})
             return f"`{cleaned}`"
-
         return cleaned
 
     def _check_table_exists(self, db_name: str, table_name: str) -> bool:
@@ -450,8 +374,8 @@ class MySQLUploader:
         if cache_key in self._table_metadata_cache:
             cached_time, result = self._table_metadata_cache[cache_key]
             if time.time() - cached_time < self.metadata_cache_ttl:
+                logger.debug('表存在缓存命中', {'库': db_name, '表': table_name, '存在': result})
                 return result
-
         db_name = self._validate_identifier(db_name)
         table_name = self._validate_identifier(table_name)
         sql = """
@@ -459,21 +383,16 @@ class MySQLUploader:
                 FROM INFORMATION_SCHEMA.TABLES 
                 WHERE TABLE_SCHEMA = %s AND TABLE_NAME = %s
                 """
-
         try:
             with self._get_connection() as conn:
                 with conn.cursor() as cursor:
                     cursor.execute(sql, (db_name, table_name))
                     result = bool(cursor.fetchone())
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                '库': db_name,
-                '表': table_name,
-                '检查数据表是否存在时发生未知错误': str(e)})
+            logger.error('检查数据表是否存在时发生未知错误', {'库': db_name, '表': table_name, '错误': str(e)})
             raise
-
-        # 执行查询并缓存结果
         self._table_metadata_cache[cache_key] = (time.time(), result)
+        logger.debug('表存在检查', {'库': db_name, '表': table_name, '存在': result})
         return result
 
     def _create_table(
@@ -485,7 +404,7 @@ class MySQLUploader:
             date_column: Optional[str] = None,
             indexes: Optional[List[str]] = None,
             allow_null: bool = False
-    ):
+    ) -> None:
         """
         创建数据表
 
@@ -500,69 +419,42 @@ class MySQLUploader:
         """
         db_name = self._validate_identifier(db_name)
         table_name = self._validate_identifier(table_name)
-
         if not set_typ:
-            logger.error(sys._getframe().f_code.co_name, {
-                '库': db_name,
-                '表': table_name,
-                'set_typ 未指定': set_typ})
+            logger.error('建表时未指定set_typ', {'库': db_name, '表': table_name})
             raise ValueError('set_typ 未指定')
-
-        # 构建列定义SQL
         column_defs = ["`id` INT NOT NULL AUTO_INCREMENT"]
-
-        # 添加其他列定义
         for col_name, col_type in set_typ.items():
-            # 跳过id列，因为已经在前面添加了
             if col_name.lower() == 'id':
                 continue
             safe_col_name = self._validate_identifier(col_name)
             col_def = f"`{safe_col_name}` {col_type}"
-
-            # 根据allow_null决定是否添加NOT NULL约束
             if not allow_null and not col_type.lower().startswith('json'):
                 col_def += " NOT NULL"
-
             column_defs.append(col_def)
-
-        # 添加主键定义
         if primary_keys:
-            # 确保id在主键中
             if 'id' not in [pk.lower() for pk in primary_keys]:
                 primary_keys = ['id'] + primary_keys
         else:
-            # 如果没有指定主键，则使用id作为主键
             primary_keys = ['id']
-
-        # 添加主键定义
         safe_primary_keys = [self._validate_identifier(pk) for pk in primary_keys]
         primary_key_sql = f", PRIMARY KEY (`{'`,`'.join(safe_primary_keys)}`)"
-
-        # 构建完整SQL
         sql = f"""
         CREATE TABLE IF NOT EXISTS `{db_name}`.`{table_name}` (
             {','.join(column_defs)}
             {primary_key_sql}
         ) ENGINE=InnoDB DEFAULT CHARSET={self.charset} COLLATE={self.collation}
         """
-
         try:
             with self._get_connection() as conn:
                 with conn.cursor() as cursor:
                     cursor.execute(sql)
-                    logger.info(f"`{db_name}`.`{table_name}`: 数据表已创建")
-
-                # 添加普通索引
+                    logger.info('数据表已创建', {'库': db_name, '表': table_name})
                 index_statements = []
-
-                # 日期列索引
                 if date_column and date_column in set_typ:
                     safe_date_col = self._validate_identifier(date_column)
                     index_statements.append(
                         f"ALTER TABLE `{db_name}`.`{table_name}` ADD INDEX `idx_{safe_date_col}` (`{safe_date_col}`)"
                     )
-
-                # 其他索引
                 if indexes:
                     for idx_col in indexes:
                         if idx_col in set_typ:
@@ -570,27 +462,19 @@ class MySQLUploader:
                             index_statements.append(
                                 f"ALTER TABLE `{db_name}`.`{table_name}` ADD INDEX `idx_{safe_idx_col}` (`{safe_idx_col}`)"
                             )
-
-                # 执行所有索引创建语句
                 if index_statements:
                     with conn.cursor() as cursor:
                         for stmt in index_statements:
                             cursor.execute(stmt)
-                            logger.debug(f"Executed index statement: {stmt}", )
-
+                            logger.debug('执行索引语句', {'SQL': stmt})
                 conn.commit()
-                logger.info(f"索引已添加: `{db_name}`.`{table_name}` -> `{indexes}`")
-
+                logger.info('索引已添加', {'库': db_name, '表': table_name, '索引': indexes})
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                '库': db_name,
-                '表': table_name,
-                '建表失败': str(e),
-            })
+            logger.error('建表失败', {'库': db_name, '表': table_name, '错误': str(e)})
             conn.rollback()
             raise
 
-    def _validate_datetime(self, value, date_type=False):
+    def _validate_datetime(self, value: str, date_type: bool = False) -> Any:
         """
         验证并标准化日期时间格式
 
@@ -614,12 +498,17 @@ class MySQLUploader:
         for fmt in formats:
             try:
                 if date_type:
-                    return pd.to_datetime(datetime.datetime.strptime(value, fmt).strftime('%Y-%m-%d'))
+                    result = pd.to_datetime(datetime.datetime.strptime(value, fmt).strftime('%Y-%m-%d'))
+                    logger.debug('日期格式化成功', {'原始': value, '格式': fmt, '结果': str(result)})
+                    return result
                 else:
-                    return datetime.datetime.strptime(value, fmt).strftime('%Y-%m-%d %H:%M:%S')
+                    result = datetime.datetime.strptime(value, fmt).strftime('%Y-%m-%d %H:%M:%S')
+                    logger.debug('日期格式化成功', {'原始': value, '格式': fmt, '结果': str(result)})
+                    return result
             except ValueError:
                 continue
-        raise ValueError(f"无效的日期格式2: `{value}`")
+        logger.error('无效的日期格式', {'值': value})
+        raise ValueError(f"无效的日期格式: `{value}`")
 
     def _validate_value(self, value: Any, column_type: str, allow_null: bool) -> Any:
         """
@@ -633,40 +522,31 @@ class MySQLUploader:
         """
         if value is None:
             if not allow_null:
+                logger.warning('字段值为None但不允许空值', {'字段类型': column_type})
                 return 'none'
             return None
-
         try:
             column_type_lower = column_type.lower()
-
-            # 处理百分比值
             if isinstance(value, str) and value.strip().endswith('%'):
                 try:
-                    # 移除百分号并转换为小数
                     percent_str = value.strip().replace('%', '')
-                    # 处理科学计数法
-                    if 'e' in percent_str.lower():
-                        percent_value = float(percent_str)
-                    else:
-                        percent_value = float(percent_str)
+                    percent_value = float(percent_str)
                     decimal_value = percent_value / 100
+                    logger.debug('百分比字符串转小数', {'原始': value, '结果': decimal_value})
                     return decimal_value
                 except ValueError:
-                    pass  # 如果不是有效的百分比数字，继续正常处理
-
+                    logger.warning('百分比字符串转小数失败', {'原始': value})
             elif 'int' in column_type_lower:
                 if isinstance(value, str):
-                    # 移除可能的逗号和空格
                     value = value.replace(',', '').strip()
-                    # 尝试转换为浮点数再转整数
                     try:
                         return int(float(value))
                     except ValueError:
+                        logger.error('字符串转整数失败', {'值': value})
                         raise ValueError(f"`{value}` -> 无法转为整数")
                 return int(value) if value is not None else None
             elif any(t in column_type_lower for t in ['float', 'double', 'decimal']):
                 if isinstance(value, str):
-                    # 处理可能包含逗号的数字字符串
                     value = value.replace(',', '')
                 return float(value) if value is not None else None
             elif 'date' in column_type_lower or 'time' in column_type_lower:
@@ -674,12 +554,12 @@ class MySQLUploader:
                     return value.strftime('%Y-%m-%d %H:%M:%S')
                 elif isinstance(value, str):
                     try:
-                        return self._validate_datetime(value)  # 使用专门的日期验证方法
+                        return self._validate_datetime(value)
                     except ValueError as e:
+                        logger.error('无效日期格式', {'值': value, '错误': str(e)})
                         raise ValueError(f"无效日期格式: `{value}` -> {str(e)}")
                 return str(value)
             elif 'char' in column_type_lower or 'text' in column_type_lower:
-                # 防止SQL注入
                 if isinstance(value, str):
                     return value.replace('\\', '\\\\').replace("'", "\\'")
                 return str(value)
@@ -688,9 +568,7 @@ class MySQLUploader:
             else:
                 return value
         except (ValueError, TypeError) as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                f'转换异常, 无法将 `{value}` 的数据类型转为: `{column_type}`': str(e),
-            })
+            logger.error('数据类型转换异常', {'值': value, '目标类型': column_type, '错误': str(e)})
             raise ValueError(f"转换异常 -> 无法将 `{value}` 的数据类型转为: `{column_type}` -> {str(e)}")
 
     def _get_table_columns(self, db_name: str, table_name: str) -> Dict[str, str]:
@@ -710,20 +588,15 @@ class MySQLUploader:
         WHERE TABLE_SCHEMA = %s AND TABLE_NAME = %s
         ORDER BY ORDINAL_POSITION
         """
-
         try:
             with self._get_connection() as conn:
                 with conn.cursor() as cursor:
                     cursor.execute(sql, (db_name, table_name))
                     set_typ = {row['COLUMN_NAME'].lower(): row['DATA_TYPE'] for row in cursor.fetchall()}
-                    logger.debug(f"`{db_name}`.`{table_name}`: 获取表的列信息: `{set_typ}`")
+                    logger.debug('获取表的列信息', {'库': db_name, '表': table_name, '列信息': set_typ})
                     return set_typ
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                '库': db_name,
-                '表': table_name,
-                '无法获取表列信息': str(e),
-            })
+            logger.error('无法获取表列信息', {'库': db_name, '表': table_name, '错误': str(e)})
             raise
 
     def _upload_to_table(
@@ -750,30 +623,32 @@ class MySQLUploader:
                 self._create_table(db_name, table_name, set_typ, primary_keys, date_column, indexes,
                                    allow_null=allow_null)
             else:
-                logger.error(sys._getframe().f_code.co_name, {
+                logger.error('数据表不存在', {
                     '库': db_name,
                     '表': table_name,
-                    '数据表不存在': table_name,
+                    'func': sys._getframe().f_code.co_name,
                 })
                 raise ValueError(f"数据表不存在: `{db_name}`.`{table_name}`")
 
         # 获取表结构并验证
         table_columns = self._get_table_columns(db_name, table_name)
         if not table_columns:
-            logger.error(sys._getframe().f_code.co_name, {
+            logger.error('获取列失败', {
                 '库': db_name,
                 '表': table_name,
-                '获取列失败': table_columns,
+                '列': self._shorten_for_log(table_columns),
+                'func': sys._getframe().f_code.co_name,
             })
             raise ValueError(f"获取列失败 `{db_name}`.`{table_name}`")
 
         # 验证数据列与表列匹配
         for col in set_typ:
             if col not in table_columns:
-                logger.error(sys._getframe().f_code.co_name, {
+                logger.error('列不存在', {
                     '库': db_name,
                     '表': table_name,
-                    '列不存在': f'{col} -> {table_columns}',
+                    '列': col,
+                    'func': sys._getframe().f_code.co_name,
                 })
                 raise ValueError(f"列不存在: `{col}` -> `{db_name}`.`{table_name}`")
 
@@ -858,11 +733,9 @@ class MySQLUploader:
                   - List[Dict[str, Any]]：将规范化列表中每个字典的键
         """
         if isinstance(data, pd.DataFrame):
-            # 处理DataFrame
             data.columns = [self._validate_identifier(col) for col in data.columns]
             return data
         elif isinstance(data, list):
-            # 处理字典列表
             return [{self._validate_identifier(k): v for k, v in item.items()} for item in data]
         return data
 
@@ -888,9 +761,10 @@ class MySQLUploader:
                 data.columns = [col.lower() for col in data.columns]
                 data = data.replace({pd.NA: None}).to_dict('records')
             except Exception as e:
-                logger.error(sys._getframe().f_code.co_name, {
-                    '数据转字典时发生错误': str(e),
-                    '数据': data,
+                logger.error('数据转字典时发生错误', {
+                    'error': str(e),
+                    'data': self._shorten_for_log(data),
+                    'func': sys._getframe().f_code.co_name,
                 })
                 raise ValueError(f"数据转字典时发生错误: {e}")
         elif isinstance(data, dict):
@@ -899,8 +773,9 @@ class MySQLUploader:
             # 将列表中的每个字典键转为小写
             data = [{k.lower(): v for k, v in item.items()} for item in data]
         else:
-            logger.error(sys._getframe().f_code.co_name, {
-                '数据结构必须是字典、列表、字典列表或dataframe': data,
+            logger.error('数据结构必须是字典、列表、字典列表或dataframe', {
+                'data': self._shorten_for_log(data),
+                'func': sys._getframe().f_code.co_name,
             })
             raise ValueError("数据结构必须是字典、列表、字典列表或dataframe")
 
@@ -943,17 +818,19 @@ class MySQLUploader:
                 if col_name not in row:
                     if not allow_null:
                         error_msg = f"行号:{row_idx} -> 缺失列: `{col_name}`"
-                        logger.error(error_msg)
+                        logger.error(error_msg, {'row': self._shorten_for_log(row)})
                         raise ValueError(error_msg)
                     prepared_row[col_name] = None
                 else:
                     try:
                         prepared_row[col_name] = self._validate_value(row[col_name], filtered_set_typ[col_name], allow_null)
                     except ValueError as e:
-                        logger.error(sys._getframe().f_code.co_name, {
+                        logger.error('数据验证失败', {
                             '列': col_name,
                             '行': row_idx,
                             '报错': str(e),
+                            'row': self._shorten_for_log(row),
+                            'func': sys._getframe().f_code.co_name,
                         })
                         raise ValueError(f"行:{row_idx}, 列:`{col_name}`-> 报错: {str(e)}")
             prepared_data.append(prepared_row)
@@ -1009,10 +886,20 @@ class MySQLUploader:
             '库': db_name,
             '表': table_name,
             '批次': batch_id,
-            '分表方式': partition_by,
-            '排重': check_duplicate,
             '传入': len(data) if hasattr(data, '__len__') else 1,
-            # '自动建表': auto_create
+            '参数': {
+                '主键': primary_keys,
+                '去重': check_duplicate,
+                '去重列': duplicate_columns,
+                '允许空值': allow_null,
+                '分表方式': partition_by,
+                '分表列': partition_date_column,
+                # '自动建表': auto_create,
+                '索引': indexes,
+                '更新旧数据': update_on_duplicate,
+                '事务模式': transaction_mode
+            },
+            '数据样例': self._shorten_for_log(data, 2)
         })
 
         try:
@@ -1020,11 +907,12 @@ class MySQLUploader:
             if partition_by:
                 partition_by = str(partition_by).lower()
                 if partition_by not in ['year', 'month']:
-                    logger.error(sys._getframe().f_code.co_name, {
+                    logger.error('分表方式必须是 "year" 或 "month" 或 "None', {
                         '库': db_name,
                         '表': table_name,
                         '批次': batch_id,
-                        '分表方式必须是 "year" 或 "month" 或 "None"': partition_by,
+                        '分表方式': partition_by,
+                        'func': sys._getframe().f_code.co_name,
                     })
                     raise ValueError("分表方式必须是 'year' 或 'month' 或 'None'")
 
@@ -1036,8 +924,9 @@ class MySQLUploader:
                 if auto_create:
                     self._create_database(db_name)
                 else:
-                    logger.error(sys._getframe().f_code.co_name, {
-                        '数据库不存在': db_name
+                    logger.error('数据库不存在', {
+                        '库': db_name,
+                        'func': sys._getframe().f_code.co_name,
                     })
                     raise ValueError(f"数据库不存在: `{db_name}`")
 
@@ -1047,11 +936,13 @@ class MySQLUploader:
                 for row in prepared_data:
                     try:
                         if partition_date_column not in row:
-                            logger.error(sys._getframe().f_code.co_name,{
+                            logger.error('异常缺失列',{
                                 '库': db_name,
                                 '表': table_name,
                                 '批次': batch_id,
-                                '异常缺失列': partition_date_column,
+                                '缺失列': partition_date_column,
+                                'row': self._shorten_for_log(row),
+                                'func': sys._getframe().f_code.co_name,
                             })
                             continue  # 跳过当前行
 
@@ -1064,11 +955,12 @@ class MySQLUploader:
                             partitioned_data[part_table] = []
                         partitioned_data[part_table].append(row)
                     except Exception as e:
-                        logger.error(sys._getframe().f_code.co_name, {
+                        logger.error('分表处理异常', {
                             '库': db_name,
                             '表': table_name,
-                            'row_data': row,
-                            '分表处理失败': str(e),
+                            'row_data': self._shorten_for_log(row),
+                            'error': str(e),
+                            'func': sys._getframe().f_code.co_name,
                         })
                         continue  # 跳过当前行
 
@@ -1082,11 +974,13 @@ class MySQLUploader:
                             indexes, batch_id, update_on_duplicate, transaction_mode
                         )
                     except Exception as e:
-                        logger.error(sys._getframe().f_code.co_name, {
+                        logger.error('分表上传异常', {
                             '库': db_name,
                             '表': table_name,
                             '分表': part_table,
-                            '分表上传失败': str(e),
+                            'error': str(e),
+                            '数据样例': self._shorten_for_log(part_data, 2),
+                            'func': sys._getframe().f_code.co_name,
                         })
                         continue  # 跳过当前分表，继续处理其他分表
             else:
@@ -1101,11 +995,13 @@ class MySQLUploader:
             success_flag = True
 
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
+            logger.error('上传过程发生全局错误', {
                 '库': db_name,
                 '表': table_name,
-                '上传过程发生全局错误': str(e),
+                'error': str(e),
                 'error_type': type(e).__name__,
+                '数据样例': self._shorten_for_log(data, 2),
+                'func': sys._getframe().f_code.co_name,
             })
         finally:
             logger.info("存储完成", {
@@ -1180,10 +1076,11 @@ class MySQLUploader:
         """验证并标准化事务模式"""
         valid_modes = ('row', 'batch', 'hybrid')
         if mode.lower() not in valid_modes:
-            logger.error(sys._getframe().f_code.co_name, {
-                '参数异常': f'transaction_mode -> {mode}',
+            logger.error('事务模式参数错误', {
+                '错误值': mode,
                 '可选值': valid_modes,
-                '自动使用默认模式': 'batch'
+                '自动使用默认模式': 'batch',
+                'func': sys._getframe().f_code.co_name,
             })
             return 'batch'
         return mode.lower()
@@ -1352,7 +1249,7 @@ class MySQLUploader:
                     batch_inserted, batch_skipped, batch_failed = self._process_batch(
                         conn, cursor, db_name, table_name, batch, all_columns,
                         sql, check_duplicate, duplicate_columns, batch_id,
-                        transaction_mode, i, len(data), update_on_duplicate
+                        transaction_mode, update_on_duplicate
                     )
 
                     # 更新总统计
@@ -1375,24 +1272,47 @@ class MySQLUploader:
             duplicate_columns: Optional[List[str]],
             batch_id: Optional[str],
             transaction_mode: str,
-            batch_index: int,
-            total_data_length: int,
             update_on_duplicate: bool = False
     ) -> Tuple[int, int, int]:
-        """处理单个批次的数据插入"""
+        """
+        处理单个批次的数据插入
+
+        :param conn: 数据库连接对象
+        :param cursor: 数据库游标对象
+        :param db_name: 数据库名
+        :param table_name: 表名
+        :param batch: 当前批次的数据（字典列表）
+        :param all_columns: 需要插入的所有列名
+        :param sql: 执行的SQL语句
+        :param check_duplicate: 是否检查重复
+        :param duplicate_columns: 排重列
+        :param batch_id: 批次ID
+        :param transaction_mode: 事务模式
+        :param update_on_duplicate: 遇到重复时是否更新
+        :return: (插入数, 跳过数, 失败数)
+        """
         batch_inserted = 0
         batch_skipped = 0
         batch_failed = 0
-
+        batch_size = len(batch)
+        logger.debug('批次插入开始', {
+            '库': db_name,
+            '表': table_name,
+            '批次ID': batch_id,
+            '批次大小': batch_size,
+            '事务模式': transaction_mode,
+            'SQL预览': sql[:200],
+            '排重': check_duplicate,
+            '排重列': duplicate_columns,
+            '允许更新': update_on_duplicate,
+            '数据样例': self._shorten_for_log(batch, 2)
+        })
         if transaction_mode == 'batch':
-            # 批量模式特殊处理 - 尝试逐行插入但保持事务
             try:
                 for row_idx, row in enumerate(batch, 1):
                     result = self._process_single_row(
-                        db_name, table_name,
-                        cursor, row, all_columns, sql,
-                        check_duplicate, duplicate_columns,
-                        update_on_duplicate
+                        db_name, table_name, cursor, row, all_columns, sql,
+                        check_duplicate, duplicate_columns, update_on_duplicate
                     )
                     if result == 'inserted':
                         batch_inserted += 1
@@ -1400,32 +1320,32 @@ class MySQLUploader:
                         batch_skipped += 1
                     else:
                         batch_failed += 1
-
-                # 批量模式最后统一提交
                 conn.commit()
-
+                logger.debug('批次插入成功', {
+                    '库': db_name,
+                    '表': table_name,
+                    '批次ID': batch_id,
+                    '插入': batch_inserted,
+                    '跳过': batch_skipped,
+                    '失败': batch_failed
+                })
             except Exception as e:
-                # 如果整个批量操作失败，回滚
                 conn.rollback()
-                batch_failed = len(batch)  # 标记整个批次失败
-                logger.error(sys._getframe().f_code.co_name, {
+                batch_failed += len(batch)
+                logger.error('批次插入失败', {
                     '库': db_name,
                     '表': table_name,
-                    '批次': f'{batch_id}  {batch_index + 1}/{total_data_length}',
-                    'error_type': type(e).__name__,
-                    '批量操作失败': str(e),
-                    '事务模式': transaction_mode,
-                    '处理方式': '整个批次回滚'
+                    '批次ID': batch_id,
+                    '错误': str(e),
+                    'SQL预览': sql[:200],
+                    '数据样例': self._shorten_for_log(batch, 2)
                 })
-
         else:  # row 或 hybrid 模式
             for row_idx, row in enumerate(batch, 1):
                 try:
                     result = self._process_single_row(
-                        db_name, table_name,
-                        cursor, row, all_columns, sql,
-                        check_duplicate, duplicate_columns,
-                        update_on_duplicate
+                        db_name, table_name, cursor, row, all_columns, sql,
+                        check_duplicate, duplicate_columns, update_on_duplicate
                     )
                     if result == 'inserted':
                         batch_inserted += 1
@@ -1433,37 +1353,41 @@ class MySQLUploader:
                         batch_skipped += 1
                     else:
                         batch_failed += 1
-
-                    # 根据模式决定提交时机
-                    if transaction_mode == 'row':
-                        conn.commit()  # 逐行提交
-                    elif transaction_mode == 'hybrid' and row_idx % 100 == 0:
-                        conn.commit()  # 每100行提交一次
-
+                    conn.commit()
+                    logger.debug('单行插入成功', {
+                        '库': db_name,
+                        '表': table_name,
+                        '批次ID': batch_id,
+                        '行号': row_idx,
+                        '插入状态': result
+                    })
                 except Exception as e:
                     conn.rollback()
                     batch_failed += 1
-                    logger.error(sys._getframe().f_code.co_name, {
+                    logger.error('单行插入失败', {
                         '库': db_name,
                         '表': table_name,
-                        '批次/当前行': f'{batch_id}  {row_idx}/{len(batch)}',
-                        'error_type': type(e).__name__,
-                        '单行插入失败': str(e),
-                        '是否排重': check_duplicate,
-                        '排重列': duplicate_columns,
-                        '事务模式': transaction_mode,
+                        '批次ID': batch_id,
+                        '行号': row_idx,
+                        '错误': str(e),
+                        'SQL预览': sql[:200],
+                        '数据': self._shorten_for_log(row)
                     })
-
-            # 混合模式最后统一提交
-            if transaction_mode == 'hybrid':
-                conn.commit()
-
+        logger.debug('批次插入结束', {
+            '库': db_name,
+            '表': table_name,
+            '批次ID': batch_id,
+            '插入': batch_inserted,
+            '跳过': batch_skipped,
+            '失败': batch_failed,
+            '数据样例': self._shorten_for_log(batch, 2)
+        })
         return batch_inserted, batch_skipped, batch_failed
 
     def _process_single_row(
             self,
-            db_name,
-            table_name,
+            db_name: str,
+            table_name: str,
             cursor,
             row: Dict,
             all_columns: List[str],
@@ -1472,95 +1396,87 @@ class MySQLUploader:
             duplicate_columns: Optional[List[str]],
             update_on_duplicate: bool = False
     ) -> str:
-        """处理单行数据插入"""
-        try:
-            # 准备参数
-            row_values = [row.get(col) for col in all_columns]
-            
-            # 确定排重列（排除id和更新时间列）
-            dup_cols = duplicate_columns if duplicate_columns else [
-                col for col in all_columns
-                if col.lower() not in self.base_excute_col
-            ]
-            
-            if check_duplicate:
-                # 添加排重条件参数
-                dup_values = [row.get(col) for col in dup_cols]
-                row_values.extend(dup_values)
-
-            # logger.info(sql)
-            # logger.info(row_values)
-            cursor.execute(sql, row_values)
+        """
+        处理单行数据插入
 
+        :param db_name: 数据库名
+        :param table_name: 表名
+        :param cursor: 数据库游标对象
+        :param row: 单行数据（字典）
+        :param all_columns: 需要插入的所有列名
+        :param sql: 执行的SQL语句
+        :param check_duplicate: 是否检查重复
+        :param duplicate_columns: 排重列
+        :param update_on_duplicate: 遇到重复时是否更新
+        :return: 'inserted' | 'skipped' | 'failed'
+        """
+        try:
+            # 构造参数
+            values = [row.get(col) for col in all_columns]
             if check_duplicate:
-                # 检查是否实际插入了行
-                return 'inserted' if cursor.rowcount > 0 else 'skipped'
-            return 'inserted'
-
+                # 需要为 WHERE NOT EXISTS 语句补充参数
+                if not update_on_duplicate:
+                    # duplicate_columns 为空时，默认用所有列（排除id/更新时间）
+                    dup_cols = duplicate_columns if duplicate_columns else [col for col in all_columns if col.lower() not in self.base_excute_col]
+                    values = values + [row.get(col) for col in dup_cols]
+            cursor.execute(sql, values)
         except Exception as e:
-            logger.error(sys._getframe().f_code.co_name, {
-                'error_type': type(e).__name__,
-                '单行插入失败': str(e),
-                '是否排重': check_duplicate,
-                '排重列': duplicate_columns,
-                '处理方式': '继续处理剩余行'
+            logger.error('单行插入失败', {
+                '库': db_name,
+                '表': table_name,
+                'row': self._shorten_for_log(row),
+                '错误': str(e)
             })
             return 'failed'
+        return 'inserted'
 
-    def close(self):
+    def close(self) -> None:
         """
         关闭连接池并清理资源
-        
         这个方法会安全地关闭数据库连接池，并清理相关资源。
         建议结束时手动调用此方法。
-        
         :raises: 可能抛出关闭连接时的异常
         """
         try:
             if hasattr(self, 'pool') and self.pool is not None:
-                # 更安全的关闭方式
                 try:
                     self.pool.close()
                 except Exception as e:
-                    logger.warning("关闭连接池时出错", {
-                        'error': str(e)
-                    })
-
+                    logger.warning('关闭连接池时出错', {'error': str(e)})
                 self.pool = None
-
-                logger.info("success", {'uploader.py': '连接池关闭'})
+                logger.info('连接池关闭', {'uploader.py': '连接池关闭'})
         except Exception as e:
-            logger.error("关闭连接池失败", {
-                'error': str(e)
-            })
+            logger.error('关闭连接池失败', {'error': str(e)})
             raise
 
-    def _check_pool_health(self):
+    def _check_pool_health(self) -> bool:
         """
         检查连接池健康状态
-
         :return: 连接池健康返回True，否则返回False
         """
         conn = None
         try:
             conn = self.pool.connection()
             conn.ping(reconnect=True)
+            logger.debug('连接池健康检查通过')
             return True
         except Exception as e:
-            logger.warning("连接池健康检查失败", {
-                'error': str(e)
-            })
+            logger.warning('连接池健康检查失败', {'error': str(e)})
             return False
         finally:
             if conn:
                 try:
                     conn.close()
                 except Exception as e:
-                    logger.warning("关闭连接时出错", {
-                        'error': str(e)
-                    })
+                    logger.warning('关闭连接时出错', {'error': str(e)})
 
-    def retry_on_failure(max_retries=3, delay=1):
+    def retry_on_failure(max_retries: int = 3, delay: int = 1):
+        """
+        通用重试装饰器
+        :param max_retries: 最大重试次数
+        :param delay: 重试间隔（秒）
+        :return: 装饰器
+        """
         def decorator(func):
             @wraps(func)
             def wrapper(*args, **kwargs):
@@ -1570,18 +1486,40 @@ class MySQLUploader:
                         return func(*args, **kwargs)
                     except (pymysql.OperationalError, pymysql.InterfaceError) as e:
                         last_exception = e
+                        logger.warning('操作失败，准备重试', {'attempt': attempt + 1, 'error': str(e)})
                         if attempt < max_retries - 1:
                             time.sleep(delay * (attempt + 1))
                             continue
-                        raise logger.error(f"操作重试 {max_retries} 次后失败")
+                        logger.error(f'操作重试 {max_retries} 次后失败', {'error': str(e)})
+                        raise
                     except Exception as e:
-                        raise logger.error(f"操作失败: {str(e)}")
-                raise last_exception if last_exception else logger.error("操作重试失败，未知错误")
-
+                        logger.error('操作失败', {'error': str(e)})
+                        raise
+                raise last_exception if last_exception else logger.error('操作重试失败，未知错误')
             return wrapper
-
         return decorator
 
+    def _shorten_for_log(self, obj: Any, maxlen: int = 200) -> Any:
+        """
+        日志安全截断工具：对字符串、列表、字典等做长度限制，避免日志过长。
+        :param obj: 原始对象
+        :param maxlen: 最大长度/元素数
+        :return: 截断后的对象
+        """
+        if isinstance(obj, str):
+            return obj[:maxlen] + ("..." if len(obj) > maxlen else "")
+        elif isinstance(obj, list):
+            return obj[:maxlen] + (["..."] if len(obj) > maxlen else [])
+        elif isinstance(obj, dict):
+            short = {k: self._shorten_for_log(v, maxlen) for i, (k, v) in enumerate(obj.items()) if i < maxlen}
+            if len(obj) > maxlen:
+                short['...'] = f"total_keys={len(obj)}"
+            return short
+        elif hasattr(obj, 'shape') and hasattr(obj, 'head'):
+            # pandas DataFrame
+            return f"DataFrame shape={obj.shape}, head={obj.head(1).to_dict()}"
+        return obj
+    
     def __enter__(self):
         return self
 
@@ -1591,9 +1529,7 @@ class MySQLUploader:
 
 def main():
     """
-    示例代码：
-    
-    这个示例展示了如何：
+    示例：
     1. 创建上传器实例
     2. 定义数据表结构
     3. 准备测试数据