aury-boot 0.0.32__tar.gz → 0.0.34__tar.gz

{aury_boot-0.0.32 → aury_boot-0.0.34}/PKG-INFO

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

{aury_boot-0.0.32 → aury_boot-0.0.34}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.32'
-__version_tuple__ = version_tuple = (0, 0, 32)
+__version__ = version = '0.0.34'
+__version_tuple__ = version_tuple = (0, 0, 34)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.32 → aury_boot-0.0.34}/aury/boot/commands/templates/generate/repository.py.tpl

@@ -11,8 +11,9 @@ class {class_name}Repository(BaseRepository[{class_name}]):
     继承 BaseRepository 自动获得：
     - get(id): 按 ID 获取
     - get_by(**filters): 按条件获取单个
-    - list(skip, limit, **filters): 获取列表
-    - paginate(params, **filters): 分页获取
+    - list(skip, limit, sort, **filters): 获取列表
+    - paginate(pagination, sort, **filters): 分页获取
+    - stream(batch_size, sort, **filters): 流式查询
     - create(data): 创建
     - update(entity, data): 更新
     - delete(entity, soft=True): 删除

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

@@ -5,7 +5,7 @@
 **文件**: `{package_name}/repositories/user_repository.py`
 
 ```python
-"""User 数据访问层。"""
+"""“User 数据访问层。"""
 
 from aury.boot.domain.repository.impl import BaseRepository
 
@@ -18,13 +18,14 @@ class UserRepository(BaseRepository[User]):
     继承 BaseRepository 自动获得：
     - get(id): 按 ID 获取
     - get_by(**filters): 按条件获取单个
-    - list(skip, limit, **filters): 获取列表
-    - paginate(params, **filters): 分页获取
+    - list(skip, limit, sort, **filters): 获取列表
+    - paginate(pagination, sort, **filters): 分页获取
     - count(**filters): 计数
     - exists(**filters): 是否存在
     - create(data): 创建
     - update(entity, data): 更新
     - delete(entity, soft=True): 删除（默认软删除）
+    - stream(batch_size, sort, **filters): 流式查询
     - batch_create(data_list): 批量创建
     - bulk_insert(data_list): 高性能批量插入
     """
@@ -35,7 +36,7 @@ class UserRepository(BaseRepository[User]):
 
     async def list_active(self, skip: int = 0, limit: int = 100) -> list[User]:
         """获取激活用户列表。"""
-        return await self.list(skip=skip, limit=limit, is_active=True)
+        return await self.list(skip=skip, limit=limit, sort="-created_at", is_active=True)
 ```
 
 ## 2.2 BaseRepository 方法详解
@@ -50,25 +51,36 @@ repo = UserRepository(session, User)
 user = await repo.get(user_id)                    # 按 ID（支持 int/UUID）
 user = await repo.get_by(email="a@b.com")         # 按条件（简单 AND 过滤）
 users = await repo.list(skip=0, limit=10)         # 列表
+users = await repo.list(sort="-created_at")       # 带排序
 users = await repo.list(is_active=True)           # 带过滤
 count = await repo.count(is_active=True)          # 计数
 exists = await repo.exists(email="a@b.com")       # 是否存在
 
 # === 分页 ===
-from aury.boot.domain.pagination import PaginationParams, SortParams
+from aury.boot.domain.pagination import PaginationParams
 
+# 方式1: offset/limit（与 SQL 语义一致）
 result = await repo.paginate(
-    pagination_params=PaginationParams(page=1, page_size=20),
-    sort_params=SortParams.from_string("-created_at"),
+    pagination=PaginationParams(offset=0, limit=20),
+    sort="-created_at",
+    is_active=True,
+)
+
+# 方式2: page/size（UI 风格）
+result = await repo.paginate(
+    pagination=PaginationParams.of(page=1, size=20),
+    sort="-created_at",
     is_active=True,
 )
 
 # PaginationResult 结构：
 # - result.items: list[T]      # 数据列表
 # - result.total: int          # 总记录数
