springbootAI 1.8.0__py3-none-any.whl

spring/datasource/annotations.py

@@ -0,0 +1,133 @@
+"""多数据源注解（对齐 ``dynamic-datasource-spring-boot-starter`` 的 ``@DS``/``@Master``/``@Slave``）。
+
+注解在方法执行期间设置 ``DataSourceContextHolder`` 路由键，退出后自动复位，使受管/非受管
+Bean 方法内的数据访问自动走向指定数据源。
+
+设计：
+- **复用既有注解基类**：``@DS`` 继承 ``SpringAnnotation``，元数据挂到 ``__spring_annotations__``。
+- **薄 AOP 包装**：``ds_route_decorator`` 为方法切面，``@DS``/``@Master``/``@Slave`` 通过
+  ``comprehensive_aop.ANNOTATION_DECORATORS`` 注册即可接入受管 Bean 包装链路；
+  非受管场景用 ``apply_ds_annotations`` 手动包装（与既有 ``@Validate``/``@Cacheable`` 一致）。
+- **嵌套复位**：用 ``ContextVar.reset(token)`` 保证内层方法退出后恢复外层路由键，
+  对齐 Spring ``AbstractRoutingDataSource`` 的栈式语义。
+
+与 Java 的差异：
+- ``dynamic-datasource`` starter 用 ``ThreadLocal`` + AOP；这里用 ``ContextVar`` 兼容协程。
+- ``@Master``/``@Slave`` 为 ``@DS`` 的语义快捷方式，路由键分别为 ``"master"`` 与 ``"@slave"`` 占位
+  （``@slave`` 占位由 ``DynamicRoutingDataSource`` 在切面内解析为轮询选定的具体 slave 键）。
+"""
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, Optional
+
+from spring.annotations.core import SpringAnnotation
+from .context import DataSourceContextHolder, routing_scope
+
+# 占位路由键：``@Slave`` 标记进入从库轮询逻辑，由装饰器解析为具体 slave。
+_SLAVE_PLACEHOLDER = "@__slave__"
+
+
+class DS(SpringAnnotation):
+    """``@DS("name")`` 指定方法走具名数据源。``@DS`` 不带参数等价于默认（master）。"""
+
+    _annotation_type = "datasource"
+
+    def __init__(self, value: str = ""):
+        super().__init__(value=value)
+
+
+class Master(SpringAnnotation):
+    """``@Master`` 显式走主库（等价于 ``@DS("master")``）。"""
+
+    _annotation_type = "datasource"
+
+    def __init__(self):
+        super().__init__(value="master")
+
+
+class Slave(SpringAnnotation):
+    """``@Slave`` 走从库（负载均衡轮询，由 ``DynamicRoutingDataSource`` 解析）。"""
+
+    _annotation_type = "datasource"
+
+    def __init__(self):
+        super().__init__(value=_SLAVE_PLACEHOLDER)
+
+
+def _resolve_routing_key(ds_annotation: SpringAnnotation) -> Optional[str]:
+    """从注解实例解析路由键。
+
+    ``@Slave`` 始终返回占位键，由 ``DynamicRoutingDataSource`` 在连接时解析为轮询 slave；
+    若未接入动态数据源，占位键命中不到任何池，``determine_target_data_source`` 回退默认目标，
+    行为安全。``@DS("")``/``@DS`` 不带参数返回 ``None``（默认目标）。
+    """
+    value = getattr(ds_annotation, "value", "") or ""
+    if value == _SLAVE_PLACEHOLDER:
+        return _SLAVE_PLACEHOLDER
+    return value or None
+
+
+def ds_route_decorator(method: Callable, ds_annotation: SpringAnnotation) -> Callable:
+    """``@DS``/``@Master``/``@Slave`` 的方法级切面：进入设路由键，退出复位。
+
+    保留双参数签名供手写调用；``comprehensive_aop`` 注册使用 ``ds_decorator_factory`` 工厂形式。
+    """
+    routing_key = _resolve_routing_key(ds_annotation)
+
+    if inspect.iscoroutinefunction(method):
+        @functools.wraps(method)
+        async def async_wrapper(*args, **kwargs):
+            with routing_scope(routing_key):
+                return await method(*args, **kwargs)
+        return async_wrapper
+
+    @functools.wraps(method)
+    def wrapper(*args, **kwargs):
+        with routing_scope(routing_key):
+            return method(*args, **kwargs)
+    return wrapper
+
+
+def ds_decorator_factory(ds_annotation: SpringAnnotation) -> Callable:
+    """AOP 装饰器工厂（对齐 ``comprehensive_aop.ANNOTATION_DECORATORS`` 注册约定）。
+
+    ``comprehensive_aop.apply_annotations`` 调用形如 ``factory(annotation)(method)``，
+    本工厂返回的装饰器会把方法包装为路由键作用域切面。
+    """
+    def decorator(method: Callable) -> Callable:
+        return ds_route_decorator(method, ds_annotation)
+    return decorator
+
+
+def apply_ds_annotations(instance: Any) -> Any:
+    """为非受管实例上带 ``@DS``/``@Master``/``@Slave`` 的方法手动应用切面。
+
+    受管 Bean 由 ``comprehensive_aop`` 经 ``ANNOTATION_DECORATORS`` 注册自动包装，
+    无需调用本函数。对齐既有 ``apply_annotations`` 的使用模式。
+    """
+    cls = instance.__class__
+    for name, method in inspect.getmembers(cls, predicate=inspect.isfunction):
+        annotations = getattr(method, "__spring_annotations__", [])
+        ds_ann = next(
+            (a for a in annotations if isinstance(a, (DS, Master, Slave))),
+            None,
+        )
+        if ds_ann is None:
+            continue
+        # ds_route_decorator 内部已用 functools.wraps；这里直接绑定到实例
+        wrapped = ds_route_decorator(method, ds_ann)
+        setattr(instance, name, wrapped.__get__(instance))
+    return instance
+
+
+def is_slave_placeholder(routing_key: Optional[str]) -> bool:
+    """供 ``DynamicRoutingDataSource`` 判断当前路由键是否为 ``@Slave`` 占位。"""
+    return routing_key == _SLAVE_PLACEHOLDER
+
+
+__all__ = [
+    "DS", "Master", "Slave",
+    "ds_route_decorator", "apply_ds_annotations", "is_slave_placeholder",
+]

