fastapp-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,105 @@
+"""应用配置管理.
+
+基于 pydantic-settings 的统一配置中心，支持从环境变量 / .env 文件读取.
+
+多环境配置加载顺序（后者覆盖前者）:
+    1. .env                  公共默认配置（入库 git）
+    2. .env.{APP_ENV}        当前环境差异配置（development / production / test）
+    3. 真实的系统环境变量       优先级最高
+
+APP_ENV 的来源（按优先级从高到低）:
+    - 系统环境变量 APP_ENV
+    - .env 文件中显式声明的 APP_ENV
+    - 默认值 "development"
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from pydantic import MySQLDsn, ValidationInfo, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# 先从系统环境变量确定当前环境；.env 文件中的值无法用于决定加载哪个文件，
+# 所以这一步只读系统变量，未设置时退回默认 development。
+_APP_ENV = os.getenv("APP_ENV", "development")
+
+
+class Settings(BaseSettings):
+    """应用配置.
+
+    所有环境变量均通过该类集中管理，避免散落在各处.
+    """
+
+    model_config = SettingsConfigDict(env_file=[".env", f".env.{_APP_ENV}"], extra="ignore")
+
+    # ========== App ==========
+    APP_NAME: str = "{{ project_name }}"
+    APP_ENV: Literal["development", "production", "test"] = "development"
+    DEBUG: bool = False
+    API_V1_PREFIX: str = "/api/v1"
+    # CORS 配置
+    ALLOWED_ORIGINS: list[str] = ["*"]
+
+    # ========== Security ==========
+    # 认证占位：非生产环境直接返回该用户；生产环境需接入真实认证（见 app/api/deps.py）
+    MOCK_USER: str = "dev"
+
+    # ========== Server ==========
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+
+    # ========== Database (MySQL) ==========
+    MYSQL_SERVER: str = "localhost"
+    MYSQL_PORT: int = 3306
+    MYSQL_USER: str = ""
+    MYSQL_PASSWORD: str = ""
+    MYSQL_DB: str = ""
+    DATABASE_URI: str | None = None
+
+    @field_validator("DATABASE_URI", mode="before")
+    @classmethod
+    def assemble_db_uri(cls, v: str | None, info: ValidationInfo) -> str:
+        """当未显式指定 DATABASE_URI 时，自动拼装 MySQL 链接."""
+        if isinstance(v, str) and v:
+            return v
+        values = info.data
+        dsn = MySQLDsn.build(
+            scheme="mysql+pymysql",
+            username=values.get("MYSQL_USER"),
+            password=values.get("MYSQL_PASSWORD"),
+            host=values.get("MYSQL_SERVER", ""),
+            port=values.get("MYSQL_PORT"),
+            path=values.get("MYSQL_DB") or "",
+            query="charset=utf8mb4",
+        )
+        return str(dsn)
+
+    SQL_ECHO: bool = False
+    DB_POOL_SIZE: int = 10
+    DB_MAX_OVERFLOW: int = 20
+
+    # ========== Celery 配置 ==========
+    CELERY_BROKER_URL: str = "redis://localhost:6379/0"
+    CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
+    CELERY_TASK_DEFAULT_QUEUE: str = "default"
+
+    # ========== Flower ==========
+    FLOWER_HOST: str = "0.0.0.0"
+    FLOWER_PORT: int = 5555
+    # 基本认证，格式：user:password，多个用逗号分隔
+    FLOWER_BASIC_AUTH: str | None = None
+
+    @property
+    def is_production(self) -> bool:
+        """是否为生产环境."""
+        return self.APP_ENV == "production"
+
+    @property
+    def is_test(self) -> bool:
+        """是否为测试环境."""
+        return self.APP_ENV == "test"
+
+
+settings = Settings()

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

@@ -0,0 +1,13 @@
+"""请求级上下文变量."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+# 请求级 trace_id 上下文变量，供日志、异常处理器、业务代码共享读取
+trace_id_var: ContextVar[str] = ContextVar("trace_id")
+
+
+def get_trace_id() -> str:
+    """获取当前请求的 trace_id，无请求上下文时返回空串."""
+    return trace_id_var.get("")

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

