fastapp-cli 0.1.0__py3-none-any.whl

fastapp_cli/templates/project/.pre-commit-config.yaml.j2

@@ -0,0 +1,80 @@
+# Pre-commit 配置
+# 官方文档: https://pre-commit.com/
+#
+# 快速开始:
+#   uv sync --group dev            # 安装含 pre-commit 的 dev 依赖
+#   uv run pre-commit install      # 安装 git hook
+#   uv run pre-commit run --all-files   # 对全量文件执行一次
+#
+# 升级所有 hook 版本:
+#   uv run pre-commit autoupdate
+
+default_language_version:
+  python: python{{ python_version }}
+
+# 对于较慢的 hook（例如 mypy），默认仅在 pre-push 阶段运行
+default_stages: [pre-commit]
+
+# 全局排除目录/文件
+exclude: |
+  (?x)^(
+    alembic/versions/.*|
+    \.venv/.*|
+    build/.*|
+    dist/.*|
+    uv\.lock
+  )$
+
+repos:
+  # ---------------------------------------------------------------------------
+  # 通用基础检查（空白字符、文件末尾、大文件、合法 YAML/TOML 等）
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: debug-statements
+      - id: detect-private-key
+
+  # ---------------------------------------------------------------------------
+  # Ruff: linter + formatter（替代 flake8 / isort / black / pyupgrade）
+  # 规则与 pyproject.toml 的 [tool.ruff] 配置一致
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      # 先执行 ruff 检查并自动修复
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      # 再执行 ruff 格式化
+      - id: ruff-format
+
+  # ---------------------------------------------------------------------------
+  # Mypy: 静态类型检查
+  # 规则与 pyproject.toml 的 [tool.mypy] 配置一致
+  # 说明：mypy 较慢，默认仅在 pre-push 阶段运行；如需每次提交都跑，删掉 stages 即可
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.20.2
+    hooks:
+      - id: mypy
+        stages: [pre-push]
+        files: ^app/
+        args: [--config-file=pyproject.toml]
+        additional_dependencies:
+          - pydantic>=2.0
+          - pydantic-settings>=2.0
+          - sqlmodel>=0.0.38
+          - fastapi>=0.115
+          - types-pymysql

fastapp_cli/templates/project/.python-version.j2

@@ -0,0 +1 @@
+{{ python_version }}

fastapp_cli/templates/project/Dockerfile.j2

@@ -0,0 +1,17 @@
+{% if use_docker %}
+# FastAPI 服务镜像：基于 uv 官方镜像
+FROM ghcr.io/astral-sh/uv:python{{ python_version }}-bookworm-slim
+
+WORKDIR /app
+
+# 先拷贝依赖清单以利用镜像层缓存
+COPY pyproject.toml ./
+RUN uv sync --no-dev --no-install-project || uv sync --no-dev
+
+# 拷贝项目代码
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+{% endif %}

fastapp_cli/templates/project/Makefile.j2

@@ -0,0 +1,31 @@
+.PHONY: sync dev test lint format migrate revision
+
+# 安装依赖（含 dev 组）
+sync:
+	uv sync --group dev
+
+# 本地开发启动（热重载）
+dev:
+	uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+
+# 运行测试
+test:
+	uv run pytest
+
+# 代码检查（lint + 类型检查）
+lint:
+	uv run ruff check .
+	uv run mypy app
+
+# 代码格式化
+format:
+	uv run ruff check --fix .
+	uv run ruff format .
+
+# 执行数据库迁移
+migrate:
+	uv run alembic upgrade head
+
+# 生成迁移脚本：make revision m="add xxx table"
+revision:
+	uv run alembic revision --autogenerate -m "$(m)"

fastapp_cli/templates/project/README.md.j2

