aury-boot 0.0.27__py3-none-any.whl → 0.0.28__py3-none-any.whl

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/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/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/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"):

{aury_boot-0.0.27.dist-info → aury_boot-0.0.28.dist-info}/METADATA

@@ -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.dist-info → aury_boot-0.0.28.dist-info}/RECORD

@@ -1,5 +1,5 @@
 aury/boot/__init__.py,sha256=pCno-EInnpIBa1OtxNYF-JWf9j95Cd2h6vmu0xqa_-4,1791
-aury/boot/_version.py,sha256=vq5GihUa4KrDz-Hix5Er9gtVMhfHNDBoLhzP1VsvNuE,706
+aury/boot/_version.py,sha256=rsZxmANBVfE-nN63y-ZZ_71Lkm6YP4u4TgVEBJV3mNM,706
 aury/boot/application/__init__.py,sha256=0o_XmiwFCeAu06VHggS8I1e7_nSMoRq0Hcm0fYfCywU,3071
 aury/boot/application/adapter/__init__.py,sha256=e1bcSb1bxUMfofTwiCuHBZJk5-STkMCWPF2EJXHQ7UU,3976
 aury/boot/application/adapter/base.py,sha256=Ar_66fiHPDEmV-1DKnqXKwc53p3pozG31bgTJTEUriY,15763
@@ -61,7 +61,7 @@ aury/boot/commands/templates/generate/model.py.tpl,sha256=knFwMyGZ7wMpzH4_bQD_V1
 aury/boot/commands/templates/generate/repository.py.tpl,sha256=xoEg6lPAaLIRDeFy4I0FBsPPVLSy91h6xosAlaCL_mM,590
 aury/boot/commands/templates/generate/schema.py.tpl,sha256=HIaY5B0UG_S188nQLrZDEJ0q73WPdb7BmCdc0tseZA4,545
 aury/boot/commands/templates/generate/service.py.tpl,sha256=2hwQ8e4a5d_bIMx_jGDobdmKPMFLBlfQrQVQH4Ym5k4,1842
-aury/boot/commands/templates/project/AGENTS.md.tpl,sha256=AzjUt98ojms1CSUT1kNzCNLZFLBW5BGXpSwm0yJzYeI,7797
+aury/boot/commands/templates/project/AGENTS.md.tpl,sha256=-KrVhPqwVaf1IWRIl4L9Yb0LSRihq69ZaZ-ynnGM4W8,7882
 aury/boot/commands/templates/project/README.md.tpl,sha256=oCeBiukk6Pa3hrCKybkfM2sIRHsPZ15nlwuFTUSFDwY,2459
 aury/boot/commands/templates/project/admin_console_init.py.tpl,sha256=K81L14thyEhRA8lFCQJVZL_NU22-sBz0xS68MJPeoCo,1541
 aury/boot/commands/templates/project/config.py.tpl,sha256=H_B05FypBJxTjb7qIL91zC1C9e37Pk7C9gO0-b3CqNs,1009
@@ -70,7 +70,7 @@ aury/boot/commands/templates/project/gitignore.tpl,sha256=OI0nt9u2E9EC-jAMoh3gpq
 aury/boot/commands/templates/project/main.py.tpl,sha256=Q61ve3o1VkNPv8wcQK7lUosne18JWYeItxoXVNNoYJM,1070
 aury/boot/commands/templates/project/aury_docs/00-overview.md.tpl,sha256=8Aept3yEAe9cVdRvkddr_oEF-lr2riPXYRzBuw_6DBA,2138
 aury/boot/commands/templates/project/aury_docs/01-model.md.tpl,sha256=1mQ3hGDxqEZjev4CD5-3dzYRFVonPNcAaStI1UBEUyM,6811
-aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl,sha256=yfKPYZ7x74BEF7wFp9u3S7xKr4Ld9MqXOItGZo5NM9Q,6819
+aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl,sha256=JfUVdrIgW7_J6JGCcB-_uP_x-gCtjKiewwGv4Xr44QI,7803
 aury/boot/commands/templates/project/aury_docs/03-service.md.tpl,sha256=Dg_8RGSeRmmyQrhhpppEoxl-6C5pNe9M2OzVOl1kjSk,13102
 aury/boot/commands/templates/project/aury_docs/04-schema.md.tpl,sha256=ZwwKhUbLI--PEEmwnuo2fIZrhCEZagBN6fRNDTFCnNk,2891
 aury/boot/commands/templates/project/aury_docs/05-api.md.tpl,sha256=oPzda3V6ZPDDEW-5MwyzmsMRuu5mXrsRGEq3lj0M-58,2997
@@ -124,7 +124,7 @@ aury/boot/domain/models/mixins.py,sha256=7s4m4fzt0vWX71aTHgsoagjxSZZZ4_xSea_m0D8
 aury/boot/domain/models/models.py,sha256=hNze58wPZkZ8QG2_pyszDsyKNjz2UgiRDzmneiCWLQs,2728
 aury/boot/domain/pagination/__init__.py,sha256=HSU_NyLP-ij7ZDUi-ARSSvNkvhW1_wON2Zvu2QlF6HM,11890
 aury/boot/domain/repository/__init__.py,sha256=dnmN8xFu1ASbLnzL6vx8gMoch7xBGxkJkxs9G1iGLGg,490
-aury/boot/domain/repository/impl.py,sha256=CKpCJhgPg5uh3D2h7PVDApM9aT3sk6NNfn5hvP8CEQM,16552
+aury/boot/domain/repository/impl.py,sha256=BeWe6pMBP_OvxX91FmckxAZlM2qejol06If_UBy8FtU,22016
 aury/boot/domain/repository/interceptors.py,sha256=SCTjRmBYwevAMlJ8U1uw-_McsDetNNQ7q0Da5lmfj_E,1238
 aury/boot/domain/repository/interface.py,sha256=CmkiqVhhHPx_xcpuBCz11Vr26-govwYBxFsQ8myEVyw,2904
 aury/boot/domain/repository/query_builder.py,sha256=pFErMzsBql-T6gBX0S4FxIheCkNaGjpSewzcJ2DxrUU,10890
@@ -192,7 +192,7 @@ aury/boot/testing/client.py,sha256=KOg1EemuIVsBG68G5y0DjSxZGcIQVdWQ4ASaHE3o1R0,4
 aury/boot/testing/factory.py,sha256=8GvwX9qIDu0L65gzJMlrWB0xbmJ-7zPHuwk3eECULcg,5185
 aury/boot/toolkit/__init__.py,sha256=AcyVb9fDf3CaEmJPNkWC4iGv32qCPyk4BuFKSuNiJRQ,334
 aury/boot/toolkit/http/__init__.py,sha256=zIPmpIZ9Qbqe25VmEr7jixoY2fkRbLm7NkCB9vKpg6I,11039
-aury_boot-0.0.27.dist-info/METADATA,sha256=qbe9mHwMgUyqjel4saqlfiZLtS2j_IAbMOqLkkr04ys,7695
-aury_boot-0.0.27.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-aury_boot-0.0.27.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
-aury_boot-0.0.27.dist-info/RECORD,,
+aury_boot-0.0.28.dist-info/METADATA,sha256=7fabDsArEBQ_L5MoamQPJa9xmdi19-CLTSGG5YgPQPw,7695
+aury_boot-0.0.28.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+aury_boot-0.0.28.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
+aury_boot-0.0.28.dist-info/RECORD,,