springbootAI 1.8.0__py3-none-any.whl

spring/retry/__init__.py

@@ -0,0 +1,12 @@
+"""
+重试机制模块
+提供重试注解和重试策略
+"""
+from .retry_annotations import Retryable, Backoff
+from .retry_decorator import retryable_decorator
+
+__all__ = [
+    'Retryable',
+    'Backoff',
+    'retryable_decorator',
+]

spring/retry/retry_annotations.py

@@ -0,0 +1,71 @@
+"""
+重试注解定义
+"""
+from typing import Type, Tuple, Optional
+
+
+class Backoff:
+    """
+    退避策略配置
+    
+    参数：
+        delay: 初始延迟时间（毫秒），默认1000
+        max_delay: 最大延迟时间（毫秒），默认10000
+        multiplier: 延迟倍增因子，默认2.0（指数退避）
+        random_factor: 随机因子（0.0-1.0），默认0.1
+    """
+    
+    def __init__(
+        self,
+        delay: int = 1000,
+        max_delay: int = 10000,
+        multiplier: float = 2.0,
+        random_factor: float = 0.1
+    ):
+        self.delay = delay
+        self.max_delay = max_delay
+        self.multiplier = multiplier
+        self.random_factor = random_factor
+
+
+class Retryable:
+    """
+    重试注解
+    
+    参数：
+        value: 要重试的异常类型（或异常类型元组）
+        max_retries: 最大重试次数，默认3（包含首次调用）
+        backoff: 退避策略配置
+        exclude: 不重试的异常类型（或异常类型元组）
+        recover: 恢复方法名（当重试失败时调用）
+    """
+    
+    def __init__(
+        self,
+        value: Optional[Tuple[Type[Exception], ...]] = None,
+        max_retries: int = 3,
+        backoff: Optional[object] = None,
+        exclude: Optional[Tuple[Type[Exception], ...]] = None,
+        recover: str = "",
+        max_attempts: Optional[int] = None,
+    ):
+        if max_attempts is not None:
+            if max_retries != 3 and max_retries != max_attempts:
+                raise ValueError("max_retries 与 max_attempts 不能设置为不同值")
+            max_retries = max_attempts
+        if max_retries <= 0:
+            raise ValueError("max_retries 必须大于0")
+        if isinstance(backoff, (int, float)):
+            if backoff < 0:
+                raise ValueError("backoff 延迟不能小于0")
+            backoff = Backoff(
+                delay=int(backoff),
+                max_delay=int(backoff),
+                multiplier=1.0,
+                random_factor=0.0,
+            )
+        self.value = value or (Exception,)
+        self.max_retries = max_retries
+        self.backoff = backoff or Backoff()
+        self.exclude = exclude or ()
+        self.recover = recover

spring/retry/retry_decorator.py

