fastapp-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapp-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: FastAPI 项目脚手架：一条命令生成完整可运行的 FastAPI 工程
 Author: aidenmo
 License: MIT
@@ -31,11 +31,12 @@ fastapp create my-server
 - **分层架构**：`api / schemas / crud / services / models` 分层，内置泛型 CRUD / Service 基类
 - **开箱即用的工程能力**：统一响应 / 异常体系、TraceID 中间件、loguru 日志、pydantic-settings 多环境配置
 - **分页 CRUD + 过滤**：基于 fastapi-pagination 与 fastapi-filter 的完整示例（`/api/v1/items`）
-- **Celery 骨架**：默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警
+- **Celery 可选**：`--celery` 启用时生成完整任务骨架（默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警）；默认不启用
 - **Alembic 迁移**：接入 SQLModel.metadata，含 autogenerate 过滤钩子
 - **优雅降级**：MySQL 缺席不阻塞启动，`/api/v1/health` 返回 `database: up/down`
 - **工程化配套**：Makefile、scripts/、pre-commit、ruff + mypy + pytest 配置全套
-- **可选部署文件**：`--pm2` / `--docker` 按需生成
+- **可选部署文件**：`--pm2` / `--docker` 按需生成（pm2.config.js，celery 未启用时对应启动命令自动注释）
+- **AI Agent 友好**：生成项目自带 `docs/agent_guide.md` 开发参考文档（架构、核心方法清单、扩展流程）
 
 ## 安装
 
@@ -60,8 +61,9 @@ fastapp create <project_name> [options]
 |---|---|---|
 | `project_name` | 必填 | 项目名；小写字母/数字/连字符，如 `my-server` |
 | `--description` | 交互提问 | 项目描述 |
-| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.json` |
+| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.js` |
 | `--docker / --no-docker` | 交互提问 | 是否生成 `Dockerfile` |
+| `--celery / --no-celery` | 交互提问（默认不启用） | 是否启用 Celery 异步任务 |
 | `--python` | `3.12` | 目标 Python 版本（写入 `.python-version`） |
 | `--author` | `git config user.name` | 作者署名 |
 | `--force` | 关 | 目标目录已存在时覆盖重建 |
@@ -70,7 +72,7 @@ fastapp create <project_name> [options]
 全部关键项通过 flag 提供时零交互：
 
 ```bash
-fastapp create my-server --description "demo" --no-pm2 --no-docker
+fastapp create my-server --description "demo" --no-pm2 --no-docker --no-celery
 ```
 
 生成完成后：
@@ -82,7 +84,7 @@ make dev        # 访问 /api/v1/docs
 
 ## 生成项目依赖
 
-fastapi、sqlmodel、alembic、celery[redis]、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit。
+fastapi、sqlmodel、alembic、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit；`--celery` 启用时额外引入 celery[redis] 与 flower。
 
 ## 开发 fastapp-cli 自身
 

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/README.md

@@ -11,11 +11,12 @@ fastapp create my-server
 - **分层架构**：`api / schemas / crud / services / models` 分层，内置泛型 CRUD / Service 基类
 - **开箱即用的工程能力**：统一响应 / 异常体系、TraceID 中间件、loguru 日志、pydantic-settings 多环境配置
 - **分页 CRUD + 过滤**：基于 fastapi-pagination 与 fastapi-filter 的完整示例（`/api/v1/items`）
-- **Celery 骨架**：默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警
+- **Celery 可选**：`--celery` 启用时生成完整任务骨架（默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警）；默认不启用
 - **Alembic 迁移**：接入 SQLModel.metadata，含 autogenerate 过滤钩子
 - **优雅降级**：MySQL 缺席不阻塞启动，`/api/v1/health` 返回 `database: up/down`
 - **工程化配套**：Makefile、scripts/、pre-commit、ruff + mypy + pytest 配置全套
-- **可选部署文件**：`--pm2` / `--docker` 按需生成
+- **可选部署文件**：`--pm2` / `--docker` 按需生成（pm2.config.js，celery 未启用时对应启动命令自动注释）
+- **AI Agent 友好**：生成项目自带 `docs/agent_guide.md` 开发参考文档（架构、核心方法清单、扩展流程）
 
 ## 安装
 
@@ -40,8 +41,9 @@ fastapp create <project_name> [options]
 |---|---|---|
 | `project_name` | 必填 | 项目名；小写字母/数字/连字符，如 `my-server` |
 | `--description` | 交互提问 | 项目描述 |
-| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.json` |
+| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.js` |
 | `--docker / --no-docker` | 交互提问 | 是否生成 `Dockerfile` |
