fastapp-cli 0.1.0__py3-none-any.whl

fastapp_cli/templates/project/app/tasks/sample_tasks.py.j2

@@ -0,0 +1,28 @@
+"""Celery 示例任务."""
+
+from __future__ import annotations
+
+import time
+
+from loguru import logger
+
+from app.core.celery_app import celery_app
+
+
+@celery_app.task(
+    name="app.tasks.sample_tasks.sample_task",
+    bind=True,
+    autoretry_for=(Exception,),
+    retry_kwargs={"max_retries": 3, "countdown": 10},
+)
+def sample_task(self, name: str = "world") -> dict:
+    """示例任务：模拟耗时操作并返回结果.
+
+    测试方式（需 redis 可达）::
+
+        uv run celery -A app.core.celery_app.celery_app worker -l INFO
+        uv run python -c "from app.tasks.sample_tasks import sample_task; print(sample_task.delay('fastapp').id)"
+    """
+    logger.info("[task={}] sample_task running, name={}", self.request.id, name)
+    time.sleep(1)
+    return {"message": f"hello, {name}"}

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

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

fastapp_cli/templates/project/docs/SQLModel/345/256/232/344/271/211/347/244/272/344/276/213.md

@@ -0,0 +1,400 @@
+# SQLModel 定义模型的经典示例
+
+## 1. 基础模型
+
+```python
+from sqlmodel import SQLModel, Field
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+```
+
+**要点**：
+
+- `table=True` 才会建表；没有则只是 Pydantic 模型
+- `id: int | None` + `default=None` 是自增主键的标准写法
+
+---
+
+## 2. 字段约束与索引
+
+```python
+from sqlmodel import SQLModel, Field
+
+
+class User(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    username: str = Field(min_length=3, max_length=32, unique=True, index=True)
+    email: str = Field(unique=True, index=True)
+    age: int = Field(ge=0, le=150)
+    bio: str | None = Field(default=None, max_length=500)
+    is_active: bool = Field(default=True)
+```
+
+---
+
+## 3. 时间戳与默认值
+
+```python
+from datetime import datetime, timezone
+from sqlalchemy import DateTime, func
+from sqlmodel import SQLModel, Field
+
+
+def utcnow():
+    return datetime.now(tz=timezone.utc)
+
+
+class Article(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    title: str
+    # Python 端默认值
+    created_at: datetime = Field(default_factory=utcnow)
+    # 数据库端默认值 + 自动更新
+    updated_at: datetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={"onupdate": func.now()},
+    )
+```
+
+---
+
+## 4. 枚举字段
+
+```python
+from enum import Enum
+from sqlmodel import SQLModel, Field
+
+
+class Status(str, Enum):
+    DRAFT = "draft"
+    PUBLISHED = "published"
+    ARCHIVED = "archived"
+
+
+class Post(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    title: str
+    status: Status = Field(default=Status.DRAFT, index=True)
+```
+
+---
+
+## 5. 一对多关系
+
+```python
+from sqlmodel import SQLModel, Field, Relationship
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True, unique=True)
+
+    heroes: list["Hero"] = Relationship(back_populates="team")
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    team_id: int | None = Field(default=None, foreign_key="team.id", index=True)
+
+    team: Team | None = Relationship(back_populates="heroes")
+```
+
+**使用**：
+
+```python
+team = Team(name="Avengers", heroes=[Hero(name="Iron Man")])
+session.add(team)
+session.commit()
+```
+
+---
+
+## 6. 多对多关系（需关联表）
+
+```python
+from sqlmodel import SQLModel, Field, Relationship
+
+
+class HeroTeamLink(SQLModel, table=True):
+    hero_id: int | None = Field(default=None, foreign_key="hero.id", primary_key=True)
+    team_id: int | None = Field(default=None, foreign_key="team.id", primary_key=True)
+    # 可加额外字段
+    joined_at: datetime = Field(default_factory=utcnow)
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    heroes: list["Hero"] = Relationship(back_populates="teams", link_model=HeroTeamLink)
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    teams: list[Team] = Relationship(back_populates="heroes", link_model=HeroTeamLink)
+```
+
+---
+
+## 7. Mixin 组合（推荐项目结构）
+
+```python
+from datetime import datetime
+from sqlalchemy import DateTime, func
+from sqlmodel import SQLModel, Field
+
+
+class IDMixin(SQLModel):
+    id: int | None = Field(default=None, primary_key=True, index=True)
+
+
+class TimestampMixin(SQLModel):
+    created_at: datetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={"server_default": func.now(), "nullable": False},
+    )
+    updated_at: datetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={
+            "server_default": func.now(),
+            "onupdate": func.now(),
+            "nullable": False,
+        },
+    )
+
+
+class SoftDeleteMixin(SQLModel):
+    deleted_at: datetime | None = Field(default=None, index=True)
+
+
+# 组合使用
+class User(IDMixin, TimestampMixin, SoftDeleteMixin, table=True):
+    username: str = Field(unique=True, index=True)
+    email: str
+```
+
+---
+
+## 8. 读写模型分离（API 最佳实践）
+
+```python
+# 共享基类（不建表）
+class UserBase(SQLModel):
+    username: str = Field(index=True)
+    email: str
+    age: int | None = None
+
+
+# 数据库表
+class User(UserBase, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    hashed_password: str  # 数据库独有
+
+
+# 创建请求（API 输入）
+class UserCreate(UserBase):
+    password: str  # 明文密码，仅创建时
+
+
+# 响应（API 输出，不含敏感字段）
+class UserRead(UserBase):
+    id: int
+
+
+# 更新（字段全部可选）
+class UserUpdate(SQLModel):
+    username: str | None = None
+    email: str | None = None
+    age: int | None = None
+    password: str | None = None
+```
+
+**FastAPI 中使用**：
+
+```python
+@app.post("/users/", response_model=UserRead)
+def create_user(user: UserCreate, session: Session = Depends(get_session)):
+    db_user = User.model_validate(user, update={"hashed_password": hash(user.password)})
+    session.add(db_user)
+    session.commit()
+    session.refresh(db_user)
+    return db_user
+```
+
+---
+
+## 9. 复合索引与表参数
+
+```python
+from sqlalchemy import Index, UniqueConstraint
+from sqlmodel import SQLModel, Field
+
+
+class OrderItem(SQLModel, table=True):
+    __tablename__ = "order_items"
+    __table_args__ = (
+        UniqueConstraint("order_id", "product_id", name="uq_order_product"),
+        Index("ix_order_product", "order_id", "product_id"),
+    )
+
+    id: int | None = Field(default=None, primary_key=True)
+    order_id: int = Field(foreign_key="orders.id")
+    product_id: int = Field(foreign_key="products.id")
+    quantity: int
+```
+
+---
+
+## 10. JSON 字段
+
+```python
+from sqlalchemy import JSON
+from sqlmodel import SQLModel, Field
+
+
+class Config(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    # 存储任意 JSON 数据
+    data: dict = Field(default_factory=dict, sa_type=JSON)
+    tags: list[str] = Field(default_factory=list, sa_type=JSON)
+```
+
+---
+
+## 11. UUID 主键
+
+```python
+from uuid import UUID, uuid4
+from sqlmodel import SQLModel, Field
+
+
+class Session(SQLModel, table=True):
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    user_id: int = Field(foreign_key="user.id")
+    token: str = Field(unique=True, index=True)
+```
+
+---
+
+## 12. 自引用关系（树形结构）
+
+```python
+from sqlmodel import SQLModel, Field, Relationship
+
+
+class Category(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    parent_id: int | None = Field(default=None, foreign_key="category.id")
+
+    parent: "Category | None" = Relationship(
+        back_populates="children",
+        sa_relationship_kwargs={"remote_side": "Category.id"},
+    )
+    children: list["Category"] = Relationship(back_populates="parent")
+```
+
+## 全局配置 + 自定义类型（项目统一风格）
+
+```python
+from datetime import datetime
+from typing import Annotated
+from pydantic import PlainSerializer
+from sqlalchemy import DateTime, func
+from sqlmodel import SQLModel, Field
+
+# 定义一个可复用的序列化类型
+FormattedDatetime = Annotated[
+    datetime,
+    PlainSerializer(
+        lambda v: v.strftime("%Y-%m-%d %H:%M:%S") if v else None,
+        return_type=str,
+        when_used="json",  # 仅 JSON 序列化时生效；数据库仍存 datetime
+    ),
+]
+
+
+class TimestampMixin(SQLModel):
+    created_at: FormattedDatetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={"server_default": func.now(), "nullable": False},
+    )
+    updated_at: FormattedDatetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={
+            "server_default": func.now(),
+            "onupdate": func.now(),
+            "nullable": False,
+        },
+    )
+```
+
+**优点**：
+
+- 类型可复用，多个字段共用一条规则
+- `when_used="json"` 保证只影响 JSON 输出，不影响数据库存取
+
+
+## 使用 Pydantic 模型做 JSON 结构校验
+
+```python
+from pydantic import BaseModel
+from sqlalchemy import JSON
+from sqlmodel import SQLModel, Field
+
+
+class Author(BaseModel):
+    name: str
+    email: str
+    role: str = "writer"
+
+
+class ArticleMeta(BaseModel):
+    seo_title: str | None = None
+    cover: str | None = None
+    reading_time: int = 0
+
+
+class Article(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    title: str
+
+    # 用 Pydantic 模型作为 JSON 字段类型，自动校验结构
+    meta: ArticleMeta = Field(
+        default_factory=ArticleMeta,
+        sa_type=JSON,
+    )
+    authors: list[Author] = Field(
+        default_factory=list,
+        sa_type=JSON,
+    )
+```
+
+---
+
+## 常用小结
+
+| 场景         | 关键参数                                               |
+|------------|----------------------------------------------------|
+| 自增主键       | `Field(default=None, primary_key=True)`            |
+| 索引         | `Field(index=True)`                                |
+| 唯一         | `Field(unique=True)`                               |
+| 外键         | `Field(foreign_key="table.id")`                    |
+| Python 默认值 | `default=` / `default_factory=`                    |
+| 数据库默认值     | `sa_column_kwargs={"server_default": ...}`         |
+| 自动更新       | `sa_column_kwargs={"onupdate": func.now()}`        |
+| 自定义列类型     | `sa_type=...`                                      |
+| 完整列控制      | `sa_column=Column(...)`                            |
+| 关系         | `Relationship(back_populates=..., link_model=...)` |