-# - result.page: int           # 当前页码
-# - result.page_size: int      # 每页数量
-# - result.total_pages: int    # 总页数
+# - result.offset: int         # 当前偏移量
+# - result.limit: int          # 每页数量
+# - result.page: int           # 当前页码（计算属性）
+# - result.size: int           # limit 别名
+# - result.total_pages: int    # 总页数（计算属性）
 # - result.has_next: bool      # 是否有下一页
 # - result.has_prev: bool      # 是否有上一页
 
@@ -96,11 +108,11 @@ result = await repo.cursor_paginate(
 
 # === 流式查询（大数据处理） ===
 # 逐条流式处理，不会一次性加载到内存
-async for user in repo.stream(batch_size=1000, is_active=True):
+async for user in repo.stream(batch_size=1000, sort="-created_at", is_active=True):
     await process(user)
 
 # 批量流式处理
-async for batch in repo.stream_batches(batch_size=1000):
+async for batch in repo.stream_batches(batch_size=1000, sort="id"):
     await bulk_sync_to_es(batch)
 
 # === 创建 ===
@@ -140,27 +152,28 @@ user = await repo.get_by(status__ne="archived")
 
 > 注意：filters 条件之间用 AND 组合；如需 AND/OR/NOT 的复杂组合，请使用 `QueryBuilder`（见 2.4）。
 
-### 2.2.2 排序参数（SortParams）
+### 2.2.2 排序参数（sort）
 
-`SortParams.from_string()` 支持两种语法：
+所有查询方法的 `sort` 参数支持多种格式：
 
 ```python
-from aury.boot.domain.pagination import SortParams
+# 字符串（推荐）
+await repo.list(sort="-created_at")                    # 简洁语法
+await repo.list(sort="-created_at,priority")           # 多字段
+await repo.list(sort="created_at:desc,priority:asc")  # 完整语法
 
-# 简洁语法："-" 前缀表示降序
-sort_params = SortParams.from_string("-created_at")
-sort_params = SortParams.from_string("-created_at,priority")  # 多字段
+# 字符串列表
+await repo.list(sort=["-created_at", "name"])
 
-# 完整语法：字段:方向
-sort_params = SortParams.from_string("created_at:desc,priority:asc")
+# SortParams 对象（需要白名单验证时）
+from aury.boot.domain.pagination import SortParams
 
-# 带字段白名单验证（防止 SQL 注入）
 ALLOWED_FIELDS = {{"id", "created_at", "priority", "status"}}
 sort_params = SortParams.from_string(
     "-created_at",
-    allowed_fields=ALLOWED_FIELDS
+    allowed_fields=ALLOWED_FIELDS  # 传入非法字段抛 ValueError
 )
-# 传入非法字段会抛出 ValueError
+await repo.list(sort=sort_params)
 ```
 
 ### 2.2.3 查询全部（limit=None）

{aury_boot-0.0.32 → aury_boot-0.0.34}/aury/boot/domain/pagination/__init__.py

@@ -14,61 +14,49 @@ from pydantic import BaseModel, Field, field_validator
 class PaginationParams(BaseModel):
     """分页参数。
     
-    定义分页查询的参数，包括页码和每页记录数。
-    """
-    
-    page: int = Field(default=1, ge=1, description="页码，从1开始")
-    page_size: int = Field(default=20, ge=1, le=100, description="每页记录数，最大100")
+    使用 offset/limit 模式，与 SQL 语义一致。
+    提供 `of()` 方法支持 page/size 风格的输入。
     
-    @property
-    def offset(self) -> int:
-        """计算偏移量。
+    示例:
+        # 方式1: offset/limit（底层/API风格）
+        params = PaginationParams(offset=20, limit=10)
         
-        Returns:
-            int: 偏移量
-        """
-        return (self.page - 1) * self.page_size
+        # 方式2: page/size（UI风格）
+        params = PaginationParams.of(page=3, size=10)
+    """
     
-    @property
-    def limit(self) -> int:
-        """获取限制数量。
-        
-        Returns:
-            int: 限制数量
-        """
-        return self.page_size
+    offset: int = Field(default=0, ge=0, description="偏移量")
+    limit: int = Field(default=20, ge=1, le=100, description="每页记录数，最大100")
     
-    @field_validator("page")
     @classmethod
-    def validate_page(cls, v: int) -> int:
-        """验证页码。
+    def of(cls, page: int = 1, size: int = 20) -> "PaginationParams":
+        """从 page/size 构造分页参数。
         
         Args:
-            v: 页码值
+            page: 页码，从 1 开始
+            size: 每页记录数
             
         Returns:
-            int: 验证后的页码
-        """
-        if v < 1:
-            raise ValueError("页码必须大于0")
-        return v
-    
-    @field_validator("page_size")
-    @classmethod
-    def validate_page_size(cls, v: int) -> int:
-        """验证每页记录数。
-        
-        Args:
-            v: 每页记录数
+            PaginationParams: 分页参数对象
             
-        Returns:
-            int: 验证后的每页记录数
+        Raises:
+            ValueError: 当 page < 1 或 size 无效时
         """
-        if v < 1:
-            raise ValueError("每页记录数必须大于0")
-        if v > 100:
-            raise ValueError("每页记录数不能超过100")
-        return v
+        if page < 1:
+            raise ValueError("页码必须大于 0")
+        return cls(offset=(page - 1) * size, limit=size)
+    
+    @property
+    def page(self) -> int:
+        """当前页码（从 1 开始）。"""
+        if self.limit == 0:
+            return 1
+        return self.offset // self.limit + 1
+    
+    @property
+    def size(self) -> int:
+        """每页记录数（limit 的别名）。"""
+        return self.limit
 
 
 class SortParams(BaseModel):
@@ -103,7 +91,7 @@ class SortParams(BaseModel):
         sort_str: str | None,
         *,
         allowed_fields: set[str] | None = None,
-        default_direction: str = "desc",
+        default_direction: str = "asc",
     ) -> SortParams:
         """从字符串解析排序参数。
         
@@ -124,7 +112,7 @@ class SortParams(BaseModel):
             
         示例:
             >>> SortParams.from_string("-created_at,priority")
-            SortParams(sorts=[('created_at', 'desc'), ('priority', 'desc')])
+            SortParams(sorts=[('created_at', 'desc'), ('priority', 'asc')])
             
             >>> SortParams.from_string("created_at:desc,priority:asc")
             SortParams(sorts=[('created_at', 'desc'), ('priority', 'asc')])
@@ -233,66 +221,76 @@ class PaginationResult[ModelType](BaseModel):
     """分页结果。
     
     封装分页查询的结果，包括数据列表和分页信息。