+| `--celery / --no-celery` | 交互提问（默认不启用） | 是否启用 Celery 异步任务 |
 | `--python` | `3.12` | 目标 Python 版本（写入 `.python-version`） |
 | `--author` | `git config user.name` | 作者署名 |
 | `--force` | 关 | 目标目录已存在时覆盖重建 |
@@ -50,7 +52,7 @@ fastapp create <project_name> [options]
 全部关键项通过 flag 提供时零交互：
 
 ```bash
-fastapp create my-server --description "demo" --no-pm2 --no-docker
+fastapp create my-server --description "demo" --no-pm2 --no-docker --no-celery
 ```
 
 生成完成后：
@@ -62,7 +64,7 @@ make dev        # 访问 /api/v1/docs
 
 ## 生成项目依赖
 
-fastapi、sqlmodel、alembic、celery[redis]、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit。
+fastapi、sqlmodel、alembic、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit；`--celery` 启用时额外引入 celery[redis] 与 flower。
 
 ## 开发 fastapp-cli 自身
 

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapp-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "FastAPI 项目脚手架：一条命令生成完整可运行的 FastAPI 工程"
 readme = "README.md"
 requires-python = ">=3.10"

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/__init__.py

@@ -1,3 +1,3 @@
 """fastapp-cli: FastAPI 项目脚手架."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/create.py

@@ -68,13 +68,18 @@ def create(
     pm2: bool = typer.Option(
         None,
         "--pm2/--no-pm2",
-        help="是否生成 pm2.config.json（未指定时交互提问）",
+        help="是否生成 pm2.config.js（未指定时交互提问）",
     ),
     docker: bool = typer.Option(
         None,
         "--docker/--no-docker",
         help="是否生成 Dockerfile（未指定时交互提问）",
     ),
+    celery: bool = typer.Option(
+        None,
+        "--celery/--no-celery",
+        help="是否启用 Celery 异步任务（未指定时交互提问，默认不启用）",
+    ),
     python_version: str = typer.Option(
         "3.12",
         "--python",
@@ -122,6 +127,7 @@ def create(
     desc = prompts.ask_description(description)
     use_pm2 = prompts.ask_use_pm2(pm2)
     use_docker = prompts.ask_use_docker(docker)
+    use_celery = prompts.ask_use_celery(celery)
     author_name = author or _git_user_name() or "fastapp-cli"
 
     # 3. 渲染
@@ -132,6 +138,7 @@ def create(
         "author_name": author_name,
         "use_pm2": use_pm2,
         "use_docker": use_docker,
+        "use_celery": use_celery,
         "year": datetime.now(timezone.utc).year,
         "fastapp_cli_version": __version__,
     }

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/prompts.py

@@ -1,6 +1,6 @@
 """混合模式交互提问.
 
