aury-boot 0.0.19__tar.gz → 0.0.21__tar.gz

{aury_boot-0.0.19 → aury_boot-0.0.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.19
+Version: 0.0.21
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2
@@ -24,13 +24,11 @@ Requires-Dist: sqladmin>=0.16.0; extra == 'admin'
 Provides-Extra: all
 Requires-Dist: aiomysql>=0.3.2; extra == 'all'
 Requires-Dist: aiosqlite>=0.21.0; extra == 'all'
-Requires-Dist: amqp>=5.3.1; extra == 'all'
 Requires-Dist: apscheduler>=3.11.1; extra == 'all'
 Requires-Dist: asyncpg>=0.31.0; extra == 'all'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'all'
-Requires-Dist: dramatiq-kombu-broker>=0.2.2; extra == 'all'
 Requires-Dist: dramatiq>=1.18.0; extra == 'all'
-Requires-Dist: kombu>=5.6.1; extra == 'all'
+Requires-Dist: pika>=1.3.2; extra == 'all'
 Requires-Dist: redis>=7.1.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.19.0; extra == 'dev'
@@ -53,9 +51,7 @@ Requires-Dist: aiosqlite>=0.21.0; extra == 'recommended'
 Requires-Dist: apscheduler>=3.11.1; extra == 'recommended'
 Requires-Dist: asyncpg>=0.31.0; extra == 'recommended'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'recommended'
-Requires-Dist: dramatiq-kombu-broker>=0.2.2; extra == 'recommended'
 Requires-Dist: dramatiq>=1.18.0; extra == 'recommended'
-Requires-Dist: kombu>=5.6.1; extra == 'recommended'
 Requires-Dist: redis>=7.1.0; extra == 'recommended'
 Provides-Extra: redis
 Requires-Dist: redis>=7.1.0; extra == 'redis'
@@ -66,9 +62,8 @@ Requires-Dist: apscheduler>=3.11.1; extra == 'scheduler'
 Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.21.0; extra == 'sqlite'
 Provides-Extra: tasks
-Requires-Dist: dramatiq-kombu-broker>=0.2.2; extra == 'tasks'
 Requires-Dist: dramatiq>=1.18.0; extra == 'tasks'
-Requires-Dist: kombu>=5.6.1; extra == 'tasks'
+Requires-Dist: redis>=7.1.0; extra == 'tasks'
 Description-Content-Type: text/markdown
 
 # Aury Boot

{aury_boot-0.0.19 → aury_boot-0.0.21}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.19'
-__version_tuple__ = version_tuple = (0, 0, 19)
+__version__ = version = '0.0.21'
+__version_tuple__ = version_tuple = (0, 0, 21)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.19 → aury_boot-0.0.21}/aury/boot/application/app/base.py

@@ -11,8 +11,10 @@ from contextlib import asynccontextmanager
 import sys
 from typing import Any, ClassVar
 
-from fastapi import FastAPI, Request, status
+from fastapi import FastAPI, HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
 from starlette.middleware import Middleware as StarletteMiddleware
 
 from aury.boot.application.config import BaseConfig
@@ -279,8 +281,11 @@ class FoundationApp(FastAPI):
             **kwargs,
         )
 
-        # 异常处理
-        self.add_exception_handler(Exception, global_exception_handler)
+        # 异常处理：显式注册以覆盖 FastAPI/Starlette 默认处理器，确保统一响应格式
+        self.add_exception_handler(RequestValidationError, global_exception_handler)  # 422
+        self.add_exception_handler(HTTPException, global_exception_handler)  # 4xx/5xx
+        self.add_exception_handler(StarletteHTTPException, global_exception_handler)  # Starlette 异常
+        self.add_exception_handler(Exception, global_exception_handler)  # 其他未处理异常
 
         # 设置路由
         self.setup_routes()

{aury_boot-0.0.19 → aury_boot-0.0.21}/aury/boot/application/config/settings.py

@@ -507,10 +507,9 @@ class MessageQueueSettings(BaseModel):
     - Task: 基于 Dramatiq，用于异步任务处理（API + Worker 模式）
     - MQ: 通用消息队列，用于服务间通信、事件驱动架构
     
