fastapp-cli 0.1.0__py3-none-any.whl

fastapp_cli/templates/project/app/crud/base.py.j2

@@ -0,0 +1,229 @@
+"""CRUD 泛型基类."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, cast
+
+from fastapi_filter.contrib.sqlalchemy import Filter
+from fastapi_pagination.ext.sqlmodel import paginate
+from pydantic import BaseModel
+from sqlmodel import Session, SQLModel, func, inspect, select
+from sqlmodel.sql.expression import Select, SelectOfScalar
+
+from app.core.exceptions import NotFoundError
+from app.schemas.common import PageResponse
+
+
+class CRUDBase[ModelType: SQLModel]:
+    """CRUD 基类，提供通用的增删改查方法.
+
+    所有子类只需传入对应的 SQLModel 类，即可获得基础能力.
+    复杂的查询逻辑请在子类中扩展.
+    """
+
+    def __init__(self, model: type[ModelType]) -> None:
+        """初始化.
+
+        :param model: SQLModel 实体类
+        """
+        self.model = model
+
+    def get(self, db: Session, obj_id: Any) -> ModelType | None:
+        """按主键查询单个对象."""
+        return db.get(self.model, obj_id)
+
+    def get_or_404(self, db: Session, obj_id: Any) -> ModelType:
+        """按主键查询单个对象，若不存在则抛出 404 异常."""
+        obj = self.get(db, obj_id)
+        if not obj:
+            raise NotFoundError()
+        return obj
+
+    def get_by_field(self, db: Session, field: str, value: Any) -> ModelType | None:
+        """按字段查询单个对象."""
+        if not hasattr(self.model, field):
+            raise ValueError(f"{self.model.__name__} 不存在字段 {field}")
+        statement = select(self.model).where(getattr(self.model, field) == value)
+        return db.exec(statement).first()
+
+    def get_page_multi(
+        self,
+        db: Session,
+        *,
+        filter_params: Filter | None = None,
+    ) -> PageResponse[Any]:
+        """分页查询列表."""
+        statement = select(self.model)
+        if filter_params is not None:
+            statement = filter_params.sort(filter_params.filter(statement))
+        return paginate(db, statement)  # type: ignore[arg-type]
+
+    def get_multi(
+        self,
+        db: Session,
+        *,
+        filter_params: Filter | None = None,
+    ) -> Sequence[ModelType]:
+        """查询列表."""
+        statement = select(self.model)
+        if filter_params is not None:
+            statement = filter_params.sort(filter_params.filter(statement))
+        return db.exec(statement).all()
+
+    def count(self, db: Session, query: Select | SelectOfScalar | None = None) -> int:
+        """返回记录总数."""
+        if query is not None:
+            statement = query.with_only_columns(func.count()).select_from(self.model).order_by(None).offset(None).limit(None)
+        else:
+            statement = select(func.count()).select_from(self.model)
+        return db.exec(cast(SelectOfScalar, statement)).one()
+
+    def create(self, db: Session, *, obj_in: BaseModel | dict[str, Any]) -> ModelType:
+        """创建记录."""
+        data = obj_in if isinstance(obj_in, dict) else obj_in.model_dump()
+        db_obj = self.model(**data)
+        db.add(db_obj)
+        db.commit()
+        db.refresh(db_obj)
+        return db_obj
+
+    def create_multi(self, db: Session, *, objs_in: list[BaseModel | dict[str, Any]]) -> list[ModelType]:
+        """批量创建记录."""
+        items = [obj_in if isinstance(obj_in, dict) else obj_in.model_dump() for obj_in in objs_in]
+        db_objs = [self.model(**item) for item in items]
+        db.add_all(db_objs)
+        db.commit()
+        for db_obj in db_objs:
+            db.refresh(db_obj)
+        return db_objs
+
+    def update(
+        self,
+        db: Session,
+        *,
+        db_obj: ModelType,
+        obj_in: BaseModel | dict[str, Any],
+    ) -> ModelType:
+        """更新记录."""
+        update_data = obj_in if isinstance(obj_in, dict) else obj_in.model_dump(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(db_obj, field, value)
+        db.add(db_obj)
+        db.commit()
+        db.refresh(db_obj)
+        return db_obj
+
+    def _get_by_unique_fields(
+        self,
+        db: Session,
+        data: dict[str, Any],
+        unique_fields: Sequence[str],
+    ) -> ModelType | None:
+        """按指定的唯一字段组合查询单个对象."""
+        if not unique_fields:
+            raise ValueError("unique_fields 不能为空")
+        statement = select(self.model)
+        for field in unique_fields:
+            if not hasattr(self.model, field):
+                raise ValueError(f"{self.model.__name__} 不存在字段 {field}")
+            if field not in data:
+                raise ValueError(f"obj_in 中缺少唯一字段 {field}")
+            statement = statement.where(getattr(self.model, field) == data[field])
+        return db.exec(statement).first()
+
+    def _resolve_unique_fields(
+        self,
+        unique_fields: str | Sequence[str] | None,
+    ) -> list[str]:
+        """规范化 unique_fields 参数，未指定时使用模型主键."""
+        if unique_fields is None:
+            primary_keys = cast(Sequence[Any], inspect(self.model).primary_key)  # type: ignore[union-attr]
+            return [pk.name for pk in primary_keys]
+        if isinstance(unique_fields, str):
+            return [unique_fields]
+        return list(unique_fields)
+
+    def create_or_update(
+        self,
+        db: Session,
+        *,
+        obj_in: BaseModel | dict[str, Any],
+        unique_fields: str | Sequence[str] | None = None,
+    ) -> ModelType:
+        """根据唯一字段创建或更新记录.
+
+        :param db: 数据库会话
+        :param obj_in: 入参，BaseModel 或 dict
+        :param unique_fields: 唯一字段名或字段名列表，未指定时使用模型主键
+        :return: 创建或更新后的模型实例
+        """
+        fields = self._resolve_unique_fields(unique_fields)
+        data = obj_in if isinstance(obj_in, dict) else obj_in.model_dump()
+        db_obj = self._get_by_unique_fields(db, data, fields)
+        if db_obj is None:
+            db_obj = self.model(**data)
+            db.add(db_obj)
+        else:
+            for field, value in data.items():
+                setattr(db_obj, field, value)
+            db.add(db_obj)
+        db.commit()
+        db.refresh(db_obj)
+        return db_obj
+
+    def create_or_update_multi(
+        self,
+        db: Session,
+        *,
+        objs_in: list[BaseModel | dict[str, Any]],
+        unique_fields: str | Sequence[str] | None = None,
+    ) -> list[ModelType]:
+        """批量根据唯一字段创建或更新记录.
+
+        在同一事务中提交，减少数据库往返.
+
+        :param db: 数据库会话
+        :param objs_in: 入参列表，BaseModel 或 dict
+        :param unique_fields: 唯一字段名或字段名列表，未指定时使用模型主键
+        :return: 创建或更新后的模型实例列表
+        """
+        fields = self._resolve_unique_fields(unique_fields)
+        db_objs: list[ModelType] = []
+        for obj_in in objs_in:
+            data = obj_in if isinstance(obj_in, dict) else obj_in.model_dump()
+            db_obj = self._get_by_unique_fields(db, data, fields)
+            if db_obj is None:
+                db_obj = self.model(**data)
+            else:
+                for field, value in data.items():
+                    setattr(db_obj, field, value)
+            db.add(db_obj)
+            db_objs.append(db_obj)
+        db.commit()
+        for db_obj in db_objs:
+            db.refresh(db_obj)
+        return db_objs
+
+    def remove(self, db: Session, *, obj_id: int) -> ModelType:
+        """按主键删除记录."""
+        obj = self.get_or_404(db, obj_id)
+        db.delete(obj)
+        db.commit()
+        return obj
+
+    def remove_multi(self, db: Session, *, obj_ids: list[Any]) -> list[ModelType]:
+        """批量删除记录."""
+        primary_key = cast(Any, list(inspect(self.model).primary_key)[0])  # type: ignore[union-attr]
+        statement = select(self.model).where(
+            primary_key.in_(obj_ids)
+        )
+        objs = db.exec(statement).all()
+        for obj in objs:
+            db.delete(obj)
+        db.commit()
+        return list(objs)
+
+    def exists(self, db: Session, *, obj_id: Any) -> bool:
+        """判断记录是否存在."""
+        return self.get(db, obj_id) is not None

fastapp_cli/templates/project/app/crud/item.py.j2

@@ -0,0 +1,10 @@
+"""Item CRUD."""
+
+from __future__ import annotations
+
+from app.crud.base import CRUDBase
+from app.models.item import Item
+
+
+class CRUDItem(CRUDBase[Item]):
+    pass

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

@@ -0,0 +1,118 @@
+"""FastAPI 应用入口."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi_pagination import add_pagination
+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
+from app.core.database import engine
+from app.core.exceptions import register_exception_handlers
+from app.core.logging import setup_logging
+from app.core.middleware import TraceIDMiddleware
+
+
+def _probe_database() -> None:
+    """启动时探测数据库连通性（带超时），缺席降级不阻塞启动."""
+    try:
+        with engine.connect() as conn:
+            conn.execute(text("SELECT 1"))
+        logger.info("数据库连接正常: {}", settings.DATABASE_URI)
+    except Exception as exc:  # pylint: disable=broad-except
+        logger.warning("数据库未就绪，数据接口将返回 500，请配置 .env: {}", exc)
+
+
+def _probe_redis() -> None:
+    """启动时探测 redis（带超时），不可达时 Celery 自动降级为 memory broker."""
+    broker_url = settings.CELERY_BROKER_URL
+    if broker_url.startswith("memory"):
+        logger.info("Celery broker 已配置为 memory://，跳过 redis 探测")
+        return
+    try:
+        import redis
+
+        client = redis.Redis.from_url(
+            broker_url,
+            socket_connect_timeout=1,
+            socket_timeout=1,
+        )
+        client.ping()
+        client.close()
+        logger.info("redis 连接正常: {}", broker_url)
+    except Exception as exc:  # pylint: disable=broad-except
+        degrade_to_memory(celery_app)
+        logger.warning("redis 未就绪，Celery 已降级为 memory broker: {}", exc)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    """应用生命周期.
+
+    - 启动：初始化日志、探测数据库 / redis（缺席降级，不阻塞启动）
+    - 关闭：优雅释放资源
+    """
+    setup_logging()
+    logger.info("{} starting | env={} | debug={}", settings.APP_NAME, settings.APP_ENV, settings.DEBUG)
+    _probe_database()
+    _probe_redis()
+
+    yield
+
+    logger.info("{} stopped", settings.APP_NAME)
+
+
+def create_app() -> FastAPI:
+    """工厂函数：创建 FastAPI 应用实例."""
+    app_ = FastAPI(
+        title=settings.APP_NAME,
+        # 注意：固定 False。DEBUG 环境变量仅控制日志级别与 SQL echo；
+        # 若传 True，Starlette 会绕过统一异常处理器返回原始堆栈，违反统一响应规范
+        debug=False,
+        version="0.1.0",
+        openapi_url=f"{settings.API_V1_PREFIX}/openapi.json",
+        docs_url=f"{settings.API_V1_PREFIX}/docs",
+        redoc_url=f"{settings.API_V1_PREFIX}/redoc",
+        lifespan=lifespan,
+    )
+
+    app_.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.ALLOWED_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # 注意：TraceID 中间件需在 CORS 之后添加，以保证其处于最外层（Starlette 中间件后注册先执行），
+    # 从而为所有后续逻辑提供 trace_id 上下文
+    app_.add_middleware(TraceIDMiddleware)
+
+    register_exception_handlers(app_)
+    app_.include_router(api_router, prefix=settings.API_V1_PREFIX)
+
+    # 添加分页插件
+    add_pagination(app_)
+
+    return app_
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "app.main:app",
+        host=settings.HOST,
+        port=settings.PORT,
+        reload=settings.DEBUG,
+    )

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

