aury-boot 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

aury/boot/commands/templates/project/README.md.tpl

@@ -0,0 +1,111 @@
+# {project_name}
+
+基于 [Aury Boot](https://github.com/AuriMyth/aury-boot) 构建的 API 服务。
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+uv sync
+```
+
+### 配置环境变量
+
+```bash
+cp .env.example .env
+# 编辑 .env 文件
+```
+
+### 启动开发服务器
+
+```bash
+aury server dev
+```
+
+### 管理后台（可选）
+
+默认提供 SQLAdmin 管理后台扩展（默认路径：`/api/admin-console`），适合快速搭建项目的后台管理能力。
+
+1) 安装扩展依赖：
+
+```bash
+uv add "aury-boot[admin]"
+```
+
+2) 在 `.env` 中启用并配置认证（至少 basic 或 bearer 之一）：
+
+```bash
+ADMIN_ENABLED=true
+ADMIN_PATH=/api/admin-console
+ADMIN_AUTH_MODE=basic
+ADMIN_AUTH_SECRET_KEY=CHANGE_ME_TO_A_RANDOM_SECRET
+ADMIN_AUTH_BASIC_USERNAME=admin
+ADMIN_AUTH_BASIC_PASSWORD=change_me
+```
+
+3) 启动后访问：
+
+- `http://127.0.0.1:8000/api/admin-console`
+
+### 生成代码
+
+```bash
+# 生成完整 CRUD（交互式，推荐）
+aury generate crud user -i
+
+# 单独生成（添加 -i 参数可交互式配置）
+aury generate model user -i     # SQLAlchemy 模型
+aury generate repo user        # Repository
+aury generate service user     # Service
+aury generate api user         # API 路由
+aury generate schema user      # Pydantic Schema
+```
+
+### 数据库迁移
+
+```bash
+# 生成迁移
+aury migrate make -m "add user table"
+
+# 执行迁移
+aury migrate up
+
+# 查看状态
+aury migrate status
+```
+
+### 调度器和 Worker
+
+```bash
+# 独立运行调度器
+aury scheduler
+
+# 运行任务队列 Worker
+aury worker
+```
+
+## 项目结构
+
+```
+{project_name}/
+├── main.py              # 应用入口
+├── app/                 # 代码包（默认 app，可通过 aury init <pkg> 自定义）
+│   ├── config.py        # 配置定义
+│   ├── api/             # API 路由
+│   ├── services/        # 业务逻辑
+│   ├── models/          # SQLAlchemy 模型
+│   ├── repositories/    # 数据访问层
+│   ├── schemas/         # Pydantic 模型
+│   ├── exceptions/      # 自定义异常
+│   ├── schedules/       # 定时任务
+│   └── tasks/           # 异步任务
+├── migrations/          # 数据库迁移
+└── tests/               # 测试
+```
+
+## 文档
+
+- [DEVELOPMENT.md](./DEVELOPMENT.md) - 开发指南（代码组织与规范）
+- [CLI.md](./CLI.md) - CLI 命令参考
+- [Aury Boot 文档](https://github.com/AuriMyth/aury-boot)

aury/boot/commands/templates/project/admin_console_init.py.tpl

@@ -0,0 +1,50 @@
+"""管理后台（Admin Console）项目侧扩展点。
+
+说明：
+- 框架会在启用 ADMIN_ENABLED=true 时自动尝试加载本模块，并调用 register_admin(admin)
+- 用于注册 SQLAdmin 的 ModelView（展示/编辑你的业务模型）
+- 认证默认推荐使用环境变量（basic/bearer）；如需深度自定义，可在本模块实现 register_admin_auth(config)
+  （注意：一旦定义 register_admin_auth，会覆盖内置认证逻辑）
+"""
+
+from __future__ import annotations
+
+
+def register_admin(admin) -> None:
+    """注册 SQLAdmin Views。
+
+    你可以在这里添加你的 ModelView：
+
+    ```python
+    from sqladmin import ModelView
+    from {import_prefix}models.user import User
+
+    class UserAdmin(ModelView, model=User):
+        column_list = [User.id, User.email]
+
+    admin.add_view(UserAdmin)
+    ```
+    """
+    # 默认不注册任何 view，避免生成项目缺少模型时报错
+    return
+
+
+# 如需自定义认证（覆盖 basic/bearer），取消注释并实现：
+#
+# def register_admin_auth(config):
+#     from sqladmin.authentication import AuthenticationBackend
+#     from starlette.requests import Request
+#
+#     class MyAuth(AuthenticationBackend):
+#         async def login(self, request: Request) -> bool:
+#             return False
+#
+#         async def logout(self, request: Request) -> bool:
+#             return True
+#
+#         async def authenticate(self, request: Request) -> bool:
+#             return False
+#
+#     return MyAuth(secret_key=config.admin.auth.secret_key)
+
+

aury/boot/commands/templates/project/config.py.tpl

@@ -0,0 +1,30 @@
+"""应用配置。
+
+配置优先级：命令行参数 > 环境变量 > .env 文件 > 默认值
+
+环境变量示例：
+    DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb
+    CACHE_TYPE=redis
+    CACHE_REDIS_URL=redis://localhost:6379/0
+    LOG_LEVEL=INFO
+"""
+
+from aury.boot.application.config import BaseConfig
+
+
+class AppConfig(BaseConfig):
+    """{project_name} 配置。
+    
+    继承 BaseConfig 获得所有默认配置项：
+    - server: 服务器配置
+    - database: 数据库配置
+    - cache: 缓存配置
+    - log: 日志配置
+    - migration: 迁移配置
+    
+    可以在这里添加自定义配置项。
+    """
+    
+    # 添加自定义配置项
+    # my_setting: str = Field(default="value", description="自定义配置")
+    pass

aury/boot/commands/templates/project/conftest.py.tpl

@@ -0,0 +1,26 @@
+"""Pytest 配置和 fixtures。"""
+
+import asyncio
+from collections.abc import AsyncGenerator, Generator
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from aury.boot.infrastructure.database import DatabaseManager
+
+
+@pytest.fixture(scope="session")
+def event_loop() -> Generator[asyncio.AbstractEventLoop, None, None]:
+    """创建事件循环。"""
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+
+@pytest.fixture
+async def db_session() -> AsyncGenerator[AsyncSession, None]:
+    """获取数据库会话。"""
+    db_manager = DatabaseManager.get_instance()
+    async with db_manager.session() as session:
+        yield session
+        await session.rollback()

aury/boot/commands/templates/project/env.example.tpl

@@ -0,0 +1,213 @@
+# =============================================================================
+# {project_name} 环境变量配置
+# =============================================================================
+# 复制此文件为 .env 并根据实际情况修改
+# 所有配置项均有默认值，只需取消注释并修改需要覆盖的项
+
+# =============================================================================
+# 服务配置 (SERVICE_)
+# =============================================================================
+# 服务名称，用于日志目录区分
+SERVICE_NAME={project_name_snake}
+# 服务类型: api / worker
+# SERVICE_TYPE=api
+
+# =============================================================================
+# 服务器配置 (SERVER_)
+# =============================================================================
+# SERVER_HOST=127.0.0.1
+# SERVER_PORT=8000
+# 工作进程数（生产环境建议设为 CPU 核心数）
+# SERVER_WORKERS=1
+# 是否启用热重载（生产环境应设为 false）
+# SERVER_RELOAD=true
+
+# =============================================================================
+# 数据库配置 (DATABASE_)
+# =============================================================================
+# 数据库连接字符串（默认 SQLite）
+# DATABASE_URL=sqlite+aiosqlite:///./dev.db
+# PostgreSQL: postgresql+asyncpg://user:pass@localhost:5432/{project_name_snake}
+# MySQL: mysql+aiomysql://user:pass@localhost:3306/{project_name_snake}
+
+# 连接池大小
+# DATABASE_POOL_SIZE=5
+# 连接池最大溢出连接数
+# DATABASE_MAX_OVERFLOW=10
+# 连接回收时间（秒）
+# DATABASE_POOL_RECYCLE=3600
+# 获取连接超时时间（秒）
+# DATABASE_POOL_TIMEOUT=30
+# 是否在获取连接前 PING
+# DATABASE_POOL_PRE_PING=true
+# 是否输出 SQL 语句（调试用）
+# DATABASE_ECHO=false
+
+# =============================================================================
+# 缓存配置 (CACHE_)
+# =============================================================================
+# 缓存类型: memory / redis / memcached
+# CACHE_TYPE=memory
+# Redis/Memcached URL
+# CACHE_URL=redis://localhost:6379/0
+# 内存缓存最大大小
+# CACHE_MAX_SIZE=1000
+
+# =============================================================================
+# 日志配置 (LOG_)
+# =============================================================================
+# 日志级别: DEBUG / INFO / WARNING / ERROR / CRITICAL
+# LOG_LEVEL=INFO
+# 日志文件目录
+# LOG_DIR=logs
+# 日志文件轮转时间 (HH:MM 格式)
+# LOG_ROTATION_TIME=00:00
+# 日志文件轮转大小阈值
+# LOG_ROTATION_SIZE=100 MB
+# 日志文件保留天数
+# LOG_RETENTION_DAYS=7
+# 是否启用日志文件轮转
+# LOG_ENABLE_FILE_ROTATION=true
+# 是否输出日志到控制台
+# LOG_ENABLE_CONSOLE=true
+
+# =============================================================================
+# 健康检查配置 (HEALTH_CHECK_)
+# =============================================================================
+# 健康检查端点路径
+# HEALTH_CHECK_PATH=/api/health
+# 是否启用健康检查端点
+# HEALTH_CHECK_ENABLED=true
+
+# =============================================================================
+# 管理后台配置 (ADMIN_) - SQLAdmin Admin Console
+# =============================================================================
+# 是否启用管理后台（生产建议仅内网或配合反向代理）
+# ADMIN_ENABLED=false
+# 管理后台路径（默认 /api/admin-console，避免与业务 URL 冲突）
+# ADMIN_PATH=/api/admin-console
+#
+# SQLAdmin 通常要求同步 SQLAlchemy Engine：
+# - 若 DATABASE_URL 使用的是异步驱动（如 postgresql+asyncpg），建议显式提供同步 URL 覆盖
+# ADMIN_DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/{project_name_snake}
+#
+# 可选：显式指定项目侧模块（用于注册 views/auth）
+# ADMIN_VIEWS_MODULE={project_name_snake}.admin_console
+#
+# 认证（默认建议 basic / bearer；jwt/custom 通常需要自定义 backend）
+# ADMIN_AUTH_MODE=basic
+# ADMIN_AUTH_SECRET_KEY=CHANGE_ME_TO_A_RANDOM_SECRET
+#
+# basic：登录页用户名/密码
+# ADMIN_AUTH_BASIC_USERNAME=admin
+# ADMIN_AUTH_BASIC_PASSWORD=change_me
+#
+# bearer：token 白名单（也支持在登录页输入 token）
+# ADMIN_AUTH_BEARER_TOKENS=["change_me_token"]
+#
+# custom/jwt：自定义认证后端（动态导入）
+# ADMIN_AUTH_BACKEND=yourpkg.admin_auth:backend
+
+# =============================================================================
+# CORS 配置 (CORS_)
+# =============================================================================
+# 允许的 CORS 源（生产环境应设置具体域名）
+# CORS_ORIGINS=["*"]
+# 是否允许 CORS 凭据
+# CORS_ALLOW_CREDENTIALS=true
+# 允许的 CORS 方法
+# CORS_ALLOW_METHODS=["*"]
+# 允许的 CORS 头
+# CORS_ALLOW_HEADERS=["*"]
+
+# =============================================================================
+# 调度器配置 (SCHEDULER_)
+# =============================================================================
+# 是否在 API 服务中启用内嵌调度器
+# SCHEDULER_ENABLED=true
+# 定时任务模块列表（为空时自动发现 schedules 模块）
+# SCHEDULER_SCHEDULE_MODULES=[]
+
+# =============================================================================
+# 任务队列配置 (TASK_)
+# =============================================================================
+# 任务队列代理 URL（如 Redis 或 RabbitMQ）
+# TASK_BROKER_URL=redis://localhost:6379/1
+# 最大重试次数
+# TASK_MAX_RETRIES=3
+# 任务超时时间（秒）
+# TASK_TIMEOUT=3600
+
+# =============================================================================
+# 事件总线配置 (EVENT_)
+# =============================================================================
+# 事件总线代理 URL（如 RabbitMQ）
+# EVENT_BROKER_URL=amqp://guest:guest@localhost:5672/
+# 事件交换机名称
+# EVENT_EXCHANGE_NAME=aury.events
+
+# =============================================================================
+# 数据库迁移配置 (MIGRATION_)
+# =============================================================================
+# Alembic 配置文件路径
+# MIGRATION_CONFIG_PATH=alembic.ini
+# Alembic 迁移脚本目录
+# MIGRATION_SCRIPT_LOCATION=migrations
+# 是否自动创建迁移配置和目录
+# MIGRATION_AUTO_CREATE=true
+
+# =============================================================================
+# 对象存储配置 (STORAGE_) - 基于 aury-sdk-storage
+# =============================================================================
+# 是否启用存储组件
+# STORAGE_ENABLED=true
+# 存储类型: local / s3 / cos / oss
+# STORAGE_TYPE=local
+#
+# 本地存储（开发环境）
+# STORAGE_BASE_PATH=./storage
+#
+# S3/COS/OSS 通用配置
+# STORAGE_ACCESS_KEY_ID=AKIDxxxxx
+# STORAGE_ACCESS_KEY_SECRET=xxxxx
+# STORAGE_SESSION_TOKEN=
+# STORAGE_ENDPOINT=https://cos.ap-guangzhou.myqcloud.com
+# STORAGE_REGION=ap-guangzhou
+# STORAGE_BUCKET_NAME=my-bucket-1250000000
+# STORAGE_ADDRESSING_STYLE=virtual
+#
+# STS AssumeRole（可选，服务端自动刷新凭证）
+# STORAGE_ROLE_ARN=
+# STORAGE_ROLE_SESSION_NAME=aury-storage
+# STORAGE_EXTERNAL_ID=
+# STORAGE_STS_ENDPOINT=
+# STORAGE_STS_REGION=
+# STORAGE_STS_DURATION_SECONDS=3600
+
+# =============================================================================
+# RPC 客户端配置 (RPC_CLIENT_)
+# =============================================================================
+# 服务地址映射 {{service_name: url}}
+# RPC_CLIENT_SERVICES={{"user-service": "http://localhost:8001"}}
+# 默认超时时间（秒）
+# RPC_CLIENT_DEFAULT_TIMEOUT=30
+# 默认重试次数
+# RPC_CLIENT_DEFAULT_RETRY_TIMES=3
+# DNS 解析使用的协议
+# RPC_CLIENT_DNS_SCHEME=http
+# DNS 解析默认端口
+# RPC_CLIENT_DNS_PORT=80
+# 是否使用 DNS 回退（K8s/Docker Compose 自动 DNS）
+# RPC_CLIENT_USE_DNS_FALLBACK=true
+
+# =============================================================================
+# RPC 服务注册配置 (RPC_SERVICE_)
+# =============================================================================
+# 服务名称（用于注册）
+# RPC_SERVICE_NAME={project_name_snake}
+# 服务地址（用于注册）
+# RPC_SERVICE_URL=http://localhost:8000
+# 健康检查 URL（用于注册）
+# RPC_SERVICE_HEALTH_CHECK_URL=http://localhost:8000/api/health
+# 是否自动注册到服务注册中心
+# RPC_SERVICE_AUTO_REGISTER=false

aury/boot/commands/templates/project/gitignore.tpl

@@ -0,0 +1,128 @@
+# =============================================================================
+# {project_name} .gitignore
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Python
+# -----------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.manifest
+*.spec
+
+# -----------------------------------------------------------------------------
+# 虚拟环境
+# -----------------------------------------------------------------------------
+.venv/
+venv/
+ENV/
+env/
+.eggs/
+*.egg-info/
+*.egg
+
+# -----------------------------------------------------------------------------
+# 包管理
+# -----------------------------------------------------------------------------
+# uv
+.uv/
+
+# pip
+pip-log.txt
+pip-delete-this-directory.txt
+
+# -----------------------------------------------------------------------------
+# 测试和覆盖率
+# -----------------------------------------------------------------------------
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# -----------------------------------------------------------------------------
+# 类型检查和静态分析
+# -----------------------------------------------------------------------------
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# -----------------------------------------------------------------------------
+# 构建和分发
+# -----------------------------------------------------------------------------
+dist/
+build/
+*.egg-info/
+.eggs/
+sdist/
+wheels/
+MANIFEST
+
+# -----------------------------------------------------------------------------
+# 环境配置（敏感信息）
+# -----------------------------------------------------------------------------
+.env
+.env.local
+.env.*.local
+*.local.yml
+*.local.yaml
+
+# -----------------------------------------------------------------------------
+# 日志
+# -----------------------------------------------------------------------------
+logs/
+*.log
+
+# -----------------------------------------------------------------------------
+# IDE 和编辑器
+# -----------------------------------------------------------------------------
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+*.sublime-project
+*.sublime-workspace
+
+# -----------------------------------------------------------------------------
+# macOS
+# -----------------------------------------------------------------------------
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# -----------------------------------------------------------------------------
+# Windows
+# -----------------------------------------------------------------------------
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# -----------------------------------------------------------------------------
+# 项目特定
+# -----------------------------------------------------------------------------
+# 数据库文件（开发用 SQLite）
+*.db
+*.sqlite
+*.sqlite3
+
+# 上传文件
+uploads/
+media/
+
+# 临时文件
+tmp/
+temp/
+
+# 缓存
+.cache/

aury/boot/commands/templates/project/main.py.tpl

@@ -0,0 +1,41 @@
+"""应用入口。
+
+使用方式：
+    # 开发模式
+    aury server dev
+
+    # 生产模式
+    aury server prod
+"""
+
+from aury.boot.application.app.base import FoundationApp
+
+from {import_prefix}api import router as api_router
+from {import_prefix}config import AppConfig
+
+# 创建配置
+config = AppConfig()
+
+# 创建应用
+#
+# 框架默认注册端点：
+#   - GET /api/health  健康检查（检查数据库/缓存状态）
+#
+# 可通过环境变量配置：
+#   - HEALTH_CHECK_PATH: 健康检查路径（默认 /api/health）
+#   - HEALTH_CHECK_ENABLED: 是否启用（默认 true）
+#
+app = FoundationApp(
+    title="{project_name}",
+    version="0.1.0",
+    description="{project_name} - 基于 Aury Boot",
+    config=config,
+)
+
+# 注册 API 路由
+app.include_router(api_router, prefix="/api")
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

aury/boot/commands/templates/project/modules/api.py.tpl

@@ -0,0 +1,19 @@
+"""API 路由模块。
+
+路由结构：
+    api/
+    ├── __init__.py   # 本文件，汇总路由
+    ├── user.py       # prefix="/v1/users"
+    └── article.py    # prefix="/v1/articles"
+
+main.py 中注册：app.include_router(api_router, prefix="/api")
+最终路径：/api/v1/users, /api/v1/articles
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# 注册子路由（示例）
+# from . import example
+# router.include_router(example.router)