@@ -0,0 +1,68 @@
+# {{ project_name }}
+
+> {{ project_description }}
+> 由 [fastapp-cli](https://pypi.org/project/fastapp-cli/) v{{ fastapp_cli_version }} 生成于 {{ year }}，作者：{{ author_name }}
+
+FastAPI + SQLModel + Celery 工程模板，含分层架构、统一响应 / 异常 / TraceID / 日志、分页 CRUD、Alembic 迁移与完整测试。
+
+## 快速开始
+
+```bash
+uv sync --group dev
+make dev        # 或 uv run uvicorn app.main:app --reload
+```
+
+- 接口文档：http://localhost:8000/api/v1/docs
+- 健康检查：http://localhost:8000/api/v1/health
+
+## 降级行为说明
+
+| 组件 | 默认 | 缺席时行为 |
+|---|---|---|
+| MySQL | `.env` 中配置 | 启动不阻塞，`/api/v1/health` 返回 `database: "down"`，数据接口统一返回 500 |
+| Redis (Celery) | `redis://localhost:6379` | 启动不阻塞，自动降级为 `memory://` broker 并输出告警日志 |
+
+生产环境只需在 `.env` 配置真实 MySQL / Redis 地址，无需改代码。
+
+## 常用命令
+
+```bash
+make dev          # 本地开发启动（热重载）
+make test         # 运行测试（sqlite 内存库，无需 MySQL）
+make lint         # ruff + mypy
+make format       # ruff 格式化
+make migrate      # alembic upgrade head
+make revision m="add xxx"   # 生成迁移脚本
+```
+
+Celery：
+
+```bash
+bash scripts/celery_worker.sh    # worker
+bash scripts/celery_beat.sh      # 定时任务
+bash scripts/celery_flower.sh    # 监控面板（:5555）
+```
+
+## 目录结构
+
+```text
+app/
+├── main.py            # 工厂函数 create_app + lifespan（DB/redis 探测降级）
+├── core/              # 配置、数据库、日志、异常、中间件、Celery
+├── api/
+│   ├── deps.py        # DBSession / CurrentUser（认证占位）
+│   └── v1/endpoints/  # health / items（分页 CRUD 示例）
+├── models/            # SQLModel 模型（建模参考 docs/SQLModel定义示例.md）
+├── schemas/           # Pydantic Schema（统一响应、过滤器）
+├── crud/              # CRUD 泛型基类 + 业务实现
+├── services/          # Service 层
+├── tasks/             # Celery 任务
+└── utils/             # 工具扩展位
+```
+
+## 扩展指南
+
+1. **新增业务域**：仿照 `item` 五件套（model / schema / crud / service / endpoint），在 `models/__init__.py` 注册新模型，在 `api/v1/router.py` 挂载新路由；
+2. **生成迁移**：`make revision m="add xxx table"` 后检查 `alembic/versions/`，再 `make migrate`；
+3. **接入真实认证**：替换 `app/api/deps.py::get_current_user` 的占位实现；
+4. **新增 Celery 任务**：在 `app/tasks/` 中使用 `@celery_app.task` 装饰器编写。

fastapp_cli/templates/project/alembic/env.py.j2

@@ -0,0 +1,84 @@
+"""Alembic 迁移环境配置."""
+
+from __future__ import annotations
+
+import sys
+from logging.config import fileConfig
+from pathlib import Path
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+from sqlmodel import SQLModel
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from app.core.config import settings
+
+# 导入所有 model 以便 SQLModel.metadata 包含全部表
+from app import models  # noqa: F401
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# 注入数据库链接
+config.set_main_option("sqlalchemy.url", str(settings.DATABASE_URI))
+
+target_metadata = SQLModel.metadata
+
+# 只允许 alembic 管理的表名集合：仅包含 app/models 中显式定义的表
+# 其他存量表（历史遗留 / 跨项目共用）一律忽略，避免被 autogenerate 误判为应删除
+MANAGED_TABLES = set(target_metadata.tables.keys())
+
+
+def include_object(object_, name, type_, reflected, compare_to):
+    """Alembic autogenerate 过滤钩子.
+
+    - 表对象：仅当表在 SQLModel.metadata 中已声明（即本项目管理的表）时才参与对比，
+      其余表视为外部表，跳过 (不会被 drop)。
+    - 索引/约束等子对象：若所属表不在管理范围内，则一并忽略。
+    """
+    if type_ == "table":
+        return name in MANAGED_TABLES
+    # 非表对象：通过其归属表过滤
+    parent_table = getattr(object_, "table", None)
+    return not (parent_table is not None and parent_table.name not in MANAGED_TABLES)
+
+
+def run_migrations_offline() -> None:
+    """离线模式运行迁移."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+        include_object=include_object,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """在线模式运行迁移."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+            include_object=include_object,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

fastapp_cli/templates/project/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}.
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