-关键项（描述 / pm2 / Dockerfile）在未通过 flag 提供时交互提问；
+关键项（描述 / pm2 / Dockerfile / celery）在未通过 flag 提供时交互提问；
 flag 已提供则跳过提问，实现零交互。
 """
 
@@ -33,3 +33,10 @@ def ask_use_docker(provided: bool | None) -> bool:
     if provided is not None:
         return provided
     return typer.confirm("是否包含 Dockerfile?", default=False)
+
+
+def ask_use_celery(provided: bool | None) -> bool:
+    """是否启用 Celery 异步任务：未指定时交互提问，默认不启用."""
+    if provided is not None:
+        return provided
+    return typer.confirm("是否启用 Celery 异步任务?", default=False)

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/.env.development.example.j2

@@ -16,6 +16,7 @@ MYSQL_DB={{ project_name | replace('-', '_') }}_dev
 # 打印 SQL 方便排查
 SQL_ECHO=true
 
-# 本地 Redis
+{% if use_celery %}# 本地 Redis
 CELERY_BROKER_URL=redis://localhost:6379/0
 CELERY_RESULT_BACKEND=redis://localhost:6379/1
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/.env.example.j2

@@ -17,7 +17,7 @@ MYSQL_DB={{ project_name | replace('-', '_') }}
 # 是否打印 SQL（开发环境使用）
 SQL_ECHO=false
 
-# ========== Celery（redis，缺席时应用启动自动降级 memory://） ==========
+{% if use_celery %}# ========== Celery（redis，缺席时应用启动自动降级 memory://） ==========
 CELERY_BROKER_URL=redis://localhost:6379/0
 CELERY_RESULT_BACKEND=redis://localhost:6379/1
 CELERY_TASK_DEFAULT_QUEUE=default
@@ -27,3 +27,4 @@ FLOWER_HOST=0.0.0.0
 FLOWER_PORT=5555
 # 基本认证（可选），格式：user:password，多个用逗号分隔
 # FLOWER_BASIC_AUTH=admin:admin
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/.env.j2

@@ -17,7 +17,7 @@ MYSQL_PASSWORD=
 MYSQL_DB={{ project_name | replace('-', '_') }}_dev
 SQL_ECHO=true
 
-# ========== Celery（本地无 redis 时启动自动降级 memory://） ==========
+{% if use_celery %}# ========== Celery（本地无 redis 时启动自动降级 memory://） ==========
 CELERY_BROKER_URL=redis://localhost:6379/0
 CELERY_RESULT_BACKEND=redis://localhost:6379/1
 CELERY_TASK_DEFAULT_QUEUE=default
@@ -25,3 +25,4 @@ CELERY_TASK_DEFAULT_QUEUE=default
 # ========== Flower ==========
 FLOWER_HOST=0.0.0.0
 FLOWER_PORT=5555
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/README.md.j2

@@ -3,7 +3,7 @@
 > {{ project_description }}
 > 由 [fastapp-cli](https://pypi.org/project/fastapp-cli/) v{{ fastapp_cli_version }} 生成于 {{ year }}，作者：{{ author_name }}
 
-FastAPI + SQLModel + Celery 工程模板，含分层架构、统一响应 / 异常 / TraceID / 日志、分页 CRUD、Alembic 迁移与完整测试。
+FastAPI + SQLModel{% if use_celery %} + Celery{% endif %} 工程模板，含分层架构、统一响应 / 异常 / TraceID / 日志、分页 CRUD、Alembic 迁移与完整测试。
 
 ## 快速开始
 
@@ -20,7 +20,8 @@ make dev        # 或 uv run uvicorn app.main:app --reload
 | 组件 | 默认 | 缺席时行为 |
 |---|---|---|
 | MySQL | `.env` 中配置 | 启动不阻塞，`/api/v1/health` 返回 `database: "down"`，数据接口统一返回 500 |
-| Redis (Celery) | `redis://localhost:6379` | 启动不阻塞，自动降级为 `memory://` broker 并输出告警日志 |
+{% if use_celery %}| Redis (Celery) | `redis://localhost:6379` | 启动不阻塞，自动降级为 `memory://` broker 并输出告警日志 |
+{% endif %}
 
 生产环境只需在 `.env` 配置真实 MySQL / Redis 地址，无需改代码。
 
@@ -35,14 +36,14 @@ make migrate      # alembic upgrade head
 make revision m="add xxx"   # 生成迁移脚本
 ```
 
-Celery：
+{% if use_celery %}Celery：
 
 ```bash
 bash scripts/celery_worker.sh    # worker
 bash scripts/celery_beat.sh      # 定时任务
 bash scripts/celery_flower.sh    # 监控面板（:5555）
 ```
-
+{% endif %}
 ## 目录结构
 
 ```text
@@ -67,4 +68,5 @@ app/
 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` 装饰器编写。
+{% if use_celery %}4. **新增 Celery 任务**：在 `app/tasks/` 中使用 `@celery_app.task` 装饰器编写。
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/core/celery_app.py.j2

@@ -1,4 +1,4 @@
-"""Celery 应用实例.
+{% if use_celery %}"""Celery 应用实例.
 
 主应用与 worker 共用 ``build_celery_app`` 构造入口：
 
@@ -60,3 +60,4 @@ celery_app.conf.beat_schedule = {
     #     "schedule": crontab(hour=2, minute=0),
     # },
 }
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/core/config.py.j2

@@ -80,7 +80,7 @@ class Settings(BaseSettings):
     DB_POOL_SIZE: int = 10
     DB_MAX_OVERFLOW: int = 20
 
-    # ========== Celery 配置 ==========
+{% if use_celery %}    # ========== Celery 配置 ==========
     CELERY_BROKER_URL: str = "redis://localhost:6379/0"
     CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
     CELERY_TASK_DEFAULT_QUEUE: str = "default"
@@ -90,6 +90,7 @@ class Settings(BaseSettings):
     FLOWER_PORT: int = 5555
     # 基本认证，格式：user:password，多个用逗号分隔
     FLOWER_BASIC_AUTH: str | None = None
+{% endif %}
 
     @property
     def is_production(self) -> bool:

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/main.py.j2

@@ -12,8 +12,8 @@ from loguru import logger
 from sqlalchemy import text
 
 from app.api.v1.router import api_router
-from app.core.celery_app import celery_app, degrade_to_memory
-from app.core.config import settings
+{% if use_celery %}from app.core.celery_app import celery_app, degrade_to_memory
+{% endif %}from app.core.config import settings
 from app.core.database import engine
 from app.core.exceptions import register_exception_handlers
 from app.core.logging import setup_logging
@@ -30,7 +30,7 @@ def _probe_database() -> None:
         logger.warning("数据库未就绪，数据接口将返回 500，请配置 .env: {}", exc)
 
 
-def _probe_redis() -> None:
+{% if use_celery %}def _probe_redis() -> None:
     """启动时探测 redis（带超时），不可达时 Celery 自动降级为 memory broker."""
     broker_url = settings.CELERY_BROKER_URL
     if broker_url.startswith("memory"):
@@ -52,18 +52,18 @@ def _probe_redis() -> None:
         logger.warning("redis 未就绪，Celery 已降级为 memory broker: {}", exc)
 
 
-@asynccontextmanager
+{% endif %}@asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
     """应用生命周期.
 
