aury-boot 0.0.15__tar.gz → 0.0.17__tar.gz

{aury_boot-0.0.15 → aury_boot-0.0.17}/PKG-INFO

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

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.15'
-__version_tuple__ = version_tuple = (0, 0, 15)
+__version__ = version = '0.0.17'
+__version_tuple__ = version_tuple = (0, 0, 17)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/application/app/components.py

@@ -281,18 +281,65 @@ class SchedulerComponent(Component):
             except Exception as e:
                 logger.warning(f"加载定时任务模块失败 ({module_name}): {e}")
 
+    def _build_scheduler_config(self, config: BaseConfig) -> dict:
+        """根据配置构建 APScheduler 初始化参数。"""
+        scheduler_kwargs: dict = {}
+        scheduler_config = config.scheduler
+        
+        # jobstores: 根据 URL 自动选择存储后端
+        if scheduler_config.jobstore_url:
+            url = scheduler_config.jobstore_url
+            if url.startswith("redis://"):
+                try:
+                    from apscheduler.jobstores.redis import RedisJobStore
+                    scheduler_kwargs["jobstores"] = {
+                        "default": RedisJobStore.from_url(url)
+                    }
+                    logger.info(f"调度器使用 Redis 存储: {url.split('@')[-1]}")
+                except ImportError:
+                    logger.warning("Redis jobstore 需要安装 redis: pip install redis")
+            else:
+                # SQLAlchemy 存储 (sqlite/postgresql/mysql)
+                try:
+                    from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore
+                    scheduler_kwargs["jobstores"] = {
+                        "default": SQLAlchemyJobStore(url=url)
+                    }
+                    logger.info("调度器使用 SQLAlchemy 存储")
+                except ImportError:
+                    logger.warning("SQLAlchemy jobstore 需要安装 sqlalchemy")
+        
+        # timezone
+        if scheduler_config.timezone:
+            scheduler_kwargs["timezone"] = scheduler_config.timezone
+        
+        # job_defaults
+        scheduler_kwargs["job_defaults"] = {
+            "coalesce": scheduler_config.coalesce,
+            "max_instances": scheduler_config.max_instances,
+            "misfire_grace_time": scheduler_config.misfire_grace_time,
+        }
+        
+        return scheduler_kwargs
+    
     async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
         """启动调度器。
         
-        1. 自动发现并加载定时任务模块
-        2. 启动调度器（注册装饰器收集的任务）
+        1. 根据配置初始化调度器（jobstore/timezone/job_defaults）
+        2. 自动发现并加载定时任务模块
+        3. 启动调度器（注册装饰器收集的任务）
         """
         try:
+            # 构建配置
+            scheduler_kwargs = self._build_scheduler_config(config)
+            
+            # 获取/创建调度器实例
+            scheduler = SchedulerManager.get_instance("default", **scheduler_kwargs)
+            
             # 自动发现并加载定时任务模块
             self._autodiscover_schedules(app, config)
             
             # 启动调度器
-            scheduler = SchedulerManager.get_instance()
             scheduler.start()
         except Exception as e:
             logger.warning(f"调度器启动失败（非关键）: {e}")

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/application/app/startup.py

@@ -152,7 +152,7 @@ def collect_component_status() -> list[ComponentStatus]:
                     name="Cache" if name == "default" else f"Cache [{name}]",
                     status="ok",
                     backend=instance.backend_type,
-                    url=instance._config.get("CACHE_URL") if instance._config else None,
+                    url=(instance._config or {}).get("CACHE_URL"),
                 )
             )
 

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/application/config/settings.py

@@ -416,6 +416,10 @@ class SchedulerSettings(BaseModel):
     - SCHEDULER__ENABLED=false: 只运行 API，不启动调度器
     
     独立调度器通过 `aury scheduler` 命令运行，不需要此配置。