+    同时提供 offset/limit 和 page/size 两种风格的字段。
     """
     
     items: list[ModelType] = Field(description="数据列表")
     total: int = Field(ge=0, description="总记录数")
-    page: int = Field(ge=1, description="当前页码")
-    page_size: int = Field(ge=1, description="每页记录数")
-    total_pages: int = Field(ge=0, description="总页数")
+    offset: int = Field(ge=0, description="当前偏移量")
+    limit: int = Field(ge=1, description="每页记录数")
     has_next: bool = Field(description="是否有下一页")
     has_prev: bool = Field(description="是否有上一页")
     
+    @property
+    def page(self) -> int:
+        """当前页码（从 1 开始）。"""
+        if self.limit == 0:
+            return 1
+        return self.offset // self.limit + 1
+    
+    @property
+    def size(self) -> int:
+        """每页记录数（limit 的别名）。"""
+        return self.limit
+    
+    @property
+    def total_pages(self) -> int:
+        """总页数。"""
+        if self.limit == 0:
+            return 0
+        return (self.total + self.limit - 1) // self.limit
+    
     @classmethod
     def create(
         cls,
         items: list[ModelType],
         total: int,
-        pagination_params: PaginationParams
-    ) -> PaginationResult[ModelType]:
+        pagination: PaginationParams,
+    ) -> "PaginationResult[ModelType]":
         """创建分页结果。
         
         Args:
             items: 数据列表
             total: 总记录数