@@ -0,0 +1,155 @@
+"""
+重试切面实现
+"""
+import time
+import random
+import logging
+import functools
+from typing import Callable, Tuple, Type
+
+logger = logging.getLogger("Spring.Retry")
+
+
+def retryable_decorator(annotation):
+    """
+    @Retryable注解切面实现
+    
+    支持：
+    - 指定重试的异常类型
+    - 指定不重试的异常类型
+    - 最大重试次数
+    - 退避策略（固定延迟/指数退避）
+    - 随机因子
+    - 恢复方法（recover）
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            max_retries = annotation.max_retries
+            exceptions_to_retry = annotation.value
+            exceptions_to_exclude = annotation.exclude
+            backoff = annotation.backoff
+            recover_method = annotation.recover
+            
+            last_exception = None
+            retry_count = 0
+            
+            while retry_count < max_retries:
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+                    retry_count += 1
+                    
+                    # 检查是否是需要排除的异常
+                    if isinstance(e, exceptions_to_exclude):
+                        logger.info(f"[Retry] Exception {type(e).__name__} excluded from retry, re-raising")
+                        raise
+                    
+                    # 检查是否是需要重试的异常
+                    if not isinstance(e, exceptions_to_retry):
+                        logger.info(f"[Retry] Exception {type(e).__name__} not in retry list, re-raising")
+                        raise
+                    
+                    # 判断是否需要继续重试
+                    if retry_count >= max_retries:
+                        logger.warning(f"[Retry] Max retries ({max_retries}) exceeded for {func.__name__}: {str(e)}")
+                        break
+                    
+                    # 计算退避时间
+                    delay = _calculate_backoff(backoff, retry_count)
+                    
+                    logger.info(
+                        f"[Retry] Retrying {func.__name__} (attempt {retry_count}/{max_retries-1}), "
+                        f"exception: {type(e).__name__}, delay: {delay:.2f}ms"
+                    )
+                    
+                    # 等待
+                    time.sleep(delay / 1000.0)
+            
+            # 重试失败，尝试调用恢复方法
+            if last_exception and recover_method:
+                logger.info(f"[Retry] Calling recover method '{recover_method}' for {func.__name__}")
+                try:
+                    # 尝试从实例中获取恢复方法
+                    if args:
+                        recover_func = getattr(args[0], recover_method, None)
+                    else:
+                        recover_func = None
+                    
+                    if recover_func and callable(recover_func):
+                        # 移除self参数（如果存在）
+                        if args:
+                            return recover_func(*args[1:], **kwargs)
+                        else:
+                            return recover_func(**kwargs)
+                except Exception as recover_e:
+                    logger.error(f"[Retry] Recover method '{recover_method}' failed: {recover_e}")
+            
+            # 所有重试都失败，抛出最后一个异常
+            if last_exception:
+                raise last_exception
+        
+        return wrapper
+    return decorator
+
+
+def _calculate_backoff(backoff, attempt: int) -> float:
+    """
+    计算退避时间
+    
+    参数：
+        backoff: 退避配置
+        attempt: 当前重试次数（从1开始）
+    
+    返回：
+        退避时间（毫秒）
+    """
+    # 指数退避：delay * (multiplier ^ (attempt - 1))
+    delay = backoff.delay * (backoff.multiplier ** (attempt - 1))
+    
+    # 应用随机因子
+    if backoff.random_factor > 0:
+        random_delta = delay * backoff.random_factor
+        delay = delay + random.uniform(-random_delta, random_delta)
+    
+    # 确保不超过最大延迟
+    delay = min(delay, backoff.max_delay)
+    
+    # 确保不小于0
+    delay = max(delay, 0)
+    
+    return delay
+
+
+def retry(
+    max_retries: int = 3,
+    delay: int = 1000,
+    max_delay: int = 10000,
+    multiplier: float = 2.0,
+    exceptions: Tuple[Type[Exception], ...] = (Exception,)
+) -> Callable:
+    """
+    便捷的重试装饰器
+    
+    参数：
+        max_retries: 最大重试次数
+        delay: 初始延迟（毫秒）
+        max_delay: 最大延迟（毫秒）
+        multiplier: 延迟倍增因子
+        exceptions: 需要重试的异常类型
+    
+    使用示例：
+        @retry(max_retries=5, delay=500)
+        def fetch_data():
+            pass
+    """
+    from spring.retry.retry_annotations import Retryable, Backoff
+    
+    annotation = Retryable(
+        value=exceptions,
+        max_retries=max_retries,
+        backoff=Backoff(delay=delay, max_delay=max_delay, multiplier=multiplier)
+    )
+    
+    return retryable_decorator(annotation)

spring/scheduling/__init__.py

@@ -0,0 +1,3 @@
+from .scheduler import Scheduler
+
+__all__ = ["Scheduler"]

spring/scheduling/scheduler.py

@@ -0,0 +1,389 @@
+from typing import Dict, Any, Callable, Optional
+import asyncio
+import time
+import logging
+import threading
+
+
+class Scheduler:
+    def __init__(self):
+        # 存储任务信息: {task_id: {'task': asyncio.Task, 'loop': asyncio.AbstractEventLoop}}
+        self._tasks: Dict[str, dict] = {}
+        self._lock = threading.RLock()
+        self._logger = logging.getLogger("Spring.Scheduler")
+
+    def schedule(self, task_id: str, func: Callable, **kwargs) -> None:
+        fixed_rate = kwargs.get('fixed_rate')
+        fixed_delay = kwargs.get('fixed_delay')
+        cron = kwargs.get('cron')
+        initial_delay = kwargs.get('initial_delay', 0)
+
+        try:
+            loop = asyncio.get_event_loop()
+            if not loop.is_running():
+                # 如果有事件循环但未运行，创建新线程运行
+                def run_loop():
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+                    task = None
+                    if fixed_rate:
+                        task = loop.create_task(self._schedule_fixed_rate(task_id, func, fixed_rate, initial_delay))
+                    elif fixed_delay:
+                        task = loop.create_task(self._schedule_fixed_delay(task_id, func, fixed_delay, initial_delay))
+                    elif cron:
+                        task = loop.create_task(self._schedule_cron(task_id, func, cron, initial_delay))
+                    
+                    if task:
+                        with self._lock:
+                            self._tasks[task_id] = {'task': task, 'loop': loop}
+                    
+                    loop.run_forever()
+                
+                thread = threading.Thread(target=run_loop, daemon=True)
+                thread.start()
+                return
+        except RuntimeError:
+            # 没有事件循环，创建新线程运行
+            def run_loop():
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                task = None
+                if fixed_rate:
+                    task = loop.create_task(self._schedule_fixed_rate(task_id, func, fixed_rate, initial_delay))
+                elif fixed_delay:
+                    task = loop.create_task(self._schedule_fixed_delay(task_id, func, fixed_delay, initial_delay))
+                elif cron:
+                    task = loop.create_task(self._schedule_cron(task_id, func, cron, initial_delay))
+                
+                if task:
+                    with self._lock:
+                        self._tasks[task_id] = {'task': task, 'loop': loop}
+                
+                loop.run_forever()
+            
+            thread = threading.Thread(target=run_loop, daemon=True)
+            thread.start()
+            return
+
+        # 有运行中的事件循环
+        loop = asyncio.get_event_loop()
+        task = None
+        if fixed_rate:
+            task = asyncio.create_task(self._schedule_fixed_rate(task_id, func, fixed_rate, initial_delay))
+        elif fixed_delay:
+            task = asyncio.create_task(self._schedule_fixed_delay(task_id, func, fixed_delay, initial_delay))
+        elif cron:
+            task = asyncio.create_task(self._schedule_cron(task_id, func, cron, initial_delay))
+        else:
+            self._logger.warning(f"No scheduling type specified for task: {task_id}")
+        
+        if task:
+            with self._lock:
+                self._tasks[task_id] = {'task': task, 'loop': loop}
+
+    async def _schedule_fixed_rate(self, task_id: str, func: Callable, rate_ms: int, initial_delay: int) -> None:
+        await asyncio.sleep(initial_delay / 1000)
+        
+        while True:
+            # 检查任务是否已被取消
+            with self._lock:
+                task_info = self._tasks.get(task_id)
+                if task_info is None or task_info['task'].done():
+                    break
+            
+            start_time = time.time()
+            try:
+                if asyncio.iscoroutinefunction(func):
+                    await func()
+                else:
+                    func()
+            except Exception as e:
+                self._logger.error(f"Scheduled task {task_id} failed: {str(e)}")
+            
+            elapsed_ms = (time.time() - start_time) * 1000
+            sleep_time = max(0, rate_ms - elapsed_ms) / 1000
+            await asyncio.sleep(sleep_time)
+
+    async def _schedule_fixed_delay(self, task_id: str, func: Callable, delay_ms: int, initial_delay: int) -> None:
+        await asyncio.sleep(initial_delay / 1000)
+        
+        while True:
+            # 检查任务是否已被取消
+            with self._lock:
+                task_info = self._tasks.get(task_id)
+                if task_info is None or task_info['task'].done():
+                    break
+            
+            try:
+                if asyncio.iscoroutinefunction(func):
+                    await func()
+                else:
+                    func()
+            except Exception as e:
+                self._logger.error(f"Scheduled task {task_id} failed: {str(e)}")
+            
+            await asyncio.sleep(delay_ms / 1000)
+
+    async def _schedule_cron(self, task_id: str, func: Callable, cron_expr: str, initial_delay: int) -> None:
+        await asyncio.sleep(initial_delay / 1000)
+        
+        while True:
+            # 检查任务是否已被取消
+            with self._lock:
+                task_info = self._tasks.get(task_id)
+                if task_info is None or task_info['task'].done():
+                    break
+            
+            try:
+                if asyncio.iscoroutinefunction(func):
+                    await func()
+                else:
+                    func()
+            except Exception as e:
+                self._logger.error(f"Scheduled task {task_id} failed: {str(e)}")
+            
+            await asyncio.sleep(self._parse_cron(cron_expr))
+
+    def _parse_cron(self, cron_expr: str) -> float:
+        import datetime
+        
+        parts = cron_expr.split()
+        
+        if len(parts) == 5:
+            second = '*'
+            minute, hour, day, month, weekday = parts
+        elif len(parts) == 6:
+            second, minute, hour, day, month, weekday = parts
+        else:
+            self._logger.warning(f"Invalid cron expression: {cron_expr}")
+            return 60.0
+        
+        try:
+            now = datetime.datetime.now()
+            next_run = now + datetime.timedelta(seconds=1)
+            
+            # 解析所有字段的可能值
+            seconds = self._parse_field(second, 0, 59)
+            minutes = self._parse_field(minute, 0, 59)
+            hours = self._parse_field(hour, 0, 23)
+            days = self._parse_field(day, 1, 31)
+            months = self._parse_field(month, 1, 12)
+            
+            # 获取当前月份的最大天数
+            def get_max_day(year, m):
+                if m == 2:
+                    if year % 4 == 0 and (year % 100 != 0 or year % 400 == 0):
+                        return 29
+                    return 28
+                if m in [4, 6, 9, 11]:
+                    return 30
+                return 31
+            
+            # 从当前时间开始查找下一个匹配时间
+            while True:
+                # 检查月份
+                if next_run.month not in months:
+                    # 跳转到下一个匹配月份的第一天
+                    next_month_found = False
+                    for m in months:
+                        if m > next_run.month:
+                            next_run = next_run.replace(month=m, day=1, hour=0, minute=0, second=0)
+                            next_month_found = True
+                            break
+                    if not next_month_found:
+                        # 下一年的第一个匹配月份
+                        if months:
+                            next_run = next_run.replace(year=next_run.year + 1, month=months[0], day=1, hour=0, minute=0, second=0)
+                        else:
+                            return 60.0
+                    continue
+                
+                # 检查日期
+                max_day = get_max_day(next_run.year, next_run.month)
+                valid_days = [d for d in days if d <= max_day]
+                
+                if next_run.day not in valid_days:
+                    # 跳转到下一个匹配日期
+                    next_day_found = False
+                    for d in valid_days:
+                        if d > next_run.day:
+                            next_run = next_run.replace(day=d, hour=0, minute=0, second=0)
+                            next_day_found = True
+                            break
+                    if not next_day_found:
+                        # 跳转到下一个月
+                        next_month_found = False
+                        for m in months:
+                            if m > next_run.month:
+                                next_run = next_run.replace(month=m, day=1, hour=0, minute=0, second=0)
+                                next_month_found = True
+                                break
+                        if not next_month_found:
+                            if months:
+                                next_run = next_run.replace(year=next_run.year + 1, month=months[0], day=1, hour=0, minute=0, second=0)
+                            else:
+                                return 60.0
+                    continue
+                
+                # 检查星期
+                if weekday != '*' and weekday != '?':
+                    if not self._matches_weekday(next_run.weekday(), weekday):
+                        # 跳到下一天
+                        next_run = next_run + datetime.timedelta(days=1)
+                        next_run = next_run.replace(hour=0, minute=0, second=0)
+                        continue
+                
+                # 检查小时
+                if next_run.hour not in hours:
+                    # 跳转到下一个匹配小时
+                    next_hour_found = False
+                    for h in hours:
+                        if h > next_run.hour:
+                            next_run = next_run.replace(hour=h, minute=0, second=0)
+                            next_hour_found = True
+                            break
+                    if not next_hour_found:
+                        # 跳转到下一天
+                        next_run = next_run + datetime.timedelta(days=1)
+                        next_run = next_run.replace(hour=0, minute=0, second=0)
+                    continue
+                
+                # 检查分钟
+                if next_run.minute not in minutes:
+                    # 跳转到下一个匹配分钟
+                    next_minute_found = False
+                    for m in minutes:
+                        if m > next_run.minute:
+                            next_run = next_run.replace(minute=m, second=0)
+                            next_minute_found = True
+                            break
+                    if not next_minute_found:
+                        # 跳转到下一小时
+                        next_run = next_run + datetime.timedelta(hours=1)
+                        next_run = next_run.replace(minute=0, second=0)
+                    continue
+                
+                # 检查秒
+                if next_run.second in seconds:
+                    # 找到匹配时间
+                    delta = (next_run - now).total_seconds()
+                    return max(0, delta)
+                
+                # 跳转到下一个匹配秒
+                next_second_found = False
+                for s in seconds:
+                    if s > next_run.second:
+                        next_run = next_run.replace(second=s)
+                        next_second_found = True
+                        break
+                if not next_second_found:
+                    # 跳转到下一分钟
+                    next_run = next_run + datetime.timedelta(minutes=1)
+                    next_run = next_run.replace(second=0)
+                
+                # 防止无限循环
+                if (next_run - now).total_seconds() > 365 * 24 * 3600:
+                    return 60.0
+        
+        except Exception as e:
+            self._logger.error(f"Failed to parse cron expression '{cron_expr}': {str(e)}")
+            return 60.0
+    
+    def _parse_field(self, expr: str, min_val: int, max_val: int) -> list:
+        """解析 cron 字段表达式，返回所有可能的取值"""
+        if expr == '*' or expr == '?':
+            return list(range(min_val, max_val + 1))
+        
+        result = []
+        for part in expr.split(','):
+            if '/' in part:
+                # 处理 step 表达式，如 */5 或 0/5
+                step_parts = part.split('/')
+                if len(step_parts) == 2:
+                    start_str, step_str = step_parts
+                    start = int(start_str) if start_str != '*' else min_val
+                    step = int(step_str)
+                    for val in range(start, max_val + 1, step):
+                        if val >= min_val:
+                            result.append(val)
+            elif '-' in part:
+                # 处理范围表达式，如 1-5
+                range_parts = part.split('-')
+                if len(range_parts) == 2:
+                    start = int(range_parts[0])
+                    end = int(range_parts[1])
+                    for val in range(start, end + 1):
+                        if min_val <= val <= max_val:
+                            result.append(val)
+            elif part.isdigit():
+                # 处理单个值
+                val = int(part)
+                if min_val <= val <= max_val:
+                    result.append(val)
+        
+        return sorted(set(result))
+    
+    def _matches_field(self, value: int, expr: str, min_val: int, max_val: int) -> bool:
+        if expr == '*' or expr == '?':
+            return True
+        
+        # 处理 */5 或 0/5 格式（从起始值开始每隔step执行）
+        if '/' in expr:
+            parts = expr.split('/')
+            if len(parts) == 2:
+                start = int(parts[0]) if parts[0] != '*' else min_val
+                step = int(parts[1])
+                return (value - start) % step == 0 and value >= start
+        
+        if expr.isdigit():
+            return value == int(expr)
+        
+        if '-' in expr:
+            parts = expr.split('-')
+            if len(parts) == 2:
+                return min_val <= int(parts[0]) <= value <= int(parts[1]) <= max_val
+        
+        return False
+
+    def _matches_weekday(self, value: int, expr: str) -> bool:
+        if expr == '*' or expr == '?':
+            return True
+        
+        if expr.isdigit():
+            day = int(expr)
+            if day == 7:
+                day = 0
+            return value == day
+        
+        return False
+
+    def stop(self, task_id: str) -> None:
+        with self._lock:
+            if task_id not in self._tasks:
+                return
+            
+            task_info = self._tasks[task_id]
+            task = task_info['task']
+            loop = task_info['loop']
+            
+            if not task.done():
+                try:
+                    # 使用 call_soon_threadsafe 安全地跨线程取消任务
+                    if loop.is_running():
+                        loop.call_soon_threadsafe(task.cancel)
+                    else:
+                        task.cancel()
+                except Exception as e:
+                    self._logger.error(f"Failed to cancel task {task_id}: {str(e)}")
+            
+            del self._tasks[task_id]
+            self._logger.info(f"Scheduled task {task_id} stopped")
+
+    def stop_all(self) -> None:
+        with self._lock:
+            task_ids = list(self._tasks.keys())
+        
+        for task_id in task_ids:
+            self.stop(task_id)
+        
+        self._logger.info(f"All {len(task_ids)} scheduled tasks stopped")

spring/security/__init__.py

@@ -0,0 +1,39 @@
+"""
+Spring Security 模块
+提供认证授权、JWT支持、密钥管理、重放防护等企业级安全功能
+"""
+from .security_context import SecurityContext, SecurityContextHolder
+from .security_aop import (
+    pre_authorize_decorator,
+    secured_decorator,
+    authenticate_decorator,
+)
+
+# 可选导入：JWT工具（需要pyjwt）
+try:
+    from .jwt_utils import JwtUtils
+except ImportError:
+    JwtUtils = None
+
+# 密钥管理器
+from .secret_manager import SecretManager, is_sensitive_key, mask_secret, resolve_secret_config
+
+# 重放攻击防护
+from .replay_protection import ReplayProtection, NonceCache, RedisNonceCache, create_replay_protection
+
+__all__ = [
+    'JwtUtils',
+    'SecurityContext',
+    'SecurityContextHolder',
+    'pre_authorize_decorator',
+    'secured_decorator',
+    'authenticate_decorator',
+    'SecretManager',
+    'is_sensitive_key',
+    'mask_secret',
+    'resolve_secret_config',
+    'ReplayProtection',
+    'NonceCache',
+    'RedisNonceCache',
+    'create_replay_protection',
+]