spring/datasource/context.py

@@ -0,0 +1,69 @@
+"""多数据源路由上下文（对齐 Spring ``AbstractRoutingDataSource``）。
+
+``DataSourceContextHolder`` 用 ``ContextVar`` 保存当前线程/协程的路由键，
+``DynamicRoutingDataSource`` 在 ``get_connection`` 时读取该键决定走向哪个物理数据源。
+
+对齐 Spring：
+- Spring 用 ``ThreadLocal<Object>``；Python 用 ``ContextVar`` 以兼容 ``asyncio`` 协程。
+- ``@DS`` / ``@Master`` / ``@Slave`` 注解在方法执行期间设置路由键，退出后复位（对齐
+  ``AbstractRoutingDataSource.determineCurrentLookupKey`` + AOP 切面）。
+
+与 Java 的差异：
+- Python ``ContextVar`` 的 ``set`` 返回 token，复位用 ``reset(token)``，天然支持嵌套调用
+  （内层方法退出后自动恢复外层路由键），比 Spring 的 ``ThreadLocal`` 手动 push/pop 更简洁。
+"""
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Optional
+
+# 当前路由键：None 表示使用默认数据源（master）
+_routing_key: ContextVar[Optional[str]] = ContextVar(
+    "spring_datasource_routing_key", default=None
+)
+
+
+class DataSourceContextHolder:
+    """线程/协程安全的数据源路由键持有器（静态方法风格，对齐 Spring 同名类）。"""
+
+    @staticmethod
+    def get() -> Optional[str]:
+        """返回当前路由键；未设置返回 ``None``。"""
+        return _routing_key.get()
+
+    @staticmethod
+    def set(routing_key: Optional[str]):
+        """设置路由键，返回用于复位的 token。"""
+        return _routing_key.set(routing_key)
+
+    @staticmethod
+    def reset(token) -> None:
+        """用 ``set`` 返回的 token 复位路由键。"""
+        _routing_key.reset(token)
+
+    @staticmethod
+    def clear() -> None:
+        """强制清空路由键（慎用，会丢失嵌套层级）。"""
+        _routing_key.set(None)
+
+
+class _RoutingKeyScope:
+    """``with`` 语法糖：进入设置路由键，退出复位。供 ``@DS`` AOP 与手写代码共用。"""
+
+    def __init__(self, routing_key: Optional[str]):
+        self._routing_key = routing_key
+        self._token = None
+
+    def __enter__(self):
+        self._token = DataSourceContextHolder.set(self._routing_key)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._token is not None:
+            DataSourceContextHolder.reset(self._token)
+        return False
+
+
+def routing_scope(routing_key: Optional[str]) -> _RoutingKeyScope:
+    """便捷工厂：``with routing_scope("slave"): ...``。"""
+    return _RoutingKeyScope(routing_key)