+    
+    分布式调度：
+    - 配置 SCHEDULER__JOBSTORE_URL 使用 Redis/SQLAlchemy 存储
+    - 多节点部署时共享任务状态
     """
     
     enabled: bool = Field(
@@ -426,6 +430,33 @@ class SchedulerSettings(BaseModel):
         default_factory=list,
         description="定时任务模块列表。为空时自动发现 schedules 模块"
     )
+    # APScheduler 配置
+    jobstore_url: str | None = Field(
+        default=None,
+        description=(
+            "任务存储 URL。支持：\n"
+            "- redis://localhost:6379/0（Redis 存储）\n"
+            "- sqlite:///jobs.db（SQLite 存储）\n"
+            "- postgresql://user:pass@host/db（PostgreSQL 存储）\n"
+            "- 不配置则使用内存存储"
+        )
+    )
+    timezone: str | None = Field(
+        default=None,
+        description="调度器时区，如 Asia/Shanghai、UTC"
+    )
+    coalesce: bool = Field(
+        default=True,
+        description="是否合并错过的任务执行（多次错过只执行一次）"
+    )
+    max_instances: int = Field(
+        default=1,
+        description="同一任务的最大并发实例数"
+    )
+    misfire_grace_time: int = Field(
+        default=60,
+        description="任务错过容忍时间（秒），超过此时间则跳过"
+    )
 
 
 class TaskSettings(BaseModel):

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -122,6 +122,8 @@ mypy {package_name}/
 
 ## 代码规范
 
+> 项目所有业务配置请通过应用 `settings`/配置对象获取，**不要**直接使用 `os.environ` 在业务代码中读环境变量。
+
 ### Model 规范
 
 - **必须**继承框架预定义基类，**不要**直接继承 `Base`
@@ -129,6 +131,16 @@ mypy {package_name}/
 - 软删除模型**必须**使用复合唯一约束（包含 `deleted_at`），不能单独使用 `unique=True`
 - **不建议**使用数据库外键（`ForeignKey`），通过程序控制关系，便于分库分表和微服务拆分
 
+**重要：软删除机制**
+
+框架采用「默认 0」策略，而非 IS NULL：
+- `deleted_at = 0`：未删除
+- `deleted_at > 0`：已删除（Unix 时间戳）
+
+查询未删除记录时，使用 `WHERE deleted_at = 0`，不是 `WHERE deleted_at IS NULL`。
+
+BaseRepository 已自动处理软删除过滤，无需手动添加条件。
+
 ```python
 # ✅ 正确
 from aury.boot.domain.models import AuditableStateModel

aury_boot-0.0.17/aury/boot/commands/templates/project/aury_docs/08-scheduler.md.tpl

@@ -0,0 +1,178 @@
+# 定时任务（Scheduler）
+
+基于 APScheduler，完全透传原生 API。
+
+## 基本用法
+
+**文件**: `{package_name}/schedules/__init__.py`
+
+```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))
+async def every_minute():
+    """每 60 秒执行。"""
+    logger.info("定时任务执行中...")
+
+
+@scheduler.scheduled_job(CronTrigger(hour=0, minute=0))
+async def daily_task():
+    """每天凌晨执行。"""
+    logger.info("每日任务执行中...")
+
+
+@scheduler.scheduled_job(CronTrigger(day_of_week="mon", hour=9))
+async def weekly_report():
+    """每周一 9 点执行。"""
+    logger.info("周报任务执行中...")
+```
+
+启用方式：配置 `SCHEDULER__ENABLED=true`，框架自动加载 `{package_name}/schedules/` 模块。
+
+## 配置项
+
+```bash
+# .env
+SCHEDULER__ENABLED=true                          # 是否启用
+SCHEDULER__TIMEZONE=Asia/Shanghai                # 时区
+SCHEDULER__COALESCE=true                         # 合并错过的任务
+SCHEDULER__MAX_INSTANCES=1                       # 同一任务最大并发数
+SCHEDULER__MISFIRE_GRACE_TIME=60                 # 错过容忍时间(秒)
+SCHEDULER__JOBSTORE_URL=redis://localhost:6379/0 # 分布式存储（可选）
+```
+
+## 触发器类型
+
+### CronTrigger - 定时触发
+
+```python
+from apscheduler.triggers.cron import CronTrigger
+
+# 每天凌晨 2:30
+CronTrigger(hour=2, minute=30)
+
+# 每小时整点
+CronTrigger(hour="*", minute=0)
+
+# 工作日 9:00
+CronTrigger(day_of_week="mon-fri", hour=9)
+
+# 每月 1 号
+CronTrigger(day=1, hour=0)
+
+# 使用 crontab 表达式
+CronTrigger.from_crontab("0 2 * * *")  # 每天 2:00
+```
+
+### IntervalTrigger - 间隔触发
+
+```python
+from apscheduler.triggers.interval import IntervalTrigger
+
+IntervalTrigger(seconds=30)   # 每 30 秒
+IntervalTrigger(minutes=5)    # 每 5 分钟
+IntervalTrigger(hours=1)      # 每小时
+IntervalTrigger(days=1)       # 每天
+```
+
+### DateTrigger - 一次性触发
+
+```python
+from apscheduler.triggers.date import DateTrigger
+from datetime import datetime, timedelta
+
+# 10 秒后执行
+DateTrigger(run_date=datetime.now() + timedelta(seconds=10))
+```
+
+## 多实例支持
+
+支持不同业务线使用独立的调度器实例：
+
+```python
+# 默认实例
+scheduler = SchedulerManager.get_instance()
+
+# 命名实例
+report_scheduler = SchedulerManager.get_instance("report")
+cleanup_scheduler = SchedulerManager.get_instance("cleanup")
+```
+
+## 分布式调度
+
+多节点部署时，配置相同的 `SCHEDULER__JOBSTORE_URL`，所有节点共享任务状态：
+
+```bash
+# 所有节点使用相同配置
+SCHEDULER__JOBSTORE_URL=redis://redis:6379/0
+```
+
+APScheduler 自动协调防止重复执行。
+
+### 代码方式配置（高级）
+
+```python
+from apscheduler.jobstores.redis import RedisJobStore
+from apscheduler.executors.asyncio import AsyncIOExecutor
+
+scheduler = SchedulerManager.get_instance(
+    "distributed",
+    jobstores={"default": RedisJobStore(host="localhost", port=6379)},
+    executors={"default": AsyncIOExecutor()},
+    job_defaults={"coalesce": True, "max_instances": 1},
+    timezone="Asia/Shanghai",
+)
+```
+
+## 任务管理
+
+```python
+# 添加任务
+scheduler.add_job(my_task, CronTrigger(hour=2), id="my_task")
+
+# 获取任务
+job = scheduler.get_job("my_task")
+jobs = scheduler.get_jobs()
+
+# 暂停/恢复
+scheduler.pause_job("my_task")
+scheduler.resume_job("my_task")
+
+# 移除
+scheduler.remove_job("my_task")
+
+# 重新调度
+scheduler.reschedule_job("my_task", CronTrigger(hour=3))
+```
+
+## 监听器（高级）
+
+通过底层 APScheduler 实例访问：
+
+```python
+from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR
+
+def job_listener(event):
+    if event.exception:
+        logger.error(f"任务失败: {event.job_id}")
+    else:
+        logger.info(f"任务完成: {event.job_id}")
+
+scheduler.scheduler.add_listener(job_listener, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR)
+```
+
+## 实践建议
+
+1. **使用明确的 ID**：便于管理和调试
+2. **合理设置间隔**：避免太频繁的任务
+3. **异常处理**：在任务函数内捕获异常，避免影响调度器
+4. **超时保护**：长运行任务使用 `asyncio.wait_for`

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/commands/templates/project/aury_docs/99-cli.md.tpl

@@ -153,7 +153,7 @@ register_commands(app)
 @app.command()
 async def hello(name: str = "world") -> None:
     """示例：项目自定义命令。"""
-    print(f"Hello, {name} from {project_name_snake}!")
+    print(f"Hello, {{name}} from {project_name_snake}!")
 ```
 
 > 注意：这里的 `app` 是 Typer 应用实例，`register_commands` 会把所有内置的 `init/generate/server/...` 等命令挂到你自己的 CLI 下。

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/commands/templates/project/modules/schedules.py.tpl

@@ -6,13 +6,16 @@
 也可通过 SCHEDULER_SCHEDULE_MODULES 环境变量指定自定义模块。
 """
 