@@ -0,0 +1,10 @@
+"""SQLModel 数据库模型."""
+
+from __future__ import annotations
+
+from app.models.item import Item
+
+# 新增表一定要在这里添加
+__all__ = [
+    "Item",
+]

fastapp_cli/templates/project/app/models/base.py.j2

@@ -0,0 +1,59 @@
+"""SQLModel 基类，定义公共字段."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import PlainSerializer
+from sqlalchemy import DateTime, func
+from sqlmodel import Field, SQLModel
+
+# 定义一个可复用的序列化类型
+FormattedDatetime = Annotated[
+    datetime | None,
+    PlainSerializer(
+        lambda v: v.strftime("%Y-%m-%d %H:%M:%S") if v else None,
+        return_type=str,
+        when_used="json",  # 仅 JSON 序列化时生效；数据库仍存 datetime
+    ),
+]
+
+
+def utcnow() -> datetime:
+    """获取当前本地时间."""
+    return datetime.now()
+
+
+class TimestampMixin(SQLModel):
+    """公共时间戳字段.
+
+    - create_time: 创建时间，数据库自动生成
+    - update_time: 更新时间，每次更新自动刷新
+
+    这里使用 ``sa_type`` + ``sa_column_kwargs`` 的方式声明列参数，
+    每个继承此 Mixin 的表都会生成独立的 Column 实例，避免 SQLAlchemy
+    `Column already assigned to Table` 报错. PyCharm 的误报用 # type: ignore
+    """
+
+    create_time: FormattedDatetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),  # type: ignore
+        sa_column_kwargs={
+            "server_default": func.now(),
+        },
+    )
+    update_time: FormattedDatetime = Field(
+        default_factory=utcnow,
+        sa_type=DateTime(timezone=True),  # type: ignore
+        sa_column_kwargs={
+            "server_default": func.now(),
+            "onupdate": func.now(),
+        },
+    )
+
+
+class IDMixin(SQLModel):
+    """主键字段."""
+
+    id: int = Field(..., primary_key=True, index=True)

fastapp_cli/templates/project/app/models/item.py.j2

@@ -0,0 +1,22 @@
+"""Item 模型（demo 业务域，可替换为实际业务模型）."""
+
+from __future__ import annotations
+
+from sqlmodel import Field
+
+from app.models.base import IDMixin, TimestampMixin
+
+
+class ItemBase(TimestampMixin):
+    """Item 公共字段."""
+
+    title: str = Field(max_length=128, description="标题")
+    description: str = Field(default="", max_length=2000, description="描述")
+    price: float = Field(default=0, description="价格")
+    is_active: bool = Field(default=True, description="是否上架")
+
+
+class Item(IDMixin, ItemBase, table=True):
+    """Item 表 ORM 模型."""
+
+    __tablename__ = "t_item"

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

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

fastapp_cli/templates/project/app/schemas/common.py.j2

@@ -0,0 +1,81 @@
+"""通用 Schema - 分页、统一响应."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Self
+
+from fastapi import Query
+from fastapi_pagination import Params
+from fastapi_pagination.bases import AbstractPage, AbstractParams
+from pydantic import BaseModel, model_validator
+
+from app.core.context_var import get_trace_id
+
+
+class Response[T](BaseModel):
+    """统一响应结构.
+
+    所有接口统一返回该结构，包含业务状态码、消息、数据三个字段：
+
+    :param code: 业务状态码，0 表示成功，其他值表示业务异常
+    :param message: 描述信息
+    :param data: 业务数据载荷
+    :param trace_id: 调用链 ID，未显式指定时会自动从请求上下文注入
+    """
+
+    code: int = 0
+    message: str | None = "ok"
+    data: T | None = None
+    trace_id: str | None = None
+
+    @model_validator(mode="after")
+    def _inject_trace_id(self) -> Self:
+        """构造完成后自动注入当前请求上下文中的 trace_id（若未显式提供）."""
+        if self.trace_id is None:
+            self.trace_id = get_trace_id()
+        return self
+
+
+class PageParams(Params):
+    """分页查询参数."""
+
+    page: int = Query(1, ge=1, description="页码")
+    size: int = Query(10, ge=1, le=1000, alias="page_size", description="每页条数")
+
+
+class PageResult[T](BaseModel):
+    """分页返回结构."""
+
+    total: int
+    page: int
+    page_size: int
+    content: Sequence[T]
+
+
+class PageResponse[T](Response[PageResult[T]], AbstractPage[T]):
+    """统一分页响应结构."""
+
+    __params_type__ = PageParams
+
+    @classmethod
+    def create(
+        cls,
+        items: Sequence[T],
+        params: AbstractParams,
+        *,
+        total: int | None = None,
+        **kwargs: Any,
+    ) -> Self:
+        if not isinstance(params, PageParams):
+            raise TypeError(f"params must be an instance of PageParams, got {type(params).__name__}")
+        if total is None:
+            raise ValueError("total is required for PageResponse.create")
+        return cls(
+            data=PageResult(
+                total=total,
+                page=params.page,
+                page_size=params.size,
+                content=items,
+            )
+        )