fastapp_cli/templates/project/pm2.config.json.j2

@@ -0,0 +1,47 @@
+{% 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 %}

fastapp_cli/templates/project/pyproject.toml.j2

@@ -0,0 +1,195 @@
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "{{ project_description }}"
+readme = "README.md"
+requires-python = ">=3.12"
+
+dependencies = [
+    "alembic>=1.18.4",
+    "celery[redis]>=5.6.3",
+    "fastapi>=0.136.1",
+    "fastapi-filter[sqlalchemy]>=2.0.1",
+    "fastapi-pagination>=0.15.13",
+    "flower>=2.0.1",
+    "httpx>=0.28.1",
+    "loguru>=0.7.3",
+    "pydantic>=2.13.3",
+    "pydantic-settings>=2.14.0",
+    "pymysql>=1.1.2",
+    "sqlalchemy>=2.0.49",
+    "sqlmodel>=0.0.38",
+    "tenacity>=9.1.4", # retrying library
+    "uvicorn[standard]>=0.46.0",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11.0",
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.6.0",
+]
+
+# -----------------------------------------------------------------------------
+# pytest 测试配置
+# -----------------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+# 使测试可从项目根导入 app 包（项目未作为发行包安装时）
+pythonpath = ["."]
+asyncio_mode = "auto"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--tb=short",
+]
+markers = [
+    "unit: unit tests",
+    "integration: integration tests",
+    "slow: slow tests",
+]
+
+# -----------------------------------------------------------------------------
+# uv 镜像源：默认使用 pypi.org；内网用户取消下方注释即可启用腾讯镜像
+# -----------------------------------------------------------------------------
+# [[tool.uv.index]]
+# # 腾讯镜像源，同步自pypi
+# url = "https://mirrors.tencent.com/pypi/simple"
+# name = "mirrors_pypi"
+# default = true
+#
+# [[tool.uv.index]]
+# # 腾讯镜像源，同步自pypi
+# url = "https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple"
+# name = "tencent_pypi"
+
+# -----------------------------------------------------------------------------
+# Ruff 配置（linter + formatter，替代 flake8 / isort / black）
+# 参考：https://docs.astral.sh/ruff/
+# -----------------------------------------------------------------------------
+[tool.ruff]
+# 每行最多 120 字符
+line-length = 120
+# 目标 Python 版本（与 requires-python 对齐）
+target-version = "py312"
+# 自动遵循 .gitignore 配置，无需重复配置排除项
+respect-gitignore = true
+extend-exclude = [
+    ".venv",
+    "venv",
+    "build",
+    "dist",
+    "alembic/versions",
+    "__pycache__",
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+]
+# 每个文件都应该可被修复
+fix = true
+show-fixes = true
+
+[tool.ruff.lint]
+select = [
+    # ========== 必选核心规则（所有项目必须开启，零容忍错误检测） ==========
+    "F", # Pyflakes：检测未定义变量、未使用导入、无效语法等致命运行时错误
+    "E", # pycodestyle(Error)：PEP8语法错误检测
+    "W", # pycodestyle(Warning)：PEP8规范警告
+    "I", # isort：导入排序与分组规范，替代独立isort工具
+    # ========== 推荐质量规则（强烈建议开启，提升代码健壮性） ==========
+    "B", # flake8-bugbear：捕获基础规则遗漏的常见bug、反模式和陷阱
+    "UP", # pyupgrade：自动升级Python语法到目标版本，实现代码现代化
+    "SIM", # 代码简化：检测复杂逻辑、冗余判断，提升可读性
+    # ========== 可选增强规则（按需开启，团队规范对齐） ==========
+    "N", # pep8-naming：强制PEP8命名规范，类/函数/变量命名约束
+    "TID", # 导入整洁度：禁止循环导入、无用导入别名等
+    "FAST", # FastAPI特定规则
+]
+ignore = [
+    "E501", # 行长度超限：完全由Ruff Format控制，lint无需重复检测
+]
+# 允许自动修复的规则
+fixable = ["ALL"]
+unfixable = []
+
+
+[tool.ruff.lint.per-file-ignores]
+# 测试目录放宽规则
+"tests/**/*.py" = ["E", "F", "I", "N", "UP"]
+# alembic 迁移脚本放宽规则
+"alembic/**/*.py" = ["E", "F", "I", "N", "UP"]
+
+
+[tool.ruff.format]
+quote-style = "double"  # 使用双引号（与 black 行为一致）
+indent-style = "space"  # 使用空格缩进
+skip-magic-trailing-comma = false  # 保留末尾逗号
+
+# -----------------------------------------------------------------------------
+# mypy 配置（仅开启最核心必要的类型检查规则）
+# 参考：https://mypy.readthedocs.io/en/stable/config_file.html
+# -----------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.12"
+
+# ---------- 核心必要检查（捕获真实 bug，不做强约束） ----------
+# 警告未使用的 # type: ignore 注释，保持注释整洁
+warn_unused_ignores = true
+# 警告函数返回了 Any（可能意味着类型推断失效）
+warn_return_any = false        # 宽松：第三方库返回 Any 很常见，避免噪音
+# 警告永远不会执行到的代码
+warn_unreachable = true
+# 警告多余的类型转换
+warn_redundant_casts = true
+# 禁止隐式的 Optional（如 def f(x: int = None) 应显式写 Optional[int]）
+no_implicit_optional = true
+# 类型不严格，但保证基础一致性
+strict_equality = true
+
+# ---------- 宽松策略：不要求所有函数都必须标注类型 ----------
+# 不强制要求所有函数都有类型注解（核心：避免过度约束）
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true       # 但对无注解的函数体也做一次检查，不放过隐藏 bug
+disallow_untyped_decorators = false
+
+# ---------- 报错展示优化 ----------
+show_error_codes = true
+show_column_numbers = true
+pretty = true
+
+# ---------- 排除目录 ----------
+exclude = [
+    "^\\.venv/",
+    "^venv/",
+    "^build/",
+    "^dist/",
+    "^alembic/versions/",
+    "^__pycache__/",
+]
+
+# ---------- 针对缺少类型存根的第三方库，忽略导入错误 ----------
+# 说明：这些库通常没有官方 type stubs，忽略可以避免 "Cannot find implementation" 报错
+[[tool.mypy.overrides]]
+module = [
+    "celery.*",
+    "flower.*",
+    "sqlmodel.*",       # SQLModel 的类型推断对 mypy 不友好，建议忽略
+]
+ignore_missing_imports = true
+
+# ---------- 测试和迁移脚本：进一步放宽 ----------
+[[tool.mypy.overrides]]
+module = [
+    "tests.*",
+    "alembic.*",
+]
+ignore_errors = true

fastapp_cli/templates/project/scripts/celery_beat.sh.j2

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

fastapp_cli/templates/project/scripts/celery_flower.sh.j2

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# 启动 Flower（Celery 任务监控面板）
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+HOST="${FLOWER_HOST:-0.0.0.0}"
+PORT="${FLOWER_PORT:-5555}"
+LOG_LEVEL="${LOG_LEVEL:-INFO}"
+
+# 基本认证，格式：user:password，多个用逗号分隔
+# 可在 .env 中设置 FLOWER_BASIC_AUTH=admin:admin
+BASIC_AUTH_ARG=""
+if [ -n "${FLOWER_BASIC_AUTH:-}" ]; then
+    BASIC_AUTH_ARG="--basic-auth=${FLOWER_BASIC_AUTH}"
+fi
+
+exec uv run celery -A app.core.celery_app.celery_app flower \
+    --address="${HOST}" \
+    --port="${PORT}" \
+    --loglevel="${LOG_LEVEL}" \
+    ${BASIC_AUTH_ARG}