@@ -0,0 +1,50 @@
+"""数据库引擎与 Session 管理."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from typing import Any
+
+from sqlmodel import Session, SQLModel, create_engine
+
+from app.core.config import settings
+
+# SQLite（测试场景）不支持连接池参数，需要单独处理
+_db_uri = str(settings.DATABASE_URI)
+_engine_kwargs: dict[str, Any] = {
+    "echo": settings.SQL_ECHO,
+    "pool_pre_ping": True,
+}
+if _db_uri.startswith("sqlite"):
+    _engine_kwargs["connect_args"] = {"check_same_thread": False}
+else:
+    _engine_kwargs["pool_size"] = settings.DB_POOL_SIZE
+    _engine_kwargs["max_overflow"] = settings.DB_MAX_OVERFLOW
+    # MySQL 长连接回收，避免 wait_timeout 踢出导致的 2006 错误
+    _engine_kwargs["pool_recycle"] = 3600
+    # MySQL/PostgreSQL 事务隔离级别，避免脏读
+    _engine_kwargs["isolation_level"] = "REPEATABLE READ"
+    # 连接超时：数据库未就绪时快速失败，供启动探测降级
+    _engine_kwargs["connect_args"] = {"connect_timeout": 3}
+
+engine = create_engine(_db_uri, **_engine_kwargs)
+
+
+def init_db() -> None:
+    """初始化数据库，创建所有表.
+
+    生产环境请使用 alembic 迁移，此处仅用于本地 / 测试快速建表.
+    """
+    # 导入 models 以便 SQLModel.metadata 能够注册所有表
+    from app import models  # noqa: F401
+
+    SQLModel.metadata.create_all(engine)
+
+
+def get_session() -> Generator[Session, None, None]:
+    """FastAPI 依赖：获取数据库会话.
+
+    使用 yield 语法保证异常时 Session 正常关闭.
+    """
+    with Session(engine) as session:
+        yield session

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

@@ -0,0 +1,175 @@
+"""自定义异常与全局异常处理器.
+
+使用示例::
+
+    from app.core.exceptions import NotFoundError, AppException
+
+    # 1. 使用预定义异常
+    if user is None:
+        raise NotFoundError(message="用户不存在")
+
+    # 2. 自定义业务异常（自定义业务码）
+    raise AppExceptionError(
+        message="余额不足",
+        code=10001,
+        status_code=400,
+    )
+
+返回体统一格式::
+
+    {"code": 10001, "message": "余额不足", "data": null}
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from loguru import logger
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from app.core.context_var import get_trace_id
+from app.core.middleware import TRACE_ID_HEADER
+
+
+class AppExceptionError(Exception):
+    """业务异常基类.
+
+    用于区分业务异常与系统异常. 所有业务异常统一继承此类.
+    """
+
+    status_code: int = status.HTTP_400_BAD_REQUEST
+    code: int = 1
+    message: str = "业务异常"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        code: int | None = None,
+        status_code: int | None = None,
+        data: Any = None,
+    ) -> None:
+        """构造业务异常.
+
+        :param message: 异常信息
+        :param code: 业务状态码
+        :param status_code: HTTP 状态码
+        :param data: 附加数据
+        """
+        if message is not None:
+            self.message = message
+        if code is not None:
+            self.code = code
+        if status_code is not None:
+            self.status_code = status_code
+        self.data = data
+        super().__init__(self.message)
+
+
+class NotFoundError(AppExceptionError):
+    """资源不存在."""
+
+    status_code = status.HTTP_404_NOT_FOUND
+    code = 40400
+    message = "资源不存在"
+
+
+class UnauthorizedError(AppExceptionError):
+    """未认证."""
+
+    status_code = status.HTTP_401_UNAUTHORIZED
+    code = 40100
+    message = "未认证或凭证已失效"
+
+
+class ForbiddenError(AppExceptionError):
+    """无权限."""
+
+    status_code = status.HTTP_403_FORBIDDEN
+    code = 40300
+    message = "无访问权限"
+
+
+class ConflictError(AppExceptionError):
+    """资源冲突."""
+
+    status_code = status.HTTP_409_CONFLICT
+    code = 40900
+    message = "资源冲突"
+
+
+def _make_response(
+    *,
+    status_code: int,
+    code: int,
+    message: str,
+    data: Any = None,
+) -> JSONResponse:
+    """统一的错误返回体."""
+    trace_id = get_trace_id()
+    content: dict[str, Any] = {
+        "code": code,
+        "message": message,
+        "data": data,
+        "trace_id": trace_id or None,
+    }
+    headers = {TRACE_ID_HEADER: trace_id} if trace_id else None
+    return JSONResponse(
+        status_code=status_code,
+        content=jsonable_encoder(content),
+        headers=headers,
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """注册全局异常处理器.
+
+    :param app: FastAPI 应用实例
+    """
+
+    @app.exception_handler(AppExceptionError)
+    async def handle_app_exception(_: Request, exc: AppExceptionError) -> JSONResponse:
+        logger.warning("AppException: code={} message={}", exc.code, exc.message)
+        return _make_response(
+            status_code=exc.status_code,
+            code=exc.code,
+            message=exc.message,
+            data=exc.data,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def handle_validation_error(
+        _: Request,
+        exc: RequestValidationError,
+    ) -> JSONResponse:
+        logger.warning("Validation error: {}", exc.errors())
+        return _make_response(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            code=42200,
+            message="参数校验失败",
+            data=exc.errors(),
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def handle_http_exception(
+        _: Request,
+        exc: StarletteHTTPException,
+    ) -> JSONResponse:
+        return _make_response(
+            status_code=exc.status_code,
+            code=exc.status_code * 100,
+            message=str(exc.detail),
+        )
+
+    @app.exception_handler(Exception)
+    async def handle_unknown_exception(_: Request, exc: Exception) -> JSONResponse:
+        logger.exception("Unhandled exception: {}", exc)
+        return _make_response(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            code=50000,
+            message="服务器内部错误",
+        )

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

@@ -0,0 +1,125 @@
+"""日志配置 - 基于 loguru."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from loguru import logger
+
+from app.core.config import settings
+from app.core.context_var import get_trace_id, trace_id_var
+
+
+def with_trace(func: Callable[..., Any]) -> Callable[..., Any]:
+    """包装函数，在执行时把当前请求的 trace_id 透传到上下文与日志.
+
+    用于 ``BackgroundTasks.add_task`` 等"脱离请求生命周期"的场景：
+    在调用 ``with_trace`` 的瞬间（仍处于请求上下文）抓取 trace_id，
+    在被包装函数真正执行时再写回 ``ContextVar`` 与 loguru extra。
+
+    :param func: 待包装的同步或异步函数
+    :return: 包装后的函数，签名与原函数一致
+    """
+    trace_id = get_trace_id() or "-"
+
+    if inspect.iscoroutinefunction(func):
+        @functools.wraps(func)
+        async def _async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            token = trace_id_var.set(trace_id)
+            try:
+                with logger.contextualize(trace_id=trace_id):
+                    return await func(*args, **kwargs)
+            finally:
+                trace_id_var.reset(token)
+
+        return _async_wrapper
+
+    @functools.wraps(func)
+    def _sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        token = trace_id_var.set(trace_id)
+        try:
+            with logger.contextualize(trace_id=trace_id):
+                return func(*args, **kwargs)
+        finally:
+            trace_id_var.reset(token)
+
+    return _sync_wrapper
+
+
+class InterceptHandler(logging.Handler):
+    """拦截标准 logging 输出，统一转发到 loguru."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """重写 emit 方法."""
+        try:
+            level: str | int = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        # 读取当前请求上下文的 trace_id；logger.patch 中创建的 logger 实例不会自动继承
+        # contextualize 注入的 extra，需在 patch 回调里显式写入 record.extra。
+        trace_id = get_trace_id() or "-"
+
+        # 直接使用 record 自带的源信息（name/funcName/lineno），通过 logger.patch
+        # 强制覆盖 loguru 推断出的调用位置。这样无论标准 logging 内部经过多少层
+        # 调用（callHandlers/handle/emit 等），都能准确定位到真正的业务调用方。
+        def _patcher(r: dict) -> None:
+            r["name"] = record.name
+            r["function"] = record.funcName
+            r["line"] = record.lineno
+            r["extra"]["trace_id"] = trace_id
+
+        patched = logger.patch(_patcher)  # type: ignore
+        patched.opt(depth=0, exception=record.exc_info).log(
+            level,
+            record.getMessage(),
+        )
+
+
+def setup_logging() -> None:
+    """初始化全局日志."""
+    # 移除默认 handler
+    logger.remove()
+
+    # 为 extra 字段提供默认值，避免在无请求上下文（启动 / 后台任务）时格式化报错
+    logger.configure(extra={"trace_id": "-"})
+
+    log_format = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+        "<level>{level: <8}</level> | "
+        "<cyan>{extra[trace_id]}</cyan> | "
+        "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+        "<level>{message}</level>"
+    )
+
+    # 控制台输出
+    logger.add(
+        sys.stdout,
+        format=log_format,
+        level="DEBUG" if settings.DEBUG else "INFO",
+        colorize=True,
+        backtrace=True,
+        diagnose=settings.DEBUG,
+    )
+
+    # 拦截第三方库的标准 logging
+    # 1. 替换 root logger 的 handler，确保所有未单独配置的 logger 都走 InterceptHandler
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    # 2. 清理所有已存在的 logger 的 handler，并启用 propagate，避免重复输出
+    #    （特别是 SQLAlchemy 在 echo=True 时会给 sqlalchemy.engine.Engine 单独添加 handler）
+    for logger_name in list(logging.root.manager.loggerDict.keys()):
+        existing_logger = logging.getLogger(logger_name)
+        existing_logger.handlers = []
+        existing_logger.propagate = True
+
+    # 3. 显式为关注的第三方库 logger 设置级别（确保不会被各自默认级别屏蔽）
+    for name in ("uvicorn", "uvicorn.error", "uvicorn.access", "fastapi", "sqlalchemy.engine"):
+        logging_logger = logging.getLogger(name)
+        logging_logger.handlers = []
+        logging_logger.propagate = True

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

@@ -0,0 +1,39 @@
+"""请求级中间件 - 注入 trace_id 与请求耗时日志."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import Request, Response
+from loguru import logger
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+
+from app.core.context_var import trace_id_var
+
+TRACE_ID_HEADER = "X-Trace-ID"
+
+
+class TraceIDMiddleware(BaseHTTPMiddleware):
+    """注入 trace_id 并记录请求耗时.
+
+    - 优先复用上游传入的 ``X-Trace-ID``，否则自动生成 UUID4
+    - 写入 ``ContextVar`` 与 ``loguru.contextualize``，使日志自动携带 trace_id
+    - 响应头回写 ``X-Trace-ID``，便于前端/网关链路追踪
+    - 不捕获业务异常，统一交由全局 exception handler 处理
+    """
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        trace_id = request.headers.get(TRACE_ID_HEADER) or uuid.uuid4().hex[:16]
+        token = trace_id_var.set(trace_id)
+        try:
+            with logger.contextualize(trace_id=trace_id):
+                logger.info("{method} {path}", method=request.method, path=request.url.path)
+                response = await call_next(request)
+                response.headers[TRACE_ID_HEADER] = trace_id
+                return response
+        finally:
+            trace_id_var.reset(token)

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

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