springbootAI 1.8.0__py3-none-any.whl

spring/tx/events.py

@@ -0,0 +1,172 @@
+"""事务事件监听（对齐 Spring ``@TransactionalEventListener`` + ``TransactionalEventPublisher``）。
+
+``@TransactionalEventListener(phase=...)`` 标记的监听器在事务达到指定阶段时才触发：
+- ``BEFORE_COMMIT``：事务提交前
+- ``AFTER_COMMIT``：事务提交后（默认）
+- ``AFTER_ROLLBACK``：事务回滚后
+- ``AFTER_COMPLETION``：事务完成后（提交或回滚）
+
+设计：
+- **事件延迟**：``TransactionalEventPublisher.publish_event`` 发布事件时，若当前存在活动事务，
+  把事务监听器包装为 ``TransactionSynchronization`` 注册到 ``TransactionSynchronizationManager``，
+  等待 ``@Transactional`` 切面在对应阶段触发；无活动事务时按 ``fallback_execution`` 决定是否立即执行。
+- **复用既有事件基础设施**：普通 ``@EventListener`` 由 ``ApplicationEventPublisher`` 立即触发，
+  本模块仅处理事务监听器；可委托 ``ApplicationEventPublisher`` 处理普通监听器以共存的。
+- **注解基类**：``TransactionalEventListener`` 继承 ``SpringAnnotation``，元数据挂到
+  ``__spring_annotations__``，由 ``ApplicationContext._register_event_listeners`` 扫描注册。
+
+与 Java 的差异：
+- Spring ``@TransactionalEventListener`` 默认 ``AFTER_COMMIT``，无事务时不执行；本实现一致。
+- 监听器顺序由注册顺序决定（Spring 支持 ``@Order``，本实现保留 ``order`` 字段供扩展）。
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from typing import Any, Callable, List, Optional, Tuple, Type
+
+from spring.annotations.core import ApplicationEvent, SpringAnnotation
+from .synchronization import (
+    TransactionPhase,
+    TransactionSynchronization,
+    TransactionSynchronizationManager,
+)
+
+logger = logging.getLogger("Spring.Tx.Events")
+
+
+class TransactionalEventListener(SpringAnnotation):
+    """``@TransactionalEventListener`` 标记方法为事务阶段事件监听器。
+
+    Args:
+        phase: 触发阶段，默认 ``AFTER_COMMIT``。
+        fallback_execution: 无活动事务时是否立即执行（默认 ``False``，对齐 Spring）。
+        event_type: 监听的事件类型；未指定时从方法首参类型推断。
+        order: 监听器顺序（保留字段，当前按注册顺序触发）。
+    """
+
+    _annotation_type = "tx_event_listener"
+
+    def __init__(
+        self,
+        phase: TransactionPhase = TransactionPhase.AFTER_COMMIT,
+        fallback_execution: bool = False,
+        event_type: Optional[Type[ApplicationEvent]] = None,
+        order: int = 0,
+    ):
+        # 支持装饰器简写：@TransactionalEventListener(SomeEvent)
+        super().__init__(
+            phase=phase,
+            fallback_execution=fallback_execution,
+            event_type=event_type,
+            order=order,
+        )
+
+
+# 事务监听器条目：(event_type, callback, phase, fallback_execution, order)
+_TxListenerEntry = Tuple[Optional[Type[ApplicationEvent]], Callable, TransactionPhase, bool, int]
+
+
+class _ListenerSynchronization(TransactionSynchronization):
+    """把一个事务监听器适配为事务同步回调，在指定阶段触发。"""
+
+    def __init__(
+        self,
+        callback: Callable,
+        event: Any,
+        phase: TransactionPhase,
+        order: int,
+    ):
+        self._callback = callback
+        self._event = event
+        self._phase = phase
+        self._order = order
+        # AFTER_COMPLETION 阶段在 after_completion 中触发；其它阶段在对应方法触发。
+        self._fired = False
+
+    def _invoke(self) -> None:
+        if self._fired:
+            return
+        self._fired = True
+        result = self._callback(self._event)
+        if inspect.isawaitable(result):
+            self._finish_awaitable(result)
+
+    @staticmethod
+    def _finish_awaitable(awaitable) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            asyncio.run(awaitable)
+        else:
+            loop.create_task(awaitable)
+
+    def before_commit(self) -> None:
+        if self._phase == TransactionPhase.BEFORE_COMMIT:
+            self._invoke()
+
+    def after_commit(self) -> None:
+        if self._phase == TransactionPhase.AFTER_COMMIT:
+            self._invoke()
+
+    def after_rollback(self) -> None:
+        if self._phase == TransactionPhase.AFTER_ROLLBACK:
+            self._invoke()
+
+    def after_completion(self, status: str) -> None:
+        if self._phase == TransactionPhase.AFTER_COMPLETION:
+            self._invoke()
+
+
+class TransactionalEventPublisher:
+    """事务事件发布器：管理事务监听器并在事务阶段触发。
+
+    与 ``ApplicationEventPublisher`` 平行存在；可单独使用，也可由 ``ApplicationContext``
+    注册为 Bean 供 ``publish_event`` 统一委托。
+    """
+
+    def __init__(self):
+        self._listeners: List[_TxListenerEntry] = []
+
+    def add_listener(
+        self,
+        callback: Callable,
+        event_type: Optional[Type[ApplicationEvent]] = None,
+        phase: TransactionPhase = TransactionPhase.AFTER_COMMIT,
+        fallback_execution: bool = False,
+        order: int = 0,
+    ) -> None:
+        self._listeners.append((event_type, callback, phase, fallback_execution, order))
+
+    def clear(self) -> None:
+        self._listeners.clear()
+
+    def listener_count(self) -> int:
+        return len(self._listeners)
+
+    def publish_event(self, event: Any) -> Any:
+        """发布事件：匹配的事务监听器按事务阶段触发或回退立即执行。"""
+        if not isinstance(event, ApplicationEvent):
+            event = ApplicationEvent(source=event)
+
+        tx_active = TransactionSynchronizationManager.is_synchronization_active()
+        for event_type, callback, phase, fallback, _order in list(self._listeners):
+            if event_type is not None and not isinstance(event, event_type):
+                continue
+            if tx_active:
+                sync = _ListenerSynchronization(callback, event, phase, _order)
+                TransactionSynchronizationManager.register_synchronization(sync)
+            elif fallback:
+                # 无活动事务且允许回退执行：立即触发
+                result = callback(event)
+                if inspect.isawaitable(result):
+                    _ListenerSynchronization._finish_awaitable(result)
+            # 否则丢弃（对齐 Spring 默认：无事务不执行）
+        return event
+
+
+__all__ = [
+    "TransactionalEventListener",
+    "TransactionalEventPublisher",
+]

spring/tx/synchronization.py

@@ -0,0 +1,143 @@
+"""事务同步管理器（对齐 Spring ``TransactionSynchronizationManager``）。
+
+跟踪当前事务的同步回调（``TransactionSynchronization``），在事务生命周期各阶段触发：
+``BEFORE_COMMIT`` / ``AFTER_COMMIT`` / ``AFTER_ROLLBACK`` / ``AFTER_COMPLETION``。
+
+设计：
+- **ContextVar 持有**：用 ``ContextVar`` 保存当前事务的同步列表与活跃标志，兼容 ``asyncio`` 协程，
+  对齐 Spring 的 ``ThreadLocal<List<TransactionSynchronization>>``。
+- **最佳努力触发**：同步回调抛错时记录日志但不中断事务流程（与 Spring ``after_completion``
+  语义一致；``beforeCommit`` 抛错在 Spring 中会触发回滚，此处为安全起见统一记录，避免影响既有事务）。
+- **集成点**：``@Transactional`` 切面（``bean_factory._wrap_transactional``）在事务边界调用
+  ``init/clear`` 与各 ``trigger_*``；非受管场景可用 ``transaction_sync_scope`` 上下文管理器。
+
+与 Java 的差异：
+- Spring 用 ``ThreadLocal``；Python 用 ``ContextVar`` 兼容协程。
+- 同步回调抛错统一记录不中断事务（Spring ``beforeCommit`` 抛错会回滚），已在模块文档标注。
+"""
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from contextvars import ContextVar
+from enum import Enum
+from typing import Callable, List, Optional
+
+logger = logging.getLogger("Spring.Tx.Synchronization")
+
+
+class TransactionPhase(Enum):
+    """事务事件触发阶段（对齐 Spring ``TransactionPhase``）。"""
+    BEFORE_COMMIT = "BEFORE_COMMIT"
+    AFTER_COMMIT = "AFTER_COMMIT"
+    AFTER_ROLLBACK = "AFTER_ROLLBACK"
+    AFTER_COMPLETION = "AFTER_COMPLETION"
+
+
+class TransactionSynchronization:
+    """事务同步回调接口（对齐 Spring ``TransactionSynchronization``）。
+
+    子类按需重写各阶段回调；默认无操作。``@TransactionalEventListener`` 通过本接口的
+    适配实现把监听器挂到指定阶段。
+    """
+
+    def before_commit(self) -> None:
+        """事务提交前调用（同一事务可多次刷新时，仅最终提交前调用一次）。"""
+
+    def after_commit(self) -> None:
+        """事务成功提交后调用。"""
+
+    def after_rollback(self) -> None:
+        """事务回滚后调用。"""
+
+    def after_completion(self, status: str) -> None:
+        """事务完成后调用（``status`` 为 ``'commit'`` 或 ``'rollback'``）。"""
+
+
+# 当前事务的同步回调列表（None 表示当前无活动事务）
+_synchronizations: ContextVar[Optional[List[TransactionSynchronization]]] = ContextVar(
+    "spring_tx_synchronizations", default=None
+)
+
+
+class TransactionSynchronizationManager:
+    """事务同步管理器（静态方法风格，对齐 Spring 同名类）。"""
+
+    @staticmethod
+    def is_synchronization_active() -> bool:
+        return _synchronizations.get() is not None
+
+    @staticmethod
+    def init_synchronization() -> None:
+        """开启一个新的事务同步上下文（``@Transactional`` 入口调用）。"""
+        _synchronizations.set([])
+
+    @staticmethod
+    def clear_synchronization() -> None:
+        """清空当前事务同步上下文（``@Transactional`` 出口调用）。"""
+        _synchronizations.set(None)
+
+    @staticmethod
+    def get_synchronizations() -> List[TransactionSynchronization]:
+        """返回当前事务已注册的同步回调列表（无活动事务返回空列表）。"""
+        syncs = _synchronizations.get()
+        return list(syncs) if syncs is not None else []
+
+    @staticmethod
+    def register_synchronization(sync: TransactionSynchronization) -> None:
+        """注册一个同步回调到当前事务；无活动事务时抛错（对齐 Spring）。"""
+        syncs = _synchronizations.get()
+        if syncs is None:
+            raise RuntimeError(
+                "注册事务同步回调要求当前存在活动事务；"
+                "请在 @Transactional 方法内或 transaction_sync_scope 内调用"
+            )
+        syncs.append(sync)
+
+    # ==================== 阶段触发 ====================
+
+    @staticmethod
+    def trigger_before_commit() -> None:
+        TransactionSynchronizationManager._trigger(
+            "before_commit", lambda s: s.before_commit()
+        )
+
+    @staticmethod
+    def trigger_after_commit() -> None:
+        TransactionSynchronizationManager._trigger(
+            "after_commit", lambda s: s.after_commit()
+        )
+
+    @staticmethod
+    def trigger_after_rollback() -> None:
+        TransactionSynchronizationManager._trigger(
+            "after_rollback", lambda s: s.after_rollback()
+        )
+
+    @staticmethod
+    def trigger_after_completion(status: str) -> None:
+        TransactionSynchronizationManager._trigger(
+            "after_completion", lambda s: s.after_completion(status)
+        )
+
+    @staticmethod
+    def _trigger(phase: str, invoker: Callable[[TransactionSynchronization], None]) -> None:
+        """最佳努力触发：逐个调用同步回调，单个抛错记录日志但不中断后续。"""
+        for sync in TransactionSynchronizationManager.get_synchronizations():
+            try:
+                invoker(sync)
+            except Exception:  # pragma: no cover - 防御性，同步回调实现多样
+                logger.exception("事务同步回调 %s 执行失败", phase)
+
+
+@contextmanager
+def transaction_sync_scope():
+    """非受管场景的事务同步上下文：进入 init，退出 clear（不触发任何阶段）。
+
+    供独立测试或手动管理事务事件边界使用。``@Transactional`` 切面内部会自行管理。
+    """
+    TransactionSynchronizationManager.init_synchronization()
+    try:
+        yield TransactionSynchronizationManager
+    finally:
+        TransactionSynchronizationManager.clear_synchronization()

spring/utils/__init__.py

@@ -0,0 +1,5 @@
+from .logger import SpringLogger
+from .banner import BannerPrinter
+from .redis_client import RedisClient
+
+__all__ = ["SpringLogger", "BannerPrinter", "RedisClient"]

spring/utils/banner.py

@@ -0,0 +1,32 @@
+from spring.utils.logger import SpringLogger
+
+
+class BannerPrinter:
+    SPRING_BANNER = """
+  ____             _       _          ____  _   _   ____    _    ____  
+ / ___|  ___   ___| |_ ___| |__      / ___|| | | | / ___|  / \\  |  _ \\ 
+ \\___ \\ / _ \\ / __| __/ __| '_ \\     \\___ \\| |_| | \\___ \\ / _ \\ | |_) |
+  ___) | (_) | (__| || (__| | | |     ___) |  _  |  ___) / ___ \\|  __/ 
+ |____/ \\___/ \\___|\\__\\___|_| |_|    |____/|_| |_| |____/_/   \\_\\_|    
+                                                                        
+    """
+
+    def __init__(self, version: str = "0.1.0"):
+        self.version = version
+        self.logger = SpringLogger()
+
+    def print_banner(self) -> None:
+        print(self.SPRING_BANNER)
+        print(f" Spring Framework {self.version} ".center(60, "="))
+        print()
+
+    def print_startup_info(self, port: int, context_path: str = "") -> None:
+        self.logger.info("Starting Spring application...")
+        self.logger.info(f"Server port: {port}")
+        self.logger.info(f"Context path: {context_path or '/'}")
+        self.logger.info("Application started successfully!")
+        print()
+
+    def print_shutdown_info(self) -> None:
+        self.logger.info("Shutting down Spring application...")
+        self.logger.info("Application stopped successfully!")

spring/utils/logger.py

@@ -0,0 +1,73 @@
+import logging
+import sys
+from typing import Optional
+
+
+class SpringLogger:
+    _instance: Optional['SpringLogger'] = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if getattr(self, '_initialized', False):
+            return
+
+        self._logger = logging.getLogger("Spring")
+        self._logger.setLevel(logging.INFO)
+
+        formatter = logging.Formatter(
+            "%(asctime)s [%(levelname)s] %(name)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S"
+        )
+
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setFormatter(formatter)
+        console_handler.setLevel(logging.INFO)
+
+        self._logger.addHandler(console_handler)
+        self._initialized = True
+
+    def get_logger(self) -> logging.Logger:
+        return self._logger
+
+    def info(self, message: str) -> None:
+        self._logger.info(message)
+
+    def warn(self, message: str) -> None:
+        self._logger.warning(message)
+
+    def warning(self, message: str) -> None:
+        """Expose the standard-library logging spelling used by framework code."""
+        self._logger.warning(message)
+
+    def error(self, message: str) -> None:
+        self._logger.error(message)
+
+    def debug(self, message: str) -> None:
+        self._logger.debug(message)
+
+    def trace(self, message: str) -> None:
+        self._logger.debug(message)
+
+    def set_level(self, level: int) -> None:
+        self._logger.setLevel(level)
+        for handler in self._logger.handlers:
+            handler.setLevel(level)
+
+
+def get_logger(name: str = "Spring") -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        logger.setLevel(logging.INFO)
+        formatter = logging.Formatter(
+            "%(asctime)s [%(levelname)s] %(name)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S"
+        )
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+    return logger