-    - 启动：初始化日志、探测数据库 / redis（缺席降级，不阻塞启动）
+    - 启动：初始化日志、探测数据库{% if use_celery %} / redis（缺席降级，不阻塞启动）{% endif %}
     - 关闭：优雅释放资源
     """
     setup_logging()
     logger.info("{} starting | env={} | debug={}", settings.APP_NAME, settings.APP_ENV, settings.DEBUG)
     _probe_database()
-    _probe_redis()
-
+{% if use_celery %}    _probe_redis()
+{% endif %}
     yield
 
     logger.info("{} stopped", settings.APP_NAME)
@@ -71,6 +71,10 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
 
 def create_app() -> FastAPI:
     """工厂函数：创建 FastAPI 应用实例."""
+    if settings.DEBUG:
+        # DEBUG 模式下打印全部配置，便于本地排查；生产环境（DEBUG=false）不输出，避免泄露敏感配置
+        logger.debug("settings: {}", settings.model_dump())
+
     app_ = FastAPI(
         title=settings.APP_NAME,
         # 注意：固定 False。DEBUG 环境变量仅控制日志级别与 SQL echo；

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/tasks/sample_tasks.py.j2

@@ -1,4 +1,4 @@
-"""Celery 示例任务."""
+{% if use_celery %}"""Celery 示例任务."""
 
 from __future__ import annotations
 
@@ -26,3 +26,4 @@ def sample_task(self, name: str = "world") -> dict:
     logger.info("[task={}] sample_task running, name={}", self.request.id, name)
     time.sleep(1)
     return {"message": f"hello, {name}"}
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/docs/agent_guide.md.j2

@@ -13,8 +13,8 @@
 | ORM | SQLModel (SQLAlchemy) | PEP 695 泛型 CRUD 基类 |
 | 数据库 | MySQL（默认）/ SQLite（测试） | SQLAlchemy 引擎，连接池参数已调优 |
 | 迁移 | Alembic | 增量迁移，`MANAGED_TABLES` 约束只管理业务表 |
-| 异步任务 | Celery + Redis | redis 不可达时自动降级 memory broker |
-| 分页 | fastapi-pagination | 统一分页响应结构 |
+{% if use_celery %}| 异步任务 | Celery + Redis | redis 不可达时自动降级 memory broker |
+{% endif %}| 分页 | fastapi-pagination | 统一分页响应结构 |
 | 过滤 | fastapi-filter | 声明式查询过滤器 |
 | 日志 | loguru | 拦截标准 logging，全链路 trace_id |
 | 配置 | pydantic-settings | 多环境 `.env` 加载 |
@@ -50,7 +50,7 @@ TraceIDMiddleware (最外层，生成/透传 X-Trace-Id)
 ```text
 .
 ├── app/
-│   ├── main.py                  # create_app 工厂 + lifespan（DB/redis 探测，缺席降级不阻塞启动）
+│   ├── main.py                  # create_app 工厂 + lifespan（DB{% if use_celery %}/redis{% endif %} 探测，缺席降级不阻塞启动）
 │   ├── core/                    # 横切基础设施（禁止在此写业务逻辑）
 │   │   ├── config.py            #   settings 配置中心（多环境 .env 加载）
 │   │   ├── database.py          #   engine / get_session / init_db
@@ -58,8 +58,8 @@ TraceIDMiddleware (最外层，生成/透传 X-Trace-Id)
 │   │   ├── exceptions.py        #   AppExceptionError 体系 + 全局异常处理器
 │   │   ├── middleware.py        #   TraceIDMiddleware（trace_id 生成与响应头注入）
 │   │   ├── context_var.py       #   trace_id_var / get_trace_id
-│   │   └── celery_app.py        #   build_celery_app / degrade_to_memory / celery_app 单例
-│   ├── api/
+{% if use_celery %}│   │   └── celery_app.py        #   build_celery_app / degrade_to_memory / celery_app 单例
+{% endif %}│   ├── api/
 │   │   ├── deps.py              #   DBSession / CurrentUser 依赖（认证占位）
 │   │   └── v1/
 │   │       ├── router.py        #   v1 总路由，新业务路由在此挂载
@@ -76,11 +76,13 @@ TraceIDMiddleware (最外层，生成/透传 X-Trace-Id)
 │   ├── services/                # 业务逻辑层
 │   │   ├── base.py              #   ServiceBase 泛型基类（核心复用点）
 │   │   └── item_service.py      #   ItemService(ServiceBase[CRUDItem])
-│   ├── tasks/                   # Celery 任务（sample_tasks.py 为示例）
+│   ├── tasks/{% if use_celery %}                   # Celery 任务（sample_tasks.py 为示例）
 │   └── utils/                   # 通用工具扩展位（空）
-├── alembic/                     # 迁移环境（env.py 已配置 MANAGED_TABLES 白名单过滤）
+{% else %}                   # 预留任务目录
+│   └── utils/                   # 通用工具扩展位（空）
+{% endif %}├── alembic/                     # 迁移环境（env.py 已配置 MANAGED_TABLES 白名单过滤）
 ├── docs/                        # 本文档 + SQLModel定义示例.md（建模规范）
-├── scripts/                     # start.sh / celery_worker.sh / celery_beat.sh / celery_flower.sh
+├── scripts/                     # start.sh{% if use_celery %} / celery_worker.sh / celery_beat.sh / celery_flower.sh{% endif %}
 ├── tests/                       # pytest：conftest 用 sqlite 内存库，无需真实 MySQL
 ├── alembic.ini / Makefile / pyproject.toml
 └── .env / .env.example          # 配置文件（.env 入库，敏感信息按环境覆盖）
@@ -219,7 +221,7 @@ class Product(IDMixin, ProductBase, table=True):
 
 - 单例 `settings`：所有环境变量集中于此，**禁止在业务代码中直接读 `os.environ`**。
 - 加载顺序（后者覆盖前者）：`.env` → `.env.{APP_ENV}` → 系统环境变量。
-- 常用字段：`APP_NAME` / `APP_ENV`（development|production|test）/ `DEBUG` / `API_V1_PREFIX` / `ALLOWED_ORIGINS` / `DATABASE_URI`（未设置时自动按 `MYSQL_*` 拼装）/ `SQL_ECHO` / `CELERY_BROKER_URL` / `MOCK_USER`。
+- 常用字段：`APP_NAME` / `APP_ENV`（development|production|test）/ `DEBUG` / `API_V1_PREFIX` / `ALLOWED_ORIGINS` / `DATABASE_URI`（未设置时自动按 `MYSQL_*` 拼装）/ `SQL_ECHO`{% if use_celery %} / `CELERY_BROKER_URL`{% endif %} / `MOCK_USER`。
 - 属性：`settings.is_production` / `settings.is_test`。
 - 新增配置项：在 `Settings` 类中加字段 + 默认值，并在 `.env.example` / `.env` 中补充说明。
 
@@ -231,7 +233,7 @@ class Product(IDMixin, ProductBase, table=True):
 | `get_session()` | FastAPI 依赖，yield 语法保证 Session 关闭；**通过 `DBSession` 注解使用**，不要自建 Session |
 | `init_db()` | 本地/测试快速建表（生产用 alembic 迁移） |
 
-### 3.9 Celery（`app/core/celery_app.py`）
+{% if use_celery %}### 3.9 Celery（`app/core/celery_app.py`）
 
 | 名称 | 说明 |
 |---|---|
@@ -249,7 +251,7 @@ def send_notice(user_id: int) -> str:
     ...
 ```
 
-### 3.10 日志与 TraceID（`app/core/logging.py`、`app/core/context_var.py`）
+{% endif %}{% if use_celery %}### 3.10{% else %}### 3.9{% endif %} 日志与 TraceID（`app/core/logging.py`、`app/core/context_var.py`）
 
 | 名称 | 说明 |
 |---|---|
@@ -278,8 +280,8 @@ def send_notice(user_id: int) -> str:
 | 新增配置项 | `Settings` 类加字段 + `.env.example` 补说明 |
 | 接入真实认证 | 只替换 `app/api/deps.py::get_current_user` 实现，端点代码不动 |
 | 新增中间件 | `app/core/middleware.py` 实现，并在 `main.py::create_app` 注册；**注意注册顺序**：TraceIDMiddleware 必须最后添加（处于最外层） |
-| 新增 Celery 定时任务 | `app/tasks/` 写任务，`celery_app.conf.beat_schedule` 中注册（该文件内有注释示例） |
-| 自定义业务异常 | 继承 `AppExceptionError`，类属性覆盖 `status_code` / `code` / `message`，全局处理器自动生效 |
+{% if use_celery %}| 新增 Celery 定时任务 | `app/tasks/` 写任务，`celery_app.conf.beat_schedule` 中注册（该文件内有注释示例） |
+{% endif %}| 自定义业务异常 | 继承 `AppExceptionError`，类属性覆盖 `status_code` / `code` / `message`，全局处理器自动生效 |
 | 复杂查询 | 在业务 CRUD 子类中扩展方法，保持 Service 只编排不写 SQL 细节 |
 
 ## 5. 编码规范与注意事项
@@ -298,7 +300,7 @@ def send_notice(user_id: int) -> str:
 
 - **时间字段**：一律通过 `TimestampMixin`；JSON 输出格式 `%Y-%m-%d %H:%M:%S` 由 `FormattedDatetime` 统一处理，勿自行 strftime。
 - **Session 生命周期**：请求内通过 `DBSession` 注入；后台任务/脚本中用 `with Session(engine) as session:`，不要复用请求 Session。
-- **降级行为**：MySQL / Redis 缺席不阻塞启动（health 返回 down、Celery 降级 memory）。本地开发无需强制装依赖，但数据接口在无库时统一返回 500。
+- **降级行为**：MySQL{% if use_celery %} / Redis 缺席不阻塞启动（health 返回 down、Celery 降级 memory）。本地开发无需强制装依赖，但数据接口在无库时统一返回 500{% else %} 缺席不阻塞启动（health 返回 down）。本地开发无需强制装数据库，数据接口在无库时统一返回 500{% endif %}。
 - **测试环境**：测试用 sqlite 内存库（`tests/conftest.py`），依赖 sqlite 不支持的特性时需显式跳过。
 - **`.env` 提交策略**：`.env` 与 `.env.example` 入库作默认配置；敏感信息（生产密码）放 `.env.production`（不入库）或真实环境变量。
 - **docs/**：`SQLModel定义示例.md` 是建模规范，新表定义先对照该文档。

fastapp_cli-0.3.0/src/fastapp_cli/templates/project/pm2.config.js.j2

@@ -0,0 +1,50 @@
+{% if use_pm2 %}module.exports = {
+  apps: [
+    {
+      name: "{{ project_name }}-server",
+      script: "bash scripts/start.sh",
+      out_file: "./logs/server.log",
+      err_file: "./logs/server.log",
+    },
+{% if use_celery %}
+    {
+      name: "{{ project_name }}-worker",
+      script: "bash scripts/celery_worker.sh",
+      out_file: "./logs/celery.log",
+      err_file: "./logs/celery.log",
+    },
+    {
+      name: "{{ project_name }}-beat",
+      script: "bash scripts/celery_beat.sh",
+      out_file: "./logs/celery_beat.log",
+      err_file: "./logs/celery_beat.log",
+    },
+    {
+      name: "{{ project_name }}-flower",
+      script: "bash scripts/celery_flower.sh",
+      out_file: "./logs/flower.log",
+      err_file: "./logs/flower.log",
+    },
+{% else %}
+    // {
+    //   name: "{{ project_name }}-worker",
+    //   script: "bash scripts/celery_worker.sh",
+    //   out_file: "./logs/celery.log",
+    //   err_file: "./logs/celery.log",
+    // },
+    // {
+    //   name: "{{ project_name }}-beat",
+    //   script: "bash scripts/celery_beat.sh",
+    //   out_file: "./logs/celery_beat.log",
+    //   err_file: "./logs/celery_beat.log",
+    // },
+    // {
+    //   name: "{{ project_name }}-flower",
+    //   script: "bash scripts/celery_flower.sh",
+    //   out_file: "./logs/flower.log",
+    //   err_file: "./logs/flower.log",
+    // }
+{% endif %}
+  ],
+};
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/pyproject.toml.j2

@@ -7,12 +7,12 @@ requires-python = ">=3.12"
 
 dependencies = [
     "alembic>=1.18.4",
-    "celery[redis]>=5.6.3",
-    "fastapi>=0.136.1",
+{% if use_celery %}    "celery[redis]>=5.6.3",
+{% endif %}    "fastapi>=0.136.1",
     "fastapi-filter[sqlalchemy]>=2.0.1",
     "fastapi-pagination>=0.15.13",
-    "flower>=2.0.1",
-    "httpx>=0.28.1",
+{% if use_celery %}    "flower>=2.0.1",
+{% endif %}    "httpx>=0.28.1",
     "loguru>=0.7.3",
     "pydantic>=2.13.3",
     "pydantic-settings>=2.14.0",
@@ -180,9 +180,9 @@ exclude = [
 # 说明：这些库通常没有官方 type stubs，忽略可以避免 "Cannot find implementation" 报错
 [[tool.mypy.overrides]]
 module = [
-    "celery.*",
+{% if use_celery %}    "celery.*",
     "flower.*",
-    "sqlmodel.*",       # SQLModel 的类型推断对 mypy 不友好，建议忽略
+{% endif %}    "sqlmodel.*",       # SQLModel 的类型推断对 mypy 不友好，建议忽略
 ]
 ignore_missing_imports = true
 

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/scripts/celery_beat.sh.j2

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+{% if use_celery %}#!/usr/bin/env bash
 # 启动 Celery Beat（定时任务调度）
 set -euo pipefail
 
@@ -7,3 +7,4 @@ cd "$(dirname "$0")/.."
 LOG_LEVEL="${LOG_LEVEL:-INFO}"
 
 exec uv run celery -A app.core.celery_app.celery_app beat -l "${LOG_LEVEL}"
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/scripts/celery_flower.sh.j2

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+{% if use_celery %}#!/usr/bin/env bash
 # 启动 Flower（Celery 任务监控面板）
 set -euo pipefail
 
@@ -20,3 +20,4 @@ exec uv run celery -A app.core.celery_app.celery_app flower \
     --port="${PORT}" \
     --loglevel="${LOG_LEVEL}" \
     ${BASIC_AUTH_ARG}
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/scripts/celery_worker.sh.j2

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+{% if use_celery %}#!/usr/bin/env bash
 # 启动 Celery Worker
 set -euo pipefail
 
@@ -13,3 +13,4 @@ exec uv run celery -A app.core.celery_app.celery_app worker \
     -c "${CONCURRENCY}" \
     -l "${LOG_LEVEL}" \
     -n "worker@%h"
+{% endif %}

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/tests/test_create.py

@@ -33,6 +33,7 @@ def test_create_smoke_full_flags(tmp_path: Path, monkeypatch) -> None:
             "--description", "smoke test",
             "--pm2",
             "--docker",
+            "--celery",
             "--no-git",
         ],
     )
@@ -46,7 +47,8 @@ def test_create_smoke_full_flags(tmp_path: Path, monkeypatch) -> None:
         "app/main.py",
         "app/api/v1/endpoints/items.py",
         "tests/conftest.py",
-        "pm2.config.json",
+        "pm2.config.js",
+        "app/core/celery_app.py",
         "Dockerfile",
     ):
         assert (root / rel).exists(), f"缺少 {rel}"
@@ -59,6 +61,26 @@ def test_create_smoke_full_flags(tmp_path: Path, monkeypatch) -> None:
     assert "make dev" in result.output
 
 
+def test_create_default_no_celery(tmp_path: Path, monkeypatch) -> None:
+    """--no-celery（默认）：不生成 celery 文件，pm2 命令被注释."""
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(
+        app,
+        [
+            "create", "demo-server",
+            "--description", "x",
+            "--pm2", "--no-docker", "--no-celery", "--no-git",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+
+    root = tmp_path / "demo-server"
+    assert not (root / "app/core/celery_app.py").exists()
+    assert not (root / "app/tasks/sample_tasks.py").exists()
+    pm2_text = (root / "pm2.config.js").read_text(encoding="utf-8")
+    assert "//   script: \"bash scripts/celery_worker.sh\"" in pm2_text
+
+
 def test_create_existing_dir_rejected(tmp_path: Path, monkeypatch) -> None:
     """目标目录已存在且未指定 --force 时拒绝."""
     monkeypatch.chdir(tmp_path)
@@ -83,18 +105,19 @@ def test_create_invalid_name_rejected(tmp_path: Path, monkeypatch) -> None:
 
 
 def test_create_interactive_flow(tmp_path: Path, monkeypatch) -> None:
-    """零 flag 交互路径：通过输入补全描述 / pm2 / Dockerfile."""
+    """零 flag 交互路径：通过输入补全描述 / pm2 / Dockerfile / celery."""
     monkeypatch.chdir(tmp_path)
-    # 描述输入（回车取默认）、pm2 回答 y、Dockerfile 回答 n
+    # 描述输入（回车取默认）、pm2 回答 y、Dockerfile 回答 n、celery 回答 n（默认）
     result = runner.invoke(
         app,
         ["create", "demo-server", "--no-git"],
-        input="\ny\nn\n",
+        input="\ny\nn\nn\n",
     )
     assert result.exit_code == 0, result.output
     root = tmp_path / "demo-server"
-    assert (root / "pm2.config.json").exists()
+    assert (root / "pm2.config.js").exists()
     assert not (root / "Dockerfile").exists()
+    assert not (root / "app/core/celery_app.py").exists()
 
 
 def test_create_git_init(tmp_path: Path, monkeypatch) -> None:
@@ -104,7 +127,7 @@ def test_create_git_init(tmp_path: Path, monkeypatch) -> None:
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(
         app,
-        ["create", "demo-server", "--description", "x", "--no-pm2", "--no-docker"],
+        ["create", "demo-server", "--description", "x", "--no-pm2", "--no-docker", "--no-celery"],
     )
     assert result.exit_code == 0, result.output
     assert (tmp_path / "demo-server" / ".git").is_dir()

{fastapp_cli-0.2.0 → fastapp_cli-0.3.0}/tests/test_render.py

@@ -15,6 +15,7 @@ BASE_CTX: dict[str, object] = {
     "author_name": "tester",
     "use_pm2": False,
     "use_docker": False,
+    "use_celery": True,
     "year": 2026,
     "fastapp_cli_version": "0.1.0",
 }
@@ -70,7 +71,7 @@ def test_render_project_full(tmp_path: Path) -> None:
         assert (out / rel).exists(), f"缺少 {rel}，实际输出 {len(written)} 个文件"
 
     # 条件文件默认不生成
-    assert not (out / "pm2.config.json").exists()
+    assert not (out / "pm2.config.js").exists()
     assert not (out / "Dockerfile").exists()
 
     # 变量注入
@@ -90,9 +91,52 @@ def test_render_project_conditional_files(tmp_path: Path) -> None:
     out = tmp_path / "proj"
     render_project(out, ctx)
 
-    pm2 = out / "pm2.config.json"
+    pm2 = out / "pm2.config.js"
     dockerfile = out / "Dockerfile"
     assert pm2.exists()
     assert dockerfile.exists()
-    assert "demo-server" in pm2.read_text(encoding="utf-8")
+    pm2_text = pm2.read_text(encoding="utf-8")
+    assert "demo-server" in pm2_text
+    # celery 启用：worker/beat/flower 为生效条目
+    assert "celery_worker.sh" in pm2_text
+    assert "//   name:" not in pm2_text
     assert "python3.12" in dockerfile.read_text(encoding="utf-8")
+
+
+def test_render_project_no_celery(tmp_path: Path) -> None:
+    """use_celery=False：celery 文件不生成，pm2 中对应命令为注释，依赖剔除."""
+    from fastapp_cli.render import render_project
+
+    ctx = dict(BASE_CTX, use_celery=False, use_pm2=True)
+    out = tmp_path / "proj"
+    render_project(out, ctx)
+
+    # celery 相关文件不生成
+    for rel in (
+        "app/core/celery_app.py",
+        "app/tasks/sample_tasks.py",
+        "scripts/celery_worker.sh",
+        "scripts/celery_beat.sh",
+        "scripts/celery_flower.sh",
+    ):
+        assert not (out / rel).exists(), f"{rel} 不应生成"
+
+    # pm2.config.js 中 celery 启动命令被注释
+    pm2_text = (out / "pm2.config.js").read_text(encoding="utf-8")
+    assert "//   name:" in pm2_text
+    assert "//   script: \"bash scripts/celery_worker.sh\"" in pm2_text
+    # server 条目仍生效
+    assert 'name: "demo-server-server"' in pm2_text
+
+    # pyproject 无 celery/flower 依赖
+    pyproject = (out / "pyproject.toml").read_text(encoding="utf-8")
+    assert "celery" not in pyproject
+    assert "flower" not in pyproject
+
+    # main.py 无 celery 探测
+    main_text = (out / "app" / "main.py").read_text(encoding="utf-8")
+    assert "celery" not in main_text
+    assert "_probe_redis" not in main_text
+
+    # DEBUG 打印已注入
+    assert "settings.DEBUG" in main_text

fastapp_cli-0.2.0/src/fastapp_cli/templates/project/pm2.config.json.j2

@@ -1,47 +0,0 @@
-{% if use_pm2 %}
-{
-  "apps": [
-    {
-      "name": "{{ project_name }}-server",
-      "script": "bash scripts/start.sh",
-      "output": "./logs/server.log",
-      "error": "./logs/server-error.log",
-      "env": {
-        "HOST": "0.0.0.0",
-        "PORT": "8000",
-        "APP_ENV": "production",
-        "WORKERS": "1"
-      }
-    },
-    {
-      "name": "{{ project_name }}-worker",
-      "script": "bash scripts/celery_worker.sh",
-      "output": "./logs/celery.log",
-      "error": "./logs/celery-error.log",
-      "env": {
-        "CONCURRENCY": "4",
-        "QUEUE": "default",
-        "LOG_LEVEL": "INFO"
-      }
-    },
-    {
-      "name": "{{ project_name }}-beat",
-      "script": "bash scripts/celery_beat.sh",
-      "log_file": "./logs/celery_beat.log",
-      "env": {
-        "LOG_LEVEL": "INFO"
-      }
-    },
-    {
-      "name": "{{ project_name }}-flower",
-      "script": "bash scripts/celery_flower.sh",
-      "log_file": "./logs/flower.log",
-      "env": {
-        "FLOWER_HOST": "0.0.0.0",
-        "FLOWER_PORT": "5555",
-        "LOG_LEVEL": "INFO"
-      }
-    }
-  ]
-}
-{% endif %}