fastapp_cli/templates/project/alembic.ini.j2

@@ -0,0 +1,50 @@
+# Alembic 迁移配置：数据库连接串由 alembic/env.py 从 app.core.config 读取，这里留空
+
+[alembic]
+# path to migration scripts
+script_location = alembic
+
+# template used to generate migration file names; default is %%(rev)s_%%(slug)s
+# file_template = %%(rev)s_%%(slug)s
+
+# timezone to use when rendering the date within the migration file
+# timezone =
+
+sqlalchemy.url =
+
+[post_write_hooks]
+# 此处可配置生成迁移文件后的自动格式化钩子
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

fastapp_cli/templates/project/app/__init__.py.j2

@@ -0,0 +1 @@
+"""app"""

fastapp_cli/templates/project/app/api/__init__.py.j2

@@ -0,0 +1 @@
+"""app · api"""

fastapp_cli/templates/project/app/api/deps.py.j2

@@ -0,0 +1,33 @@
+"""API 全局依赖."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from loguru import logger
+from sqlmodel import Session
+
+from app.core.config import settings
+from app.core.database import get_session
+from app.core.exceptions import UnauthorizedError
+
+
+def get_current_user(request: Request) -> str:
+    """获取当前登录用户（认证占位）.
+
+    非生产环境直接返回 settings.MOCK_USER，便于本地开发与测试；
+    生产环境抛出 UnauthorizedError。接入真实认证时在此处替换实现，
+    参考：从请求头解析 token -> 校验 -> 返回用户标识。
+
+    :raises UnauthorizedError: 生产环境下未接入认证
+    """
+    _ = request.headers  # 接入真实认证时从 headers 解析凭证
+    if not settings.is_production:
+        return settings.MOCK_USER
+    logger.warning("生产环境尚未接入认证实现，拒绝访问")
+    raise UnauthorizedError("Invalid Auth")
+
+
+CurrentUser = Annotated[str, Depends(get_current_user)]
+DBSession = Annotated[Session, Depends(get_session)]

fastapp_cli/templates/project/app/api/v1/__init__.py.j2

@@ -0,0 +1 @@
+"""app · api · v1"""

fastapp_cli/templates/project/app/api/v1/endpoints/__init__.py.j2

@@ -0,0 +1 @@
+"""app · api · v1 · endpoints"""

fastapp_cli/templates/project/app/api/v1/endpoints/health.py.j2

@@ -0,0 +1,33 @@
+"""健康检查端点."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+from sqlalchemy import text
+from sqlmodel import Session
+
+from app.core.config import settings
+from app.core.database import engine
+
+router = APIRouter()
+
+
+def _database_status() -> str:
+    """探测数据库连通性，返回 up / down."""
+    try:
+        with Session(engine) as session:
+            session.execute(text("SELECT 1"))
+        return "up"
+    except Exception:  # pylint: disable=broad-except
+        return "down"
+
+
+@router.get("", summary="健康检查")
+def health() -> dict:
+    """健康检查：应用状态 + 数据库连通状态."""
+    return {
+        "status": "ok",
+        "app": settings.APP_NAME,
+        "env": settings.APP_ENV,
+        "database": _database_status(),
+    }

fastapp_cli/templates/project/app/api/v1/endpoints/items.py.j2

