springbootAI 1.8.0__py3-none-any.whl

spring/data/repository.py

@@ -0,0 +1,274 @@
+"""Spring Data 仓库抽象（对齐 ``org.springframework.data.repository.PagingAndSortingRepository``）。
+
+提供基于实体元数据的 CRUD + 分页 + 排序 + ``Specification`` 动态查询统一抽象。
+**复用现有范式不重复造轮子**：
+- 实体解析复用 ``DdlAutoManager._parse_entity``（与 ``OptimisticLockExecutor`` 同一 ``__new__`` 技巧），
+  无需 pool 即可解析表名/列/主键。
+- SQL 执行复用 ``OptimisticLockExecutor`` 的轻量范式（pool + cursor + ``_quote``），
+  不强依赖 PyMyBatis ``SqlSession``，降低使用门槛。
+- 列名翻译 ``_col_resolver`` 把 Python 属性名映射为真实列名（对齐 ``Column(name=...)``），
+  供 ``Sort`` / ``Specification`` 复用。
+
+与 Java 差异：
+- Java 的 Spring Data Repository 是接口 + 方法名解析（运行时动态代理生成实现）；
+  Python 无等价元编程惯例，故采用**基类继承** + 显式方法，更符合 Python 习惯。
+- ``@DataRepository`` 为标记注解（声明管理的实体类型），实际能力由继承基类获得。
+"""
+import inspect
+from typing import Any, Callable, Dict, Generic, List, Optional, Type, TypeVar
+
+from spring.data.page import Page, Pageable, Sort
+from spring.data.specification import ColResolver, Specification
+
+T = TypeVar("T")
+
+
+def _parse_entity_table(entity_class: Type):
+    """复用 ``DdlAutoManager._parse_entity`` 解析实体元数据（不依赖 pool）。
+
+    与 ``OptimisticLockExecutor._parse_columns`` 同一技巧：``__new__`` 绕过 ``__init__``
+    （后者需要 pool），直接调用纯解析方法。
+    """
+    from spring.orm.ddl_auto import DdlAutoManager
+    tmp = DdlAutoManager.__new__(DdlAutoManager)
+    tmp.dialect = "sqlite"
+    tmp.mode = None  # type: ignore
+    return tmp._parse_entity(entity_class)
+
+
+class PagingAndSortingRepository(Generic[T]):
+    """分页排序仓库基类。
+
+    Args:
+        pool:          数据库连接池（需支持 ``connection()`` 返回带 ``cursor()``/``commit()``/``close()`` 的连接）。
+        entity_class:  管理的实体类（带 ``@entity``/``Column`` 元数据）。
+        dialect:       SQL 方言（mysql/postgresql/sqlite），影响标识符引用。
+    """
+
+    def __init__(self, pool: Any, entity_class: Type[T], dialect: str = "sqlite"):
+        self.pool = pool
+        self.entity_class = entity_class
+        self.dialect = dialect.lower()
+        self._table = _parse_entity_table(entity_class)
+        self._columns: List[dict] = [c for c in self._table.columns if not c.get("transient")]
+        self._pk = next((c for c in self._columns if c.get("primary_key")), None)
+        if self._pk is None:
+            raise ValueError(
+                f"实体 {entity_class.__name__} 未声明主键（@Id），无法构建 Repository"
+            )
+        # py_name -> sql 列名 映射，供 Sort/Specification 翻译
+        self._col_map: Dict[str, str] = {
+            c.get("py_name") or c.get("name"): c.get("name") or c.get("py_name")
+            for c in self._columns
+        }
+
+    # ==================== 内部工具 ====================
+
+    def _quote(self, identifier: str) -> str:
+        if self.dialect == "mysql":
+            return f"`{identifier}`"
+        return f'"{identifier}"'
+
+    def _col_resolver(self, prop: str) -> str:
+        return self._col_map.get(prop, prop)
+
+    def _column_list(self) -> str:
+        return ", ".join(self._quote(c["name"]) for c in self._columns)
+
+    def _row_to_entity(self, row: tuple) -> T:
+        """按列顺序把行元组转为实体实例。"""
+        obj = self.entity_class.__new__(self.entity_class)
+        for col, val in zip(self._columns, row):
+            setattr(obj, col["py_name"], val)
+        return obj  # type: ignore
+
+    def _get_field(self, entity: T, py_name: str) -> Any:
+        return getattr(entity, py_name, None)
+
+    def _execute(self, sql: str, params: list, fetch: bool = False):
+        """执行 SQL。fetch=True 返回行列表，否则返回影响行数。"""
+        conn = None
+        try:
+            if hasattr(self.pool, "connection"):
+                conn = self.pool.connection()
+            else:
+                conn = self.pool
+            cursor = conn.cursor()
+            cursor.execute(sql, params)
+            if fetch:
+                rows = cursor.fetchall()
+                conn.commit()
+                return rows
+            # DML：rowcount 为影响行数（sqlite3/MySQLdb/psycopg2 一致）
+            affected = cursor.rowcount
+            conn.commit()
+            return affected
+        finally:
+            if conn is not None and hasattr(self.pool, "connection"):
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+
+    def _fetchone(self, sql: str, params: list):
+        conn = None
+        try:
+            if hasattr(self.pool, "connection"):
+                conn = self.pool.connection()
+            else:
+                conn = self.pool
+            cursor = conn.cursor()
+            cursor.execute(sql, params)
+            row = cursor.fetchone()
+            conn.commit()
+            return row
+        finally:
+            if conn is not None and hasattr(self.pool, "connection"):
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+
+    # ==================== CRUD ====================
+
+    def save(self, entity: T) -> T:
+        """保存实体：主键已存在则 UPDATE，否则 INSERT。"""
+        pk_val = self._get_field(entity, self._pk["py_name"])
+        if pk_val is not None and self.exists_by_id(pk_val):
+            return self._update(entity)
+        return self._insert(entity)
+
+    def _insert(self, entity: T) -> T:
+        non_auto = [c for c in self._columns if not c.get("auto_increment")]
+        cols = ", ".join(self._quote(c["name"]) for c in non_auto)
+        placeholders = ", ".join("?" for _ in non_auto)
+        params = [self._get_field(entity, c["py_name"]) for c in non_auto]
+        sql = f"INSERT INTO {self._quote(self._table.table_name)} ({cols}) VALUES ({placeholders})"
+        self._execute(sql, params)
+        # 自增主键回填
+        if self._pk.get("auto_increment") and self._get_field(entity, self._pk["py_name"]) is None:
+            last = self._fetchone(
+                f"SELECT {self._quote(self._pk['name'])} FROM "
+                f"{self._quote(self._table.table_name)} ORDER BY "
+                f"{self._quote(self._pk['name'])} DESC LIMIT 1", []
+            )
+            if last:
+                setattr(entity, self._pk["py_name"], last[0])
+        return entity
+
+    def _update(self, entity: T) -> T:
+        non_pk = [c for c in self._columns if not c.get("primary_key")]
+        set_parts = ", ".join(f"{self._quote(c['name'])} = ?" for c in non_pk)
+        params = [self._get_field(entity, c["py_name"]) for c in non_pk]
+        pk_val = self._get_field(entity, self._pk["py_name"])
+        params.append(pk_val)
+        sql = (f"UPDATE {self._quote(self._table.table_name)} SET {set_parts} "
+               f"WHERE {self._quote(self._pk['name'])} = ?")
+        self._execute(sql, params)
+        return entity
+
+    def find_by_id(self, id_: Any) -> Optional[T]:
+        sql = (f"SELECT {self._column_list()} FROM {self._quote(self._table.table_name)} "
+               f"WHERE {self._quote(self._pk['name'])} = ?")
+        row = self._fetchone(sql, [id_])
+        return self._row_to_entity(row) if row else None
+
+    def exists_by_id(self, id_: Any) -> bool:
+        sql = (f"SELECT 1 FROM {self._quote(self._table.table_name)} "
+               f"WHERE {self._quote(self._pk['name'])} = ? LIMIT 1")
+        return self._fetchone(sql, [id_]) is not None
+
+    def count(self, specification: Optional[Specification] = None) -> int:
+        where, params = self._spec_where(specification)
+        sql = f"SELECT COUNT(*) FROM {self._quote(self._table.table_name)}{where}"
+        row = self._fetchone(sql, params)
+        return int(row[0]) if row else 0
+
+    def delete_by_id(self, id_: Any) -> int:
+        sql = (f"DELETE FROM {self._quote(self._table.table_name)} "
+               f"WHERE {self._quote(self._pk['name'])} = ?")
+        return self._execute(sql, [id_])
+
+    def delete(self, entity: T) -> int:
+        return self.delete_by_id(self._get_field(entity, self._pk["py_name"]))
+
+    def delete_all(self, specification: Optional[Specification] = None) -> int:
+        where, params = self._spec_where(specification)
+        sql = f"DELETE FROM {self._quote(self._table.table_name)}{where}"
+        return self._execute(sql, params)
+
+    # ==================== 查询（排序/分页/动态） ====================
+
+    def find_all(self,
+                 sort: Optional[Sort] = None,
+                 specification: Optional[Specification] = None,
+                 pageable: Optional[Pageable] = None) -> Any:
+        """统一查询入口。
+
+        - 仅传 ``sort``：返回 ``List[T]``。
+        - 仅传 ``specification``：返回 ``List[T]``。
+        - 传 ``pageable``：返回 ``Page[T]``（可同时带 ``specification``）。
+        """
+        where, params = self._spec_where(specification)
+        if pageable is not None:
+            return self._find_page(pageable, where, params, specification)
+        order = self._sort_sql(sort or Sort.unsorted())
+        sql = (f"SELECT {self._column_list()} FROM {self._quote(self._table.table_name)}"
+               f"{where}{order}")
+        rows = self._execute(sql, params, fetch=True)
+        return [self._row_to_entity(r) for r in rows]
+
+    def find_one(self, specification: Specification) -> Optional[T]:
+        where, params = self._spec_where(specification)
+        sql = (f"SELECT {self._column_list()} FROM {self._quote(self._table.table_name)}"
+               f"{where} LIMIT 1")
+        row = self._fetchone(sql, params)
+        return self._row_to_entity(row) if row else None
+
+    def _find_page(self, pageable: Pageable, where: str, params: list,
+                   specification: Optional[Specification] = None) -> Page:
+        order = self._sort_sql(pageable.sort)
+        # SQLite/MySQL/PostgreSQL 均支持 LIMIT/OFFSET
+        page_sql = (f"SELECT {self._column_list()} FROM {self._quote(self._table.table_name)}"
+                    f"{where}{order} LIMIT ? OFFSET ?")
+        rows = self._execute(page_sql, params + [pageable.limit, pageable.offset], fetch=True)
+        content = [self._row_to_entity(r) for r in rows]
+        # total 必须带同一 specification，否则分页总数与筛选条件不一致
+        total = self.count(specification)
+        return Page(content, pageable, total)
+
+    def _spec_where(self, specification: Optional[Specification]) -> tuple:
+        if specification is None:
+            return "", []
+        sql, params = specification.to_predicate(self._col_resolver)
+        return (f" WHERE {sql}" if sql else ""), params
+
+    def _sort_sql(self, sort: Sort) -> str:
+        if not sort.is_sorted:
+            return ""
+        return " ORDER BY " + sort.to_sql(lambda p: self._quote(self._col_resolver(p)))
+
+
+# ==================== 注解（标记） ====================
+
+class DataRepository:
+    """``@DataRepository(EntityClass)`` 标记注解：声明仓库管理的实体类型。
+
+    标记后可通过 ``get_data_repository_entity(cls)`` 读取实体类型，便于 IoC 集成
+    （如 ``@Bean`` 工厂方法根据实体类型构造 ``PagingAndSortingRepository``）。
+
+    注意：本注解仅声明元数据，**不**自动生成仓库实现——仓库能力由继承
+    ``PagingAndSortingRepository`` 获得（对齐 Python 习惯，与 Java 接口代理方式不同）。
+    """
+
+    def __init__(self, entity_class: Type):
+        self.entity_class = entity_class
+
+    def __call__(self, target: Type) -> Type:
+        setattr(target, "__data_repository__", self)
+        return target
+
+
+def get_data_repository_entity(cls: Type) -> Optional[Type]:
+    ann = getattr(cls, "__data_repository__", None)
+    return ann.entity_class if ann is not None else None