fastapp_cli/templates/project/app/schemas/item.py.j2

@@ -0,0 +1,35 @@
+"""Item Schema：入参 / 出参 / 过滤器."""
+
+from __future__ import annotations
+
+from fastapi_filter.contrib.sqlalchemy import Filter
+from pydantic import Field
+
+from app.models.item import Item, ItemBase
+
+
+class ItemCreate(ItemBase):
+    """创建 Item 入参."""
+
+
+class ItemUpdate(ItemBase):
+    """更新 Item 入参（exclude_unset 语义下仅更新显式传入的字段）."""
+
+
+class ItemRead(ItemBase):
+    """Item 返回结构."""
+
+    id: int
+
+
+class ItemFilter(Filter):
+    """Item 搜索查询."""
+
+    title__ilike: str | None = Field(default=None, alias="title", description="标题模糊查询")
+    is_active: bool | None = Field(default=None, description="按上架状态过滤")
+    price__gte: float | None = Field(default=None, alias="price_min", description="最低价格")
+    price__lte: float | None = Field(default=None, alias="price_max", description="最高价格")
+    order_by: list[str] = Field(default=["-id"], description="排序字段")
+
+    class Constants(Filter.Constants):
+        model = Item

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

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

fastapp_cli/templates/project/app/services/base.py.j2

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from fastapi_filter.contrib.sqlalchemy import Filter
+from pydantic import BaseModel
+from sqlmodel import Session
+
+from app.core.exceptions import NotFoundError
+from app.crud.base import CRUDBase
+from app.schemas.common import PageResponse
+
+
+class ServiceBase[CRUDType: CRUDBase]:
+    """Service 基类：业务逻辑层，封装对 CRUD 的调用.
+
+    方法返回值使用 Any 标注：具体模型类型由子类按业务模型收窄，
+    避免方法级泛型 TypeVar 无法从入参推断导致的静态检查噪音。
+    """
+
+    def __init__(self, db: Session, crud: CRUDType):
+        self.db = db
+        self.crud = crud
+
+    def create(self, obj_in: BaseModel | dict[str, Any]) -> Any:
+        """创建."""
+        return self.crud.create(self.db, obj_in=obj_in)
+
+    def create_multi(self, objs_in: list[BaseModel | dict[str, Any]]) -> list[Any]:
+        """批量创建."""
+        return self.crud.create_multi(self.db, objs_in=objs_in)
+
+    def create_or_update(
+        self,
+        obj_in: BaseModel | dict[str, Any],
+        unique_fields: str | Sequence[str] | None = None,
+    ) -> Any:
+        """根据唯一字段创建或更新."""
+        return self.crud.create_or_update(
+            self.db,
+            obj_in=obj_in,
+            unique_fields=unique_fields,
+        )
+
+    def create_or_update_multi(
+        self,
+        objs_in: list[BaseModel | dict[str, Any]],
+        unique_fields: str | Sequence[str] | None = None,
+    ) -> list[Any]:
+        """批量根据唯一字段创建或更新."""
+        return self.crud.create_or_update_multi(
+            self.db,
+            objs_in=objs_in,
+            unique_fields=unique_fields,
+        )
+
+    def update(self, obj_id: int, obj_in: BaseModel | dict[str, Any]) -> Any:
+        """更新."""
+        db_obj = self.crud.get(self.db, obj_id)
+        if db_obj is None:
+            raise NotFoundError(message="待更新的数据不存在")
+        return self.crud.update(self.db, db_obj=db_obj, obj_in=obj_in)
+
+    def get(self, obj_id: int) -> Any:
+        """获取单个."""
+        return self.crud.get_or_404(self.db, obj_id=obj_id)
+
+    def delete(self, obj_id: int) -> Any:
+        """删除."""
+        return self.crud.remove(self.db, obj_id=obj_id)
+
+    def list_objs(self, filter_params: Filter | None = None) -> Sequence[Any]:
+        """获取过滤列表."""
+        return self.crud.get_multi(self.db, filter_params=filter_params)
+
+    def list_page_objs(self, filter_params: Filter | None = None) -> PageResponse[Any]:
+        """分页获取过滤列表."""
+        return self.crud.get_page_multi(self.db, filter_params=filter_params)

fastapp_cli/templates/project/app/services/item_service.py.j2

@@ -0,0 +1,10 @@
+"""Item 业务逻辑."""
+
+from __future__ import annotations
+
+from app.crud.item import CRUDItem
+from app.services.base import ServiceBase
+
+
+class ItemService(ServiceBase[CRUDItem]):
+    pass

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

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