aury-boot 0.0.27__tar.gz → 0.0.28__tar.gz

{aury_boot-0.0.27 → aury_boot-0.0.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.27
+Version: 0.0.28
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.27 → aury_boot-0.0.28}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.27'
-__version_tuple__ = version_tuple = (0, 0, 27)
+__version__ = version = '0.0.28'
+__version_tuple__ = version_tuple = (0, 0, 28)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.27 → aury_boot-0.0.28}/aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -75,6 +75,8 @@ mypy {package_name}/
 2. **[aury_docs/02-repository.md](./aury_docs/02-repository.md)** - Repository 使用
    - BaseRepository API
    - Filters 语法（__gt, __like 等）
+   - Cursor 分页（推荐，性能更优）
+   - 流式查询（大数据处理）
    - 自动提交机制
 
 3. **[aury_docs/03-service.md](./aury_docs/03-service.md)** - Service 编写与事务

{aury_boot-0.0.27 → aury_boot-0.0.28}/aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl

@@ -72,6 +72,37 @@ result = await repo.paginate(
 # - result.has_next: bool      # 是否有下一页
 # - result.has_prev: bool      # 是否有上一页
 
+# === Cursor 分页（推荐，性能更优） ===
+from aury.boot.domain.pagination import CursorPaginationParams
+
+# 第一页
+result = await repo.cursor_paginate(
+    CursorPaginationParams(limit=20),
+    is_active=True,
+)
+
+# 下一页（带上 cursor）
+result = await repo.cursor_paginate(
+    CursorPaginationParams(cursor=result.next_cursor, limit=20),
+    is_active=True,
+)
+
+# CursorPaginationResult 结构：
+# - result.items: list[T]          # 数据列表
+# - result.next_cursor: str | None # 下一页游标
+# - result.prev_cursor: str | None # 上一页游标
+# - result.has_next: bool          # 是否有下一页
+# - result.has_prev: bool          # 是否有上一页
+
+# === 流式查询（大数据处理） ===
+# 逐条流式处理，不会一次性加载到内存
+async for user in repo.stream(batch_size=1000, is_active=True):
+    await process(user)
+
+# 批量流式处理
+async for batch in repo.stream_batches(batch_size=1000):
+    await bulk_sync_to_es(batch)
+
 # === 创建 ===
 user = await repo.create({{"name": "Alice", "email": "a@b.com"}})
 users = await repo.batch_create([{{"name": "A"}}, {{"name": "B"}}])  # 返回实体

{aury_boot-0.0.27 → aury_boot-0.0.28}/aury/boot/domain/repository/impl.py

@@ -18,6 +18,8 @@ from aury.boot.common.logging import logger
 from aury.boot.domain.exceptions import VersionConflictError
 from aury.boot.domain.models import GUID, Base
 from aury.boot.domain.pagination import (
+    CursorPaginationParams,
+    CursorPaginationResult,
     PaginationParams,
     PaginationResult,
     SortParams,
@@ -263,6 +265,168 @@ class BaseRepository[ModelType: Base](IRepository[ModelType]):
             pagination_params=pagination_params,
         )
     
+    async def cursor_paginate(
+        self,
+        params: CursorPaginationParams,
+        cursor_field: str = "id",
+        **filters
+    ) -> CursorPaginationResult[ModelType]:
+        """基于游标的分页查询。
+        
+        适用于无限滚动、大数据集等场景，性能优于 offset 分页。
+        
+        Args:
+            params: 游标分页参数（cursor, limit, direction）
+            cursor_field: 游标字段名，默认 "id"，必须是有序且唯一的字段
+            **filters: 过滤条件
+            
+        Returns:
+            CursorPaginationResult: 包含 items, next_cursor, prev_cursor, has_next, has_prev
+            
+        示例:
+            # 第一页
+            result = await repo.cursor_paginate(
+                CursorPaginationParams(limit=20),
+                status="active"
+            )
+            
+            # 下一页
+            result = await repo.cursor_paginate(
+                CursorPaginationParams(cursor=result.next_cursor, limit=20),
+                status="active"
+            )
+        """
+        import base64
+        import json
+        
+        query = self._build_base_query()
+        query = self._apply_filters(query, **filters)
+        
+        cursor_attr = _get_model_attr(self._model_class, cursor_field)
+        if cursor_attr is None:
+            raise AttributeError(f"模型 {self._model_class.__name__} 没有 '{cursor_field}' 字段")
+        
+        # 解码 cursor
+        cursor_value = None
+        if params.cursor:
+            try:
+                decoded = base64.urlsafe_b64decode(params.cursor.encode()).decode()
+                cursor_value = json.loads(decoded)
+            except Exception:
+                raise ValueError("无效的游标") from None
+        
+        # 根据方向决定查询条件和排序
+        is_next = params.direction == "next"
+        if cursor_value is not None:
+            if is_next:
+                query = query.where(cursor_attr > cursor_value)
+            else:
+                query = query.where(cursor_attr < cursor_value)
+        
+        # 排序
+        if is_next:
+            query = query.order_by(cursor_attr)
+        else:
+            query = query.order_by(cursor_attr.desc())
+        
+        # 多取一条判断是否有更多
+        query = query.limit(params.limit + 1)
+        result = await self._session.execute(query)
+        items = list(result.scalars().all())
+        
+        has_more = len(items) > params.limit
+        if has_more:
+            items = items[:params.limit]
+        
+        # 反向查询时反转结果
+        if not is_next:
+            items = list(reversed(items))
+        
+        # 生成游标
+        def encode_cursor(value) -> str:
+            return base64.urlsafe_b64encode(json.dumps(value).encode()).decode()
+        
+        next_cursor = None
+        prev_cursor = None
+        
+        if items:
+            last_value = getattr(items[-1], cursor_field)
+            first_value = getattr(items[0], cursor_field)
+            
+            if is_next:
+                if has_more:
+                    next_cursor = encode_cursor(last_value)
+                if cursor_value is not None:
+                    prev_cursor = encode_cursor(first_value)
+            else:
+                if cursor_value is not None:
+                    next_cursor = encode_cursor(last_value)
+                if has_more:
+                    prev_cursor = encode_cursor(first_value)
+        
+        return CursorPaginationResult.create(
+            items=items,
+            next_cursor=next_cursor,
+            prev_cursor=prev_cursor,
+            limit=params.limit,
+        )
+    
+    async def stream(
+        self,
+        batch_size: int = 1000,
+        **filters
+    ):
+        """流式查询，使用数据库原生 server-side cursor。
+        
+        适用于大数据集处理，避免一次性加载所有数据到内存。
+        
+        Args:
+            batch_size: 每批次获取的记录数，默认 1000
+            **filters: 过滤条件
+            
+        Yields:
+            ModelType: 模型实例
+            
+        示例:
+            async for user in repo.stream(batch_size=500, status="active"):
+                process(user)
+        """
+        query = self._build_base_query()
+        query = self._apply_filters(query, **filters)
+        
+        async with self._session.stream_scalars(
+            query.execution_options(yield_per=batch_size)
+        ) as result:
+            async for item in result:
+                yield item
+    
+    async def stream_batches(
+        self,
+        batch_size: int = 1000,
+        **filters
+    ):
+        """批量流式查询，每次返回一批数据。
+        
+        Args:
+            batch_size: 每批次的记录数，默认 1000
+            **filters: 过滤条件
+            
+        Yields:
+            list[ModelType]: 一批模型实例
+            
+        示例:
+            async for batch in repo.stream_batches(batch_size=500):
+                bulk_process(batch)
+        """
+        query = self._build_base_query()
+        query = self._apply_filters(query, **filters)
+        
+        async with self._session.stream_scalars(
+            query.execution_options(yield_per=batch_size)
+        ) as result:
+            async for partition in result.partitions():
+                yield list(partition)
+    
     async def count(self, **filters) -> int:
         query = select(func.count()).select_from(self._model_class)
         if hasattr(self._model_class, "deleted_at"):