spring/datasource/dynamic.py

@@ -0,0 +1,148 @@
+"""动态路由数据源（对齐 Spring ``AbstractRoutingDataSource``）。
+
+``DynamicRoutingDataSource`` 持有多个具名物理数据源（连接池），在 ``get_connection`` 时
+依据 ``DataSourceContextHolder`` 的路由键选择目标池，无路由键时走默认目标（master）。
+
+设计：
+- **接口兼容**：实现 ``get_connection`` / ``return_connection`` / ``get_pool_stats``，
+  可作为 ``SqlSessionFactory.connection_pool`` 的 drop-in 替换，无需改动既有 ORM 调用链。
+- **从库负载均衡**：多个 slave 用轮询（round-robin）选择，对齐 Spring ``loadBalance`` 语义。
+- **故障转移**：路由键指向的池不存在时回退到默认目标并记录告警，避免业务中断。
+- **连接归还**：归还时按连接记录的来源池路由，确保借还一致。
+
+与 Java 的差异：
+- Spring 的 ``AbstractRoutingDataSource`` 是 ``DataSource`` 接口实现；这里对齐项目既有
+  ``ConnectionPool`` 接口（``get_connection``/``return_connection``），不引入 JDBC 概念。
+- 不实现 Spring 的 ``lenientFallback`` 配置项，统一回退到默认目标（更安全）。
+"""
+from __future__ import annotations
+
+import itertools
+import logging
+import threading
+from typing import Any, Dict, List, Optional
+
+from .context import DataSourceContextHolder
+
+logger = logging.getLogger("Spring.DataSource.Dynamic")
+
+
+class DynamicRoutingDataSource:
+    """动态路由数据源：按路由键在多个物理连接池间路由。
+
+    Args:
+        target_data_sources: 具名物理池映射，如 ``{"slave_1": pool1, "slave_2": pool2}``。
+        default_target_data_source: 默认目标池（路由键为 None 或未命中时使用），通常为 master。
+        slave_keys: 标记为从库的路由键列表，用于 ``@Slave`` 注解做负载均衡轮询。
+    """
+
+    def __init__(
+        self,
+        target_data_sources: Dict[str, Any],
+        default_target_data_source: Any,
+        slave_keys: Optional[List[str]] = None,
+    ):
+        if not isinstance(target_data_sources, dict) or not target_data_sources:
+            raise ValueError("target_data_sources 必须是非空映射")
+        if default_target_data_source is None:
+            raise ValueError("default_target_data_source 不能为空")
+        self._target_data_sources: Dict[str, Any] = dict(target_data_sources)
+        self._default_target = default_target_data_source
+        self._slave_keys: List[str] = list(slave_keys) if slave_keys else []
+        self._lock = threading.Lock()
+        # 轮询计数器：每个 slave_key 一个独立游标，分散热点
+        self._slave_iterators: Dict[str, itertools.cycle] = {
+            key: itertools.cycle(self._slave_keys) for key in self._slave_keys
+        } if self._slave_keys else {}
+        # 仅对 slave_keys 做轮询共享一个 cycle，简化为单一游标
+        self._slave_cycle = itertools.cycle(self._slave_keys) if self._slave_keys else None
+        # 侧表：连接不支持附加属性时（如 dict/原生对象）按 id 记录来源池，归还时清理。
+        self._connection_sources: Dict[int, Any] = {}
+
+    # ==================== 路由核心 ====================
+
+    def determine_target_data_source(self) -> Any:
+        """依据当前路由键选择目标池；未命中回退到默认目标。
+
+        ``@Slave`` 占位键触发从库轮询；显式具名键直接命中对应池。
+        """
+        from .annotations import is_slave_placeholder
+        routing_key = DataSourceContextHolder.get()
+        if routing_key is None:
+            return self._default_target
+        # @Slave 占位：走从库轮询
+        if is_slave_placeholder(routing_key):
+            return self.determine_slave_data_source()
+        pool = self._target_data_sources.get(routing_key)
+        if pool is None:
+            logger.warning(
+                "路由键 '%s' 未找到对应数据源，回退到默认目标", routing_key
+            )
+            return self._default_target
+        return pool
+
+    def determine_slave_data_source(self) -> Any:
+        """从 slave 池中轮询选择一个；无 slave 配置则回退到默认目标。"""
+        if self._slave_cycle is None:
+            return self._default_target
+        with self._lock:
+            slave_key = next(self._slave_cycle)
+        pool = self._target_data_sources.get(slave_key)
+        return pool if pool is not None else self._default_target
+
+    # ==================== 连接池接口（drop-in 替换） ====================
+
+    def get_connection(self) -> Any:
+        """获取连接：按路由键选择池，借用其 ``get_connection``。"""
+        pool = self.determine_target_data_source()
+        connection = pool.get_connection()
+        # 在连接上记录来源池，便于归还时路由；不支持属性设置时回退到侧表（按 id）
+        try:
+            connection.__spring_ds_source__ = pool
+        except (AttributeError, TypeError):
+            with self._lock:
+                self._connection_sources[id(connection)] = pool
+        return connection
+
+    def return_connection(self, pooled_conn: Any) -> None:
+        """归还连接：优先按连接上记录的来源池归还，未知则回到默认目标。"""
+        source_pool = getattr(pooled_conn, "__spring_ds_source__", None)
+        if source_pool is None:
+            with self._lock:
+                source_pool = self._connection_sources.pop(id(pooled_conn), None)
+        target = source_pool if source_pool is not None else self._default_target
+        try:
+            target.return_connection(pooled_conn)
+        finally:
+            try:
+                delattr(pooled_conn, "__spring_ds_source__")
+            except (AttributeError, TypeError):
+                pass
+
+    def get_pool_stats(self) -> Dict[str, Any]:
+        """返回各物理池的统计快照。"""
+        stats: Dict[str, Any] = {}
+        stats["__default__"] = self._safe_stats(self._default_target)
+        for key, pool in self._target_data_sources.items():
+            stats[key] = self._safe_stats(pool)
+        return stats
+
+    @staticmethod
+    def _safe_stats(pool: Any) -> Dict[str, Any]:
+        try:
+            result = pool.get_pool_stats()
+            return result if isinstance(result, dict) else {}
+        except Exception as exc:  # pragma: no cover - 防御性
+            return {"error": str(exc)}
+
+    # ==================== 运维辅助 ====================
+
+    def get_target_data_sources(self) -> Dict[str, Any]:
+        """返回具名物理池映射（只读视图）。"""
+        return dict(self._target_data_sources)
+
+    def get_default_target_data_source(self) -> Any:
+        return self._default_target
+
+    def get_slave_keys(self) -> List[str]:
+        return list(self._slave_keys)