-    支持的后端（通过 Kombu）：
+    支持的后端：
     - Redis: redis://localhost:6379/0
     - RabbitMQ: amqp://guest:guest@localhost:5672//
-    - Amazon SQS: sqs://
     """
     
     enabled: bool = Field(

{aury_boot-0.0.19 → aury_boot-0.0.21}/aury/boot/application/errors/handlers.py

@@ -174,6 +174,7 @@ class ValidationErrorHandler(ErrorHandler):
     """验证异常处理器。
     
     处理 Pydantic ValidationError 和 FastAPI RequestValidationError。
+    返回 422 Unprocessable Entity（符合 FastAPI 规范）。
     """
     
     def can_handle(self, exception: Exception) -> bool:
@@ -182,24 +183,38 @@ class ValidationErrorHandler(ErrorHandler):
     
     async def handle(self, exception: Exception, request: Request) -> JSONResponse:
         """处理验证异常。"""
-        logger.warning(f"数据验证失败: {exception}")
-        
         errors = []
         for error in exception.errors():
+            # 构建友好的字段路径：跳过 body 前缀
+            loc = error.get("loc", ())
+            # FastAPI 会在 loc 前加 'body'/'query'/'path' 等，保留第一个作为来源
+            source = str(loc[0]) if loc else ""
+            field_path = ".".join(str(part) for part in loc[1:]) if len(loc) > 1 else str(loc[0]) if loc else ""
+            
             errors.append({
-                "field": ".".join(str(loc) for loc in error["loc"]),
-                "message": error["msg"],
-                "type": error["type"],
+                "field": field_path,
+                "source": source,  # body / query / path / header
+                "message": error.get("msg", ""),
+                "type": error.get("type", ""),
+                "input": error.get("input"),  # 实际输入值（便于调试）
             })
         
+        # 详细日志：方便开发调试
+        error_summary = "; ".join(
+            f"{e['source']}.{e['field']}({e['type']}): {e['message']}" for e in errors
+        )
+        logger.warning(
+            f"参数校验失败 [{request.method} {request.url.path}]: {error_summary}"
+        )
+        
         response = ResponseBuilder.fail(
-            message="数据验证失败",
-            code=400,
+            message="参数校验失败",
+            code=422,
             errors=errors,
         )
         
         return JSONResponse(
-            status_code=status.HTTP_400_BAD_REQUEST,
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
             content=response.model_dump(mode="json"),
         )
 

{aury_boot-0.0.19 → aury_boot-0.0.21}/aury/boot/commands/pkg.py

@@ -97,16 +97,16 @@ MODULES: dict[str, ModuleInfo] = {
     "tasks": ModuleInfo(
         name="tasks",
         desc="Dramatiq 任务队列",
-        usage="TaskManager 异步任务时需要",
+        usage="TaskManager 异步任务时需要（默认使用 Redis Broker）",
         category=Category.TASK,
-        deps=["dramatiq", "kombu", "dramatiq-kombu-broker"],
+        deps=["dramatiq", "redis"],
     ),
     "rabbitmq": ModuleInfo(
         name="rabbitmq",
         desc="RabbitMQ 消息队列后端",
         usage="TaskManager/EventBus 使用 RabbitMQ 时需要（需配合 tasks）",
         category=Category.TASK,
-        deps=["amqp"],
+        deps=["pika"],
     ),
     # 调度器
     "scheduler": ModuleInfo(

{aury_boot-0.0.19 → aury_boot-0.0.21}/aury/boot/commands/templates/project/aury_docs/08-scheduler.md.tpl

@@ -1,6 +1,6 @@
 # 定时任务（Scheduler）
 
-基于 APScheduler，完全透传原生 API。
+基于 APScheduler，支持两种触发器语法：字符串模式和原生对象模式。
 
 ## 基本用法
 
@@ -9,31 +9,38 @@
 ```python
 """定时任务模块。"""
 
-from apscheduler.triggers.cron import CronTrigger
-from apscheduler.triggers.interval import IntervalTrigger
-
 from aury.boot.common.logging import logger
 from aury.boot.infrastructure.scheduler import SchedulerManager
 
 scheduler = SchedulerManager.get_instance()
 
 
-@scheduler.scheduled_job(IntervalTrigger(seconds=60))
+# === 字符串模式（推荐，简洁）===
+@scheduler.scheduled_job("interval", seconds=60)
 async def every_minute():
     """每 60 秒执行。"""
     logger.info("定时任务执行中...")
 
 
-@scheduler.scheduled_job(CronTrigger(hour=0, minute=0))
+@scheduler.scheduled_job("cron", hour=0, minute=0)
 async def daily_task():
     """每天凌晨执行。"""
     logger.info("每日任务执行中...")
 
 
-@scheduler.scheduled_job(CronTrigger(day_of_week="mon", hour=9))
+@scheduler.scheduled_job("cron", day_of_week="mon", hour=9)
 async def weekly_report():
     """每周一 9 点执行。"""
     logger.info("周报任务执行中...")
+
+
+# === 原生对象模式（完整功能）===
+from apscheduler.triggers.cron import CronTrigger
+
+@scheduler.scheduled_job(CronTrigger.from_crontab("0 2 * * *"))
+async def crontab_task():
+    """每天凌晨 2 点执行（使用 crontab 表达式）。"""
+    logger.info("每日任务执行中...")
 ```
 
 启用方式：配置 `SCHEDULER__ENABLED=true`，框架自动加载 `{package_name}/schedules/` 模块。
@@ -50,40 +57,57 @@ SCHEDULER__MISFIRE_GRACE_TIME=60                 # 错过容忍时间(秒)
 SCHEDULER__JOBSTORE_URL=redis://localhost:6379/0 # 分布式存储（可选）
 ```
 
-## 触发器类型
+## 触发器语法
 
-### CronTrigger - 定时触发
+支持两种语法：
 
-```python
-from apscheduler.triggers.cron import CronTrigger
+| 语法 | 适用场景 | 示例 |
+|------|---------|------|
+| 字符串模式 | 日常使用，简洁 | `"cron", hour="*", minute=0` |
+| 原生对象 | crontab 表达式、复杂配置 | `CronTrigger.from_crontab("0 * * * *")` |
 
+### cron - 定时触发
+
+```python
+# === 字符串模式 ===
 # 每天凌晨 2:30
-CronTrigger(hour=2, minute=30)
+@scheduler.scheduled_job("cron", hour=2, minute=30)
 
 # 每小时整点
-CronTrigger(hour="*", minute=0)
+@scheduler.scheduled_job("cron", hour="*", minute=0)
 
 # 工作日 9:00
-CronTrigger(day_of_week="mon-fri", hour=9)
+@scheduler.scheduled_job("cron", day_of_week="mon-fri", hour=9)
 
 # 每月 1 号
-CronTrigger(day=1, hour=0)
+@scheduler.scheduled_job("cron", day=1, hour=0)
+
+# === 原生对象模式 ===
+from apscheduler.triggers.cron import CronTrigger
 
 # 使用 crontab 表达式
-CronTrigger.from_crontab("0 2 * * *")  # 每天 2:00
+@scheduler.scheduled_job(CronTrigger.from_crontab("0 2 * * *"))  # 每天 2:00
 ```
 
-### IntervalTrigger - 间隔触发
+**cron 参数**：`year`, `month`, `day`, `week`, `day_of_week`, `hour`, `minute`, `second`, `start_date`, `end_date`, `timezone`, `jitter`
+
+### interval - 间隔触发
 
 ```python
+# === 字符串模式 ===
+@scheduler.scheduled_job("interval", seconds=30)   # 每 30 秒
+@scheduler.scheduled_job("interval", minutes=5)    # 每 5 分钟
+@scheduler.scheduled_job("interval", hours=1)      # 每小时
+@scheduler.scheduled_job("interval", days=1)       # 每天
+
+# === 原生对象模式 ===
 from apscheduler.triggers.interval import IntervalTrigger
 
-IntervalTrigger(seconds=30)   # 每 30 秒
-IntervalTrigger(minutes=5)    # 每 5 分钟
-IntervalTrigger(hours=1)      # 每小时
-IntervalTrigger(days=1)       # 每天
+@scheduler.scheduled_job(IntervalTrigger(hours=1, jitter=60))  # 每小时，随机抖动 60 秒
 ```
 
+**interval 参数**：`weeks`, `days`, `hours`, `minutes`, `seconds`, `start_date`, `end_date`, `timezone`, `jitter`
+
 ### DateTrigger - 一次性触发
 
 ```python
@@ -91,9 +115,31 @@ from apscheduler.triggers.date import DateTrigger
 from datetime import datetime, timedelta
 
 # 10 秒后执行
-DateTrigger(run_date=datetime.now() + timedelta(seconds=10))
+scheduler.add_job(my_task, DateTrigger(run_date=datetime.now() + timedelta(seconds=10)))
 ```
 
+## 条件加载
+
+通过 `enabled` 参数控制任务是否注册：
+
+```python
+from config import settings
+
+# 根据配置开关决定是否启用
+@scheduler.scheduled_job("cron", hour=2, enabled=settings.ENABLE_REPORT)
+async def daily_report():
+    """仅在 ENABLE_REPORT=true 时注册。"""
+    ...
+
+# 区分环境
+@scheduler.scheduled_job("interval", minutes=5, enabled=settings.ENV == "production")
+async def prod_only_task():
+    """仅生产环境执行。"""
+    ...
+```
+
+`enabled=False` 时任务不会注册，日志记录：`任务已禁用，跳过注册: xxx`
+
 ## 多实例支持
 
 支持不同业务线使用独立的调度器实例：
@@ -136,7 +182,11 @@ scheduler = SchedulerManager.get_instance(
 ## 任务管理
 
 ```python
-# 添加任务
+# 添加任务（字符串模式）
+scheduler.add_job(my_task, "cron", hour=2, minute=0, id="my_task")
+
+# 添加任务（原生对象模式）
+from apscheduler.triggers.cron import CronTrigger
 scheduler.add_job(my_task, CronTrigger(hour=2), id="my_task")
 
 # 获取任务
@@ -150,7 +200,10 @@ scheduler.resume_job("my_task")
 # 移除
 scheduler.remove_job("my_task")
 
-# 重新调度
+# 重新调度（字符串模式）
+scheduler.reschedule_job("my_task", "cron", hour=3)
+
+# 重新调度（原生对象模式）
 scheduler.reschedule_job("my_task", CronTrigger(hour=3))
 ```
 

aury_boot-0.0.21/aury/boot/commands/templates/project/modules/schedules.py.tpl

@@ -0,0 +1,38 @@
+"""定时任务模块（Scheduler）。
+
+在此文件中定义定时任务，使用 @scheduler.scheduled_job() 装饰器。
+
+框架会自动发现并加载本模块，无需在 main.py 中手动导入。
+也可通过 SCHEDULER_SCHEDULE_MODULES 环境变量指定自定义模块。
+
+触发器支持两种语法：
+- 字符串模式（推荐）：@scheduler.scheduled_job("cron", hour="*", minute=0)
+- 原生对象模式：@scheduler.scheduled_job(CronTrigger(hour="*"))
+"""
+
+# from aury.boot.common.logging import logger
+# from aury.boot.infrastructure.scheduler import SchedulerManager
+#
+# scheduler = SchedulerManager.get_instance()
+#
+#
+# # === 字符串模式（推荐，简洁）===
+# @scheduler.scheduled_job("interval", seconds=60)
+# async def example_job():
+#     """示例定时任务，每 60 秒执行一次。"""
+#     logger.info("定时任务执行中...")
+#
+#
+# @scheduler.scheduled_job("cron", hour="*", minute=0)
+# async def hourly_job():
+#     """每小时整点执行。"""
+#     logger.info("整点任务执行")
+#
+#
+# # === 原生对象模式（完整功能）===
+# # from apscheduler.triggers.cron import CronTrigger
+# #
+# # @scheduler.scheduled_job(CronTrigger.from_crontab("0 2 * * *"))
+# # async def daily_job():
+# #     """每天凌晨 2 点执行（使用 crontab 表达式）。"""
+# #     logger.info("每日任务执行")