spring/data/specification.py

@@ -0,0 +1,228 @@
+"""Spring Data JPA 风格的动态查询 ``Specification``（对齐 ``org.springframework.data.jpa.domain.Specification``）。
+
+将查询条件抽象为可组合的谓词，``to_predicate()`` 返回 ``(where_sql, params)``，
+由 ``PagingAndSortingRepository`` 拼入 SQL。支持 ``and`` / ``or`` / ``not`` 复合。
+
+与 Java 差异：
+- Java 的 ``Specification.to_predicate(Root, CriteriaQuery, CriteriaBuilder)`` 依赖 JPA Criteria API；
+  Python 无等价物，故简化为返回 ``(where_sql_fragment, params)`` 元组。
+- 列名翻译通过 ``col_resolver``（``property_name -> sql_column_name``）回调完成，
+  与 ``Pageable.Sort`` 一致，避免 ``Column(name=...)`` 自定义列名时生成错误 SQL。
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Callable, List, Optional, Tuple, TypeVar
+
+T = TypeVar("T")
+
+# 谓词返回类型：(SQL 片段, 参数列表)；SQL 片段为空串表示无条件
+Predicate = Tuple[str, List[Any]]
+ColResolver = Callable[[str], str]
+
+
+class Specification(ABC):
+    """查询规范抽象基类。"""
+
+    @abstractmethod
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        """返回 ``(where_sql, params)``。``where_sql`` 为空串表示无条件。"""
+
+    def and_(self, other: "Specification") -> "Specification":
+        return And(self, other)
+
+    def or_(self, other: "Specification") -> "Specification":
+        return Or(self, other)
+
+    def not_(self) -> "Specification":
+        return Not(self)
+
+
+def _resolve(prop: str, col_resolver: Optional[ColResolver]) -> str:
+    return col_resolver(prop) if col_resolver else prop
+
+
+class _Empty(Specification):
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        return "", []
+
+
+class And(Specification):
+    def __init__(self, *specs: Specification):
+        self.specs = specs
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        parts: List[str] = []
+        params: List[Any] = []
+        for s in self.specs:
+            sql, p = s.to_predicate(col_resolver)
+            if sql:
+                parts.append(f"({sql})")
+                params.extend(p)
+        if not parts:
+            return "", []
+        return " AND ".join(parts), params
+
+
+class Or(Specification):
+    def __init__(self, *specs: Specification):
+        self.specs = specs
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        parts: List[str] = []
+        params: List[Any] = []
+        for s in self.specs:
+            sql, p = s.to_predicate(col_resolver)
+            if sql:
+                parts.append(f"({sql})")
+                params.extend(p)
+        if not parts:
+            return "", []
+        return " OR ".join(parts), params
+
+
+class Not(Specification):
+    def __init__(self, spec: Specification):
+        self.spec = spec
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        sql, params = self.spec.to_predicate(col_resolver)
+        if not sql:
+            return "", []
+        return f"NOT ({sql})", params
+
+
+class _Comparison(Specification):
+    """单字段比较谓词基类。"""
+
+    def __init__(self, property: str, op: str, value: Any, negated: bool = False):
+        self.property = property
+        self.op = op
+        self.value = value
+        self.negated = negated
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        col = _resolve(self.property, col_resolver)
+        op = self.op if not self.negated else _negate_op(self.op)
+        return f"{col} {op} ?", [self.value]
+
+
+def _negate_op(op: str) -> str:
+    return {
+        "=": "<>", "<>": "=", "!=": "=",
+        ">": "<=", "<": ">=", ">=": "<", "<=": ">",
+        "LIKE": "NOT LIKE", "IN": "NOT IN", "IS": "IS NOT",
+    }.get(op, f"NOT {op}")
+
+
+class _Like(Specification):
+    def __init__(self, property: str, pattern: str, case_insensitive: bool = False):
+        self.property = property
+        self.pattern = pattern
+        self.case_insensitive = case_insensitive
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        col = _resolve(self.property, col_resolver)
+        if self.case_insensitive:
+            return f"LOWER({col}) LIKE LOWER(?)", [self.pattern]
+        return f"{col} LIKE ?", [self.pattern]
+
+
+class _In(Specification):
+    def __init__(self, property: str, values: list):
+        self.property = property
+        self.values = list(values)
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        col = _resolve(self.property, col_resolver)
+        if not self.values:
+            return "1=0", []  # 空集合：恒假
+        placeholders = ", ".join("?" for _ in self.values)
+        return f"{col} IN ({placeholders})", list(self.values)
+
+
+class _IsNull(Specification):
+    def __init__(self, property: str, negate: bool = False):
+        self.property = property
+        self.negate = negate
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        col = _resolve(self.property, col_resolver)
+        return (f"{col} IS NOT NULL" if self.negate else f"{col} IS NULL"), []
+
+
+class _Between(Specification):
+    def __init__(self, property: str, low: Any, high: Any):
+        self.property = property
+        self.low = low
+        self.high = high
+
+    def to_predicate(self, col_resolver: Optional[ColResolver] = None) -> Predicate:
+        col = _resolve(self.property, col_resolver)
+        return f"{col} BETWEEN ? AND ?", [self.low, self.high]
+
+
+class Specifications:
+    """``Specification`` 静态工厂（对齐 Spring ``Specifications`` 工具类）。"""
+
+    @staticmethod
+    def empty() -> Specification:
+        return _Empty()
+
+    @staticmethod
+    def where(spec: Optional[Specification] = None) -> Specification:
+        return spec if spec is not None else _Empty()
+
+    @staticmethod
+    def equal(property: str, value: Any) -> Specification:
+        return _Comparison(property, "=", value)
+
+    @staticmethod
+    def not_equal(property: str, value: Any) -> Specification:
+        return _Comparison(property, "<>", value)
+
+    @staticmethod
+    def greater_than(property: str, value: Any) -> Specification:
+        return _Comparison(property, ">", value)
+
+    @staticmethod
+    def greater_equal(property: str, value: Any) -> Specification:
+        return _Comparison(property, ">=", value)
+
+    @staticmethod
+    def less_than(property: str, value: Any) -> Specification:
+        return _Comparison(property, "<", value)
+
+    @staticmethod
+    def less_equal(property: str, value: Any) -> Specification:
+        return _Comparison(property, "<=", value)
+
+    @staticmethod
+    def like(property: str, pattern: str, case_insensitive: bool = False) -> Specification:
+        return _Like(property, pattern, case_insensitive)
+
+    @staticmethod
+    def in_(property: str, values: list) -> Specification:
+        return _In(property, values)
+
+    @staticmethod
+    def is_null(property: str) -> Specification:
+        return _IsNull(property, negate=False)
+
+    @staticmethod
+    def is_not_null(property: str) -> Specification:
+        return _IsNull(property, negate=True)
+
+    @staticmethod
+    def between(property: str, low: Any, high: Any) -> Specification:
+        return _Between(property, low, high)
+
+    @staticmethod
+    def and_(spec: Specification, *others: Specification) -> Specification:
+        return And(spec, *others)
+
+    @staticmethod
+    def or_(spec: Specification, *others: Specification) -> Specification:
+        return Or(spec, *others)
+
+    @staticmethod
+    def not_(spec: Specification) -> Specification:
+        return Not(spec)

spring/datasource/__init__.py

@@ -0,0 +1,66 @@
+"""SpringBootAI 多数据源读写分离模块（对齐 Spring ``AbstractRoutingDataSource`` +
+``dynamic-datasource-spring-boot-starter`` 的 ``@DS``/``@Master``/``@Slave``）。
+
+模块组成：
+- ``context``:  ``DataSourceContextHolder`` —— ``ContextVar`` 持有当前路由键。
+- ``dynamic``:  ``DynamicRoutingDataSource`` —— 多池路由 + 从库轮询 + 故障回退。
+- ``annotations``: ``@DS``/``@Master``/``@Slave`` 注解 + 方法级 AOP 切面。
+
+典型用法::
+
+    from spring.datasource import (
+        DynamicRoutingDataSource, DS, Master, Slave,
+        DataSourceContextHolder, apply_ds_annotations,
+    )
+
+    # 1. 装配动态数据源（master + 两个 slave）
+    dynamic_ds = DynamicRoutingDataSource(
+        target_data_sources={"slave_1": pool1, "slave_2": pool2},
+        default_target_data_source=master_pool,
+        slave_keys=["slave_1", "slave_2"],
+    )
+
+    # 2. 注解驱动路由
+    class OrderService:
+        @Master
+        def create_order(self, order): ...   # 走主库写
+        @Slave
+        def list_orders(self): ...            # 走从库读（轮询）
+        @DS("report_db")
+        def report(self): ...                 # 走具名数据源
+
+设计原则：**复用项目既有范式**，注解继承 ``SpringAnnotation``，AOP 注册对齐
+``@Validate``/``@Cacheable``，连接池接口对齐 ``ConnectionPool``，未引入第三方库。
+
+与 Java 的差异：
+- 用 ``ContextVar`` 替代 ``ThreadLocal``，兼容 ``asyncio`` 协程。
+- ``@Slave`` 用占位路由键 + ``DynamicRoutingDataSource`` 轮询解析，无需运行时织入具体键。
+"""
+from .context import DataSourceContextHolder, routing_scope
+from .dynamic import DynamicRoutingDataSource
+from .annotations import (
+    DS, Master, Slave,
+    ds_route_decorator, ds_decorator_factory, apply_ds_annotations, is_slave_placeholder,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "DataSourceContextHolder",
+    "routing_scope",
+    "DynamicRoutingDataSource",
+    "DS", "Master", "Slave",
+    "ds_route_decorator", "ds_decorator_factory",
+    "apply_ds_annotations", "is_slave_placeholder",
+    "__version__",
+]
+
+# 接入 comprehensive_aop 受管 Bean 包装链路（对齐 @Validate/@Cacheable 注册模式）。
+# 在受管 Bean 上标注 @DS/@Master/@Slave 时，IoC 容器会通过 apply_annotations 自动包装。
+try:
+    from spring.aop.comprehensive_aop import ANNOTATION_DECORATORS
+    for _ann_cls in (DS, Master, Slave):
+        if _ann_cls not in ANNOTATION_DECORATORS:
+            ANNOTATION_DECORATORS[_ann_cls] = ds_decorator_factory
+except ImportError:  # pragma: no cover - comprehensive_aop 未安装时静默跳过
+    pass