spring/event/__init__.py

@@ -0,0 +1,7 @@
+"""Application event API."""
+
+from spring.annotations.core import ApplicationEvent, EventListener
+from .publisher import ApplicationEventPublisher
+
+__all__ = ["ApplicationEvent", "EventListener", "ApplicationEventPublisher"]
+

spring/event/publisher.py

@@ -0,0 +1,69 @@
+"""Synchronous application event publication for managed beans."""
+
+import asyncio
+import inspect
+import threading
+from typing import Any, Callable, List, Optional, Tuple, Type
+
+from spring.annotations.core import ApplicationEvent
+
+
+ListenerEntry = Tuple[Optional[Type[ApplicationEvent]], Callable, int, int]
+
+
+class ApplicationEventPublisher:
+    """Publish events to listeners registered by the application context."""
+
+    def __init__(self):
+        self._listeners: List[ListenerEntry] = []
+        self._lock = threading.RLock()
+        self._sequence = 0
+
+    def add_listener(
+        self,
+        callback: Callable,
+        event_type: Optional[Type[ApplicationEvent]] = None,
+        order: int = 0,
+    ) -> None:
+        with self._lock:
+            self._sequence += 1
+            self._listeners.append((event_type, callback, order, self._sequence))
+            self._listeners.sort(key=lambda item: (item[2], item[3]))
+
+    def remove_listener(self, callback: Callable) -> None:
+        with self._lock:
+            self._listeners = [
+                entry for entry in self._listeners if entry[1] != callback
+            ]
+
+    def publish_event(self, event: Any) -> ApplicationEvent:
+        if not isinstance(event, ApplicationEvent):
+            event = ApplicationEvent(source=event)
+
+        with self._lock:
+            listeners = list(self._listeners)
+
+        for event_type, callback, _, _ in listeners:
+            if event_type is not None and not isinstance(event, event_type):
+                continue
+            result = callback(event)
+            if inspect.isawaitable(result):
+                self._finish_awaitable(result)
+        return event
+
+    @staticmethod
+    def _finish_awaitable(awaitable) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            asyncio.run(awaitable)
+        else:
+            loop.create_task(awaitable)
+
+    def listener_count(self) -> int:
+        with self._lock:
+            return len(self._listeners)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._listeners.clear()