-            pagination_params: 分页参数
+            pagination: 分页参数
             
         Returns:
             PaginationResult[ModelType]: 分页结果
         """
-        total_pages = (total + pagination_params.page_size - 1) // pagination_params.page_size
-        has_next = pagination_params.page < total_pages
-        has_prev = pagination_params.page > 1
+        has_next = pagination.offset + pagination.limit < total
+        has_prev = pagination.offset > 0
         
         return cls(
             items=items,
             total=total,
-            page=pagination_params.page,
-            page_size=pagination_params.page_size,
-            total_pages=total_pages,
+            offset=pagination.offset,
+            limit=pagination.limit,
             has_next=has_next,
             has_prev=has_prev,
         )
     
     def get_next_params(self) -> PaginationParams | None:
-        """获取下一页的分页参数。
-        
-        Returns:
-            PaginationParams | None: 下一页的分页参数，如果没有下一页则返回None
-        """
+        """获取下一页的分页参数。"""
         if not self.has_next:
             return None
-        return PaginationParams(page=self.page + 1, page_size=self.page_size)
+        return PaginationParams(offset=self.offset + self.limit, limit=self.limit)
     
     def get_prev_params(self) -> PaginationParams | None:
-        """获取上一页的分页参数。
-        
-        Returns:
-            PaginationParams | None: 上一页的分页参数，如果没有上一页则返回None
-        """
+        """获取上一页的分页参数。"""
         if not self.has_prev:
             return None
-        return PaginationParams(page=self.page - 1, page_size=self.page_size)
+        new_offset = max(0, self.offset - self.limit)
+        return PaginationParams(offset=new_offset, limit=self.limit)
 
 
 class CursorPaginationParams(BaseModel):

{aury_boot-0.0.32 → aury_boot-0.0.34}/aury/boot/domain/repository/impl.py

@@ -224,45 +224,113 @@ class BaseRepository[ModelType: Base](IRepository[ModelType]):
         result = await self._session.execute(query)
         return result.scalar_one_or_none()
     
-    async def list(self, skip: int = 0, limit: int | None = 100, **filters) -> list[ModelType]:
+    async def list(
+        self,
+        skip: int = 0,
+        limit: int | None = None,
+        sort: str | SortParams | list[str] | None = None,
+        **filters
+    ) -> list[ModelType]:
+        """获取实体列表。
+        
+        Args:
+            skip: 跳过记录数
+            limit: 返回记录数限制，None 表示不限制（默认）
+            sort: 排序参数，支持多种格式：
+                - 字符串: "-created_at" 或 "created_at:desc" 或 "-created_at,name"
+                - SortParams 对象
+                - 字符串列表: ["-created_at", "name"]
+            **filters: 过滤条件
+            
+        Returns:
+            list[ModelType]: 实体列表
+        """
         query = self._build_base_query()
         query = self._apply_filters(query, **filters)
+        query = self._apply_sort(query, sort)
         query = query.offset(skip)
         if limit is not None:
             query = query.limit(limit)
         result = await self._session.execute(query)
         return list(result.scalars().all())
     
+    def _apply_sort(
+        self,
+        query: Select,
+        sort: str | SortParams | list[str] | None,
+    ) -> Select:
+        """应用排序参数到查询。
+        
+        Args:
+            query: SQLAlchemy 查询对象
+            sort: 排序参数，支持：
+                - 字符串: "-created_at" 或 "created_at:desc" 或 "-created_at,name"
+                - SortParams 对象
+                - 字符串列表: ["-created_at", "name"]
+                
+        Returns:
+            Select: 应用排序后的查询对象
+        """
+        if sort is None:
+            return query
+        
+        # 统一转换为 SortParams
+        sort_params: SortParams
+        if isinstance(sort, SortParams):
+            sort_params = sort
+        elif isinstance(sort, str):
+            sort_params = SortParams.from_string(sort)
+        elif isinstance(sort, list):
+            # 列表格式: ["-created_at", "name"]
+            sort_params = SortParams.from_string(",".join(sort))
+        else:
+            return query
+        
+        order_by_list = []
+        for field, direction in sort_params.sorts:
+            field_attr = getattr(self._model_class, field, None)
+            if field_attr is not None:
+                if direction == "desc":
+                    order_by_list.append(field_attr.desc())
+                else:
+                    order_by_list.append(field_attr)
+        
+        if order_by_list:
+            query = query.order_by(*order_by_list)
+        
+        return query
+    
     async def paginate(
         self,
-        pagination_params: PaginationParams,
-        sort_params: SortParams | None = None,
+        pagination: PaginationParams,
+        sort: str | SortParams | list[str] | None = None,
         **filters
     ) -> PaginationResult[ModelType]:
-        query = self._build_base_query()
-        query = self._apply_filters(query, **filters)
+        """分页查询（list 的语法糖）。
         
