aury-boot 0.0.27__py3-none-any.whl → 0.0.29__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.29'
+__version_tuple__ = version_tuple = (0, 0, 29)
 
 __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 编写与事务
@@ -162,15 +164,25 @@ class User(Base): ...
 - 写操作**必须**使用 `@transactional` 装饰器
 - 只读操作可以不加事务装饰器
 - 跨 Service 调用通过共享 session 实现事务共享
+- **后台任务必须**使用 `@isolated_task` 装饰器
 
 ```python
-from aury.boot.domain.transaction import transactional
+from aury.boot.domain.transaction import transactional, isolated_task
 
 class UserService(BaseService):
     @transactional
     async def create(self, data: UserCreate) -> User:
         # 自动事务管理
         return await self.repo.create(data.model_dump())
+
+
+# 后台任务必须加 @isolated_task，否则事务不会提交
+@isolated_task
+async def background_upload(space_id: int, url: str):
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            await repo.update(...)
 ```
 
 ### Manager API 规范

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/commands/templates/project/aury_docs/03-service.md.tpl

@@ -396,3 +396,63 @@ DATABASE_ISOLATION_LEVEL=REPEATABLE READ
 - 大多数场景：`READ COMMITTED`（平衡性能和一致性）
 - 报表/统计查询：`REPEATABLE READ`（保证读取一致性）
 - 金融交易：`SERIALIZABLE`（最强一致性，性能较低）
+
+### 3.12 后台任务事务隔离（重要）
+
+在 `@transactional` 装饰的 Service 方法中 spawn 后台任务时，**必须**使用 `@isolated_task` 或 `isolated_context`，否则事务不会提交。
+
+**问题背景**：
+`asyncio.create_task()` 会继承父协程的 `contextvars`。如果父协程在 `@transactional` 中，子任务会继承事务深度标记，导致：
+- `auto_commit` 失效
+- `transactional_context` 也不会提交
+- session 关闭时数据被 rollback
+
+**解决方案 1：装饰器（推荐）**
+
+```python
+import asyncio
+from aury.boot.domain.transaction import isolated_task, transactional_context
+from aury.boot.infrastructure.database import DatabaseManager
+
+db = DatabaseManager.get_instance()
+
+
+@isolated_task
+async def upload_cover(space_id: int, cover_url: str):
+    """后台任务：上传封面。"""
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            space = await repo.get(space_id)
+            if space:
+                await repo.update(space, {{"cover": cover_url}})
+        # 现在会正常 commit
+
+
+class SpaceService(BaseService):
+    @transactional
+    async def create(self, data: SpaceCreate) -> Space:
+        space = await self.repo.create(data.model_dump())
+        
+        # spawn 后台任务
+        asyncio.create_task(upload_cover(space.id, data.cover_url))
+        
+        return space
+```
+
+**解决方案 2：上下文管理器**
+
+```python
+from aury.boot.domain.transaction import isolated_context
+
+async def background_job():
+    async with isolated_context():
+        async with db.session() as session:
+            async with transactional_context(session):
+                # 正常的事务处理
+                ...
+```
+
+**注意事项**：
+- 后台任务必须新开 session（`db.session()`），不能复用主请求的 `self.session`
+- 后台任务的事务与主请求独立，主请求回滚不影响后台任务

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/domain/transaction/__init__.py

@@ -390,11 +390,68 @@ def requires_transaction(func: Callable) -> Callable:
     return wrapper
 
 