spring/excel/__init__.py

@@ -0,0 +1,51 @@
+"""SpringBootAI Excel 模块 —— 注解驱动的 Excel 读写（对齐 alibaba EasyExcel）。
+
+模块组成：
+- annotations:  ``@ExcelProperty`` / ``@ExcelIgnore`` / ``@excel_sheet`` 字段+类级注解
+                 （复用 ORM ``Column``/``@entity`` 元数据描述符范式）
+- converters:   ``Converter`` 接口 + 内置 int/float/bool/str/date/Decimal 转换器（按类型自动选择）
+- reader:       ``ExcelReader`` 读取引擎（表头映射/类型转换/多 sheet/head_row_number）
+- writer:       ``ExcelWriter`` 写入引擎（表头/顺序/样式/大数字防丢精度/多 sheet）
+- easy_excel:   ``EasyExcel`` 流式构建入口（对齐 alibaba EasyExcel API）
+- style:        默认表头/内容样式
+- exceptions:   ``ExcelError`` 异常族
+
+安装（可选依赖）::
+
+    pip install springbootAI[excel]      # 同时安装 openpyxl
+    pip install springbootAI[ai]         # AI 模块
+    pip install springbootAI[full]       # 全部可选依赖
+
+注解声明无需 openpyxl；仅 read/write 时检测，未安装抛 ``ExcelDependencyError`` 提示安装。
+"""
+from .exceptions import (
+    ExcelError, ExcelPropertyError, ExcelReadError, ExcelWriteError, ExcelDependencyError,
+)
+from .annotations import (
+    ExcelProperty, ExcelIgnore, ExcelSheet, excel_sheet,
+    ExcelColumnModel, parse_excel_columns,
+)
+from .converters import (
+    Converter, StringConverter, IntegerConverter, FloatConverter,
+    BooleanConverter, DateStringConverter, BigDecimalConverter, resolve_converter,
+)
+from .reader import ExcelReader
+from .writer import ExcelWriter
+from .easy_excel import EasyExcel, read_excel, write_excel
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # 异常
+    "ExcelError", "ExcelPropertyError", "ExcelReadError", "ExcelWriteError",
+    "ExcelDependencyError",
+    # 注解
+    "ExcelProperty", "ExcelIgnore", "ExcelSheet", "excel_sheet",
+    "ExcelColumnModel", "parse_excel_columns",
+    # 转换器
+    "Converter", "StringConverter", "IntegerConverter", "FloatConverter",
+    "BooleanConverter", "DateStringConverter", "BigDecimalConverter", "resolve_converter",
+    # 引擎
+    "ExcelReader", "ExcelWriter", "EasyExcel", "read_excel", "write_excel",
+    "__version__",
+]