-        if sort_params:
-            order_by_list = []
-            for field, direction in sort_params.sorts:
-                field_attr = getattr(self._model_class, field, None)
-                if field_attr is not None:
-                    if direction == "desc":
-                        order_by_list.append(field_attr.desc())
-                    else:
-                        order_by_list.append(field_attr)
-            if order_by_list:
-                query = query.order_by(*order_by_list)
-        
-        query = query.offset(pagination_params.offset).limit(pagination_params.limit)
-        result = await self._session.execute(query)
-        items = list(result.scalars().all())
-        total_count = await self.count(**filters)
+        Args:
+            pagination: 分页参数
+            sort: 排序参数，支持多种格式：
+                - 字符串: "-created_at" 或 "created_at:desc" 或 "-created_at,name"
+                - SortParams 对象
+                - 字符串列表: ["-created_at", "name"]
+            **filters: 过滤条件
+            
+        Returns:
+            PaginationResult[ModelType]: 分页结果
+        """
+        items = await self.list(
+            skip=pagination.offset,
+            limit=pagination.limit,
+            sort=sort,
+            **filters
+        )
+        total = await self.count(**filters)
         
         return PaginationResult.create(
             items=items,
-            total=total_count,
-            pagination_params=pagination_params,
+            total=total,
+            pagination=pagination,
         )
     
     async def cursor_paginate(
@@ -374,6 +442,7 @@ class BaseRepository[ModelType: Base](IRepository[ModelType]):
     async def stream(
         self,
         batch_size: int = 1000,
+        sort: str | SortParams | list[str] | None = None,
         **filters
     ):
         """流式查询，使用数据库原生 server-side cursor。
@@ -382,17 +451,19 @@ class BaseRepository[ModelType: Base](IRepository[ModelType]):
         
         Args:
             batch_size: 每批次获取的记录数，默认 1000
+            sort: 排序参数（同 list）
             **filters: 过滤条件
             
         Yields:
             ModelType: 模型实例
             
         示例:
-            async for user in repo.stream(batch_size=500, status="active"):
+            async for user in repo.stream(batch_size=500, sort="-created_at", status="active"):
                 process(user)
         """
         query = self._build_base_query()
         query = self._apply_filters(query, **filters)
+        query = self._apply_sort(query, sort)
         
         async with self._session.stream_scalars(
             query.execution_options(yield_per=batch_size)
@@ -403,23 +474,26 @@ class BaseRepository[ModelType: Base](IRepository[ModelType]):
     async def stream_batches(
         self,
         batch_size: int = 1000,
+        sort: str | SortParams | list[str] | None = None,
         **filters
     ):
         """批量流式查询，每次返回一批数据。
         
         Args:
             batch_size: 每批次的记录数，默认 1000