@@ -0,0 +1,90 @@
+"""Items 分页 CRUD 示例端点（demo 业务域，可替换为实际业务接口）."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from fastapi_filter import FilterDepends
+
+from app.api.deps import CurrentUser, DBSession
+from app.crud.item import CRUDItem
+from app.models.item import Item
+from app.schemas.common import PageResponse, Response
+from app.schemas.item import ItemCreate, ItemFilter, ItemRead, ItemUpdate
+from app.services.item_service import ItemService
+
+router = APIRouter()
+
+
+def get_service(db: DBSession) -> ItemService:
+    return ItemService(db, CRUDItem(Item))
+
+
+ItemServiceDep = Annotated[ItemService, Depends(get_service)]
+
+
+@router.get(
+    "",
+    response_model=PageResponse[ItemRead],
+    summary="分页查询 Item",
+)
+def list_items(
+    filter_params: Annotated[ItemFilter, FilterDepends(ItemFilter, by_alias=True)],
+    service: ItemServiceDep,
+):
+    return service.list_page_objs(filter_params)
+
+
+@router.post(
+    "",
+    response_model=Response[ItemRead],
+    summary="创建 Item",
+)
+def create_item(
+    payload: ItemCreate,
+    service: ItemServiceDep,
+    current_user: CurrentUser,
+) -> Response[ItemRead]:
+    data: ItemRead = service.create(payload)
+    return Response(data=data)
+
+
+@router.get(
+    "/{item_id}",
+    response_model=Response[ItemRead],
+    summary="获取单个 Item",
+)
+def get_item(
+    item_id: int,
+    service: ItemServiceDep,
+) -> Response[ItemRead]:
+    data: ItemRead = service.get(item_id)
+    return Response(data=data)
+
+
+@router.patch(
+    "/{item_id}",
+    response_model=Response[ItemRead],
+    summary="更新 Item",
+)
+def update_item(
+    item_id: int,
+    payload: ItemUpdate,
+    service: ItemServiceDep,
+) -> Response[ItemRead]:
+    data: ItemRead = service.update(item_id, payload)
+    return Response(data=data)
+
+
+@router.delete(
+    "/{item_id}",
+    response_model=Response[ItemRead],
+    summary="删除 Item",
+)
+def delete_item(
+    item_id: int,
+    service: ItemServiceDep,
+) -> Response[ItemRead]:
+    data: ItemRead = service.delete(item_id)
+    return Response(data=data)

fastapp_cli/templates/project/app/api/v1/router.py.j2

@@ -0,0 +1,9 @@
+"""v1 总路由."""
+
+from fastapi import APIRouter
+
+from app.api.v1.endpoints import health, items
+
+api_router = APIRouter()
+api_router.include_router(items.router, prefix="/items", tags=["items"])
+api_router.include_router(health.router, prefix="/health", tags=["health"])

fastapp_cli/templates/project/app/core/__init__.py.j2

@@ -0,0 +1 @@
+"""app · core"""

fastapp_cli/templates/project/app/core/celery_app.py.j2

@@ -0,0 +1,62 @@
+"""Celery 应用实例.
+
+主应用与 worker 共用 ``build_celery_app`` 构造入口：
+
+- 默认 broker/backend 来自 settings（redis）；
+- Web 应用在 lifespan 中探测 redis，不可达时自动降级为 memory（见 app/main.py）；
+- worker 启动入口固定使用本模块的 ``celery_app``（生产环境请确保 redis 可达）。
+"""
+
+from __future__ import annotations
+
+from celery import Celery
+
+from app.core.config import settings
+
+
+def build_celery_app(broker_url: str, backend_url: str, *, name: str = "worker") -> Celery:
+    """构造 Celery 实例.
+
+    :param broker_url: broker 地址（redis:// 或 memory://）
+    :param backend_url: result backend 地址
+    :param name: Celery 应用名
+    :return: 配置完成的 Celery 实例
+    """
+    celery = Celery(name, broker=broker_url, backend=backend_url)
+    celery.conf.update(
+        task_default_queue=settings.CELERY_TASK_DEFAULT_QUEUE,
+        task_serializer="json",
+        result_serializer="json",
+        accept_content=["json"],
+        timezone="Asia/Shanghai",
+        enable_utc=False,
+        task_track_started=True,
+        task_time_limit=60 * 60,
+        task_soft_time_limit=50 * 60,
+        worker_max_tasks_per_child=200,
+        worker_prefetch_multiplier=4,
+        broker_connection_retry_on_startup=True,
+    )
+    return celery
+
+
+def degrade_to_memory(celery: Celery) -> None:
+    """将 Celery 降级为内存 broker/backend（本地无 redis 时使用）."""
+    celery.conf.broker_url = "memory://"
+    celery.conf.result_backend = "cache+memory://"
+
+
+celery_app = build_celery_app(
+    settings.CELERY_BROKER_URL,
+    settings.CELERY_RESULT_BACKEND,
+    name="{{ project_name | replace('-', '_') }}_worker",
+)
+
+# 定时任务示例（如不需要可删除）
+# from celery.schedules import crontab
+celery_app.conf.beat_schedule = {
+    # "daily-report": {
+    #     "task": "app.tasks.sample_tasks.sample_task",
+    #     "schedule": crontab(hour=2, minute=0),
+    # },
+}