+def isolated_task[T](func: Callable[..., T]) -> Callable[..., T]:
+    """后台任务隔离装饰器。
+    
+    重置事务上下文，避免从父协程继承 _transaction_depth 导致 auto_commit 失效。
+    
+    问题背景：
+        asyncio.create_task() 会继承父协程的 contextvars。如果父协程在 @transactional 中，
+        _transaction_depth > 0，子任务的 auto_commit 和 transactional_context 都会认为
+        "在事务中" 而跳过 commit，导致 session 关闭时 rollback。
+    
+    用法：
+        @isolated_task
+        async def upload_cover(space_id: int, cover_url: str):
+            async with db.session() as session:
+                async with transactional_context(session):
+                    repo = SpaceRepository(session, Space)
+                    space = await repo.get(space_id)
+                    await repo.update(space, {"cover": cover_url})
+                # 现在会正常 commit
+        
+        # 在 Service 中 spawn
+        asyncio.create_task(upload_cover(space.id, url))
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        # 重置事务深度，让当前任务成为独立的事务上下文
+        token = _transaction_depth.set(0)
+        try:
+            return await func(*args, **kwargs)
+        finally:
+            _transaction_depth.reset(token)
+    
+    return wrapper
+
+
+@asynccontextmanager
+async def isolated_context() -> AsyncGenerator[None]:
+    """后台任务隔离上下文管理器。
+    
+    与 @isolated_task 作用相同，但用于上下文管理器形式。
+    
+    用法：
+        async def background_job():
+            async with isolated_context():
+                async with db.session() as session:
+                    async with transactional_context(session):
+                        ...
+    """
+    token = _transaction_depth.set(0)
+    try:
+        yield
+    finally:
+        _transaction_depth.reset(token)
+
+
 __all__ = [
     "TransactionManager",
     "TransactionRequiredError",
     "_transaction_depth",  # 内部使用，不对外文档化
     "ensure_transaction",
+    "isolated_context",
+    "isolated_task",
     "on_commit",
     "requires_transaction",
     "transactional",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.27
+Version: 0.0.29
 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.29.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=p4kcB0BmpcnphBIseH7188jNCCOqFZSly7Pka9LrUDM,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=SpqoXZXCyWmitBV6Mt0VvXWdPZAZXsLoU-vDEyJyQDc,8269
 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,8 +70,8 @@ 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/03-service.md.tpl,sha256=Dg_8RGSeRmmyQrhhpppEoxl-6C5pNe9M2OzVOl1kjSk,13102
+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=SgfPAgLVi_RbMjSAe-m49jQOIr6vfUT8VF2V1E-qa3w,15098
 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
 aury/boot/commands/templates/project/aury_docs/06-exception.md.tpl,sha256=Tv_Q5lsScHzvtcaFWmuQzN4YqvpcWZIdXS8jw99K29E,3340
@@ -124,13 +124,13 @@ 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
 aury/boot/domain/service/__init__.py,sha256=ZRotaBlqJXn7ebPTQjjoHtorpQREk8AgTD69UCcRd1k,118
 aury/boot/domain/service/base.py,sha256=6sN0nf8r5yUZsE6AcZOiOXFCqzb61oCxTfrWlqjIo9I,2035
-aury/boot/domain/transaction/__init__.py,sha256=Mk-J-5VOuuQ7NDW1DQmU-skCvcUOuEENfP_Ej3iZuJ8,13497
+aury/boot/domain/transaction/__init__.py,sha256=EKnjJ235SYjMCvGIuLVlTdYRzU35RxNMejRGUExYqqE,15488
 aury/boot/infrastructure/__init__.py,sha256=ppP1-suaDICMNvBSXj_4DVSH3h0D8e0qZhtENCr16m8,3007
 aury/boot/infrastructure/cache/__init__.py,sha256=G40uCkpJ1jSs2fc_CBDem73iQQzCcp-4GG1WpDJzwaA,658
 aury/boot/infrastructure/cache/backends.py,sha256=9QMQ8G9DtZgzVXZ_Ng7n1gXRu-_OQZgw4FHPOfr1qco,13585
@@ -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.29.dist-info/METADATA,sha256=EaL1z6pE7pRmQ6YSAytT91uPj34ejAyuzeTpWWpAI-g,7695
+aury_boot-0.0.29.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+aury_boot-0.0.29.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
+aury_boot-0.0.29.dist-info/RECORD,,