+            sort: 排序参数（同 list）
             **filters: 过滤条件
             
         Yields:
             list[ModelType]: 一批模型实例
             
         示例:
-            async for batch in repo.stream_batches(batch_size=500):
+            async for batch in repo.stream_batches(batch_size=500, sort="id"):
                 bulk_process(batch)
         """
         query = self._build_base_query()
         query = self._apply_filters(query, **filters)
+        query = self._apply_sort(query, sort)
         
         async with self._session.stream_scalars(
             query.execution_options(yield_per=batch_size)
@@ -437,7 +511,10 @@ class BaseRepository[ModelType: Base](IRepository[ModelType]):
         return result.scalar_one()
     
     async def exists(self, **filters) -> bool:
-        return await self.count(**filters) > 0
+        """检查是否存在匹配的记录（比 count > 0 更高效）。"""
+        query = self._apply_filters(self._build_base_query(), **filters).limit(1)
+        result = await self._session.execute(query)
+        return result.scalar_one_or_none() is not None
     
     async def add(self, entity: ModelType) -> ModelType:
         self._session.add(entity)

{aury_boot-0.0.32 → aury_boot-0.0.34}/aury/boot/domain/repository/interface.py

@@ -35,22 +35,41 @@ class IRepository[ModelType: Base](ABC):
         pass
     
     @abstractmethod
-    async def list(self, skip: int = 0, limit: int | None = 100, **filters) -> list[ModelType]:
-        """获取实体列表。limit=None 时返回全部记录（谨慎使用）。"""
+    async def list(
+        self,
+        skip: int = 0,
+        limit: int | None = None,
+        sort: str | SortParams | list[str] | None = None,
+        **filters
+    ) -> list[ModelType]:
+        """获取实体列表。
+        
+        Args:
+            skip: 跳过记录数
+            limit: 返回记录数限制，None 表示不限制（默认）
+            sort: 排序参数，支持多种格式：
+                - 字符串: "-created_at" 或 "created_at:desc" 或 "-created_at,name"
+                - SortParams 对象
+                - 字符串列表: ["-created_at", "name"]
+            **filters: 过滤条件
+            
+        Returns:
+            list[ModelType]: 实体列表
+        """
         pass
     
     @abstractmethod
     async def paginate(
         self,
-        pagination_params: PaginationParams,
-        sort_params: SortParams | None = None,
+        pagination: PaginationParams,
+        sort: str | SortParams | list[str] | None = None,
         **filters
     ) -> PaginationResult[ModelType]:
-        """分页获取实体列表。
+        """分页查询（list 的语法糖）。
         
         Args:
-            pagination_params: 分页参数
-            sort_params: 排序参数
+            pagination: 分页参数
+            sort: 排序参数，支持多种格式（同 list）
             **filters: 过滤条件
             
         Returns:

{aury_boot-0.0.32 → aury_boot-0.0.34}/aury/boot/infrastructure/monitoring/alerting/__init__.py

@@ -27,7 +27,7 @@
 
 from .aggregator import AlertAggregator
 from .events import AlertEvent, AlertEventType, AlertNotification, AlertSeverity
-from .manager import AlertManager, emit_alert
+from .manager import AlertManager, emit_alert, emit_exception_alert
 from .notifiers import AlertNotifier, FeishuNotifier, WebhookNotifier
 from .rules import AlertRule, load_rules_from_dict
 
@@ -46,5 +46,6 @@ __all__ = [
     "WebhookNotifier",
     # 便捷函数
     "emit_alert",
+    "emit_exception_alert",
     "load_rules_from_dict",
 ]