+# 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("interval", seconds=60)
+# @scheduler.scheduled_job(IntervalTrigger(seconds=60))
 # async def example_job():
 #     """示例定时任务，每 60 秒执行一次。"""
 #     logger.info("定时任务执行中...")

{aury_boot-0.0.15 → aury_boot-0.0.17}/aury/boot/infrastructure/cache/manager.py

@@ -110,13 +110,15 @@ class CacheManager:
                 supported = ", ".join(b.value for b in CacheBackend)
                 raise ValueError(f"不支持的缓存后端: {backend}。支持: {supported}")
         
-        # 保存配置
+        # 保存配置（用于启动横幅等场景展示）
         self._config = {"CACHE_TYPE": backend.value}
         
         # 根据后端类型构建配置并创建后端
         if backend == CacheBackend.REDIS:
             if not url:
                 raise ValueError("Redis 缓存需要提供 url 参数")
+            # 记录 URL 以便在启动横幅中展示（会通过 mask_url 脱敏）
+            self._config["CACHE_URL"] = url
             self._backend = await CacheFactory.create(
                 "redis", url=url, serializer=serializer
             )
@@ -128,6 +130,8 @@ class CacheManager:
             cache_url = url or (servers[0] if servers else None)
             if not cache_url:
                 raise ValueError("Memcached 缓存需要提供 url 参数")
+            # 同样记录 URL，便于在启动横幅中展示
+            self._config["CACHE_URL"] = cache_url
             self._backend = await CacheFactory.create(
                 "memcached", servers=cache_url
             )