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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapp-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: FastAPI 项目脚手架：一条命令生成完整可运行的 FastAPI 工程
 Author: aidenmo
 License: MIT

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

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

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

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

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

@@ -62,6 +62,8 @@ app/
 
 ## 扩展指南
 
+> AI Agent / 新成员开发前请先阅读 [docs/agent_guide.md](docs/agent_guide.md)——包含架构说明、核心方法清单（优先复用）、标准开发流程与编码规范。
+
 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` 的占位实现；

fastapp_cli-0.2.0/src/fastapp_cli/templates/project/docs/agent_guide.md.j2

@@ -0,0 +1,305 @@
+# {{ project_name }} — AI Agent 开发参考文档
+
+> 本文档面向 AI Agent（或新加入的开发者），目标是帮助你在不了解项目历史的情况下，快速掌握项目设计并**正确地**进行开发。
+> 核心原则：**优先复用已有方法与基础设施，不要重复造轮子。**
+
+## 1. 项目概述与整体架构
+
+本项目是由 fastapp-cli v{{ fastapp_cli_version }} 生成的 FastAPI 工程，技术栈：
+
+| 层次 | 技术 | 说明 |
+|---|---|---|
+| Web 框架 | FastAPI | 工厂函数 `create_app` 创建，lifespan 管理启动/关闭 |
+| ORM | SQLModel (SQLAlchemy) | PEP 695 泛型 CRUD 基类 |
+| 数据库 | MySQL（默认）/ SQLite（测试） | SQLAlchemy 引擎，连接池参数已调优 |
+| 迁移 | Alembic | 增量迁移，`MANAGED_TABLES` 约束只管理业务表 |
+| 异步任务 | Celery + Redis | redis 不可达时自动降级 memory broker |
+| 分页 | fastapi-pagination | 统一分页响应结构 |
+| 过滤 | fastapi-filter | 声明式查询过滤器 |
+| 日志 | loguru | 拦截标准 logging，全链路 trace_id |
+| 配置 | pydantic-settings | 多环境 `.env` 加载 |
+| 包管理 | uv | 依赖分组（dev 组含 pytest/ruff/mypy） |
+| 质量工具 | ruff + mypy + pytest | 必须全绿才能合入 |
+
+**分层架构（自上而下的调用方向，禁止跨层 / 反向依赖）：**
+
+```text
+Endpoint (app/api/v1/endpoints/)   路由层：参数解析、依赖注入、组装 Response
+    ↓ 调用
+Service (app/services/)            业务层：业务规则、事务编排，继承 ServiceBase
+    ↓ 调用
+CRUD (app/crud/)                   数据访问层：只做数据读写，继承 CRUDBase
+    ↓ 操作
+Model (app/models/)                SQLModel 表模型 + Pydantic 校验二合一
+```
+
+**横切能力（在 core 中，所有层可直接使用）：** 统一响应 / 统一异常 / TraceID / 日志 / 配置 / 数据库会话。
+
+**请求处理链路：**
+
+```text
+TraceIDMiddleware (最外层，生成/透传 X-Trace-Id)
+  → CORS
+    → register_exception_handlers 注册的异常处理器（兜底所有异常）
+      → Endpoint（注入 DBSession / CurrentUser）
+        → Response[T] 自动注入 trace_id
+```
+
+## 2. 目录结构及各模块职责
+
+```text
+.
+├── app/
+│   ├── main.py                  # create_app 工厂 + lifespan（DB/redis 探测，缺席降级不阻塞启动）
+│   ├── core/                    # 横切基础设施（禁止在此写业务逻辑）
+│   │   ├── config.py            #   settings 配置中心（多环境 .env 加载）
+│   │   ├── database.py          #   engine / get_session / init_db
+│   │   ├── logging.py           #   setup_logging / with_trace / InterceptHandler
+│   │   ├── 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/
+│   │   ├── deps.py              #   DBSession / CurrentUser 依赖（认证占位）
+│   │   └── v1/
+│   │       ├── router.py        #   v1 总路由，新业务路由在此挂载
+│   │       └── endpoints/       #   health.py（健康检查）、items.py（分页 CRUD 示例域）
+│   ├── models/                  # SQLModel 表模型；新模型必须在 __init__.py 注册
+│   │   ├── base.py              #   IDMixin / TimestampMixin / utcnow
+│   │   └── item.py              #   Item 示例模型
+│   ├── schemas/                 # Pydantic Schema：入参 / 出参 / 过滤器
+│   │   ├── common.py            #   Response / PageParams / PageResult / PageResponse
+│   │   └── item.py              #   ItemCreate / ItemUpdate / ItemRead / ItemFilter
+│   ├── crud/                    # 数据访问层
+│   │   ├── base.py              #   CRUDBase 泛型基类（核心复用点）
+│   │   └── item.py              #   CRUDItem(CRUDBase[Item])
+│   ├── services/                # 业务逻辑层
+│   │   ├── base.py              #   ServiceBase 泛型基类（核心复用点）
+│   │   └── item_service.py      #   ItemService(ServiceBase[CRUDItem])
+│   ├── tasks/                   # Celery 任务（sample_tasks.py 为示例）
+│   └── utils/                   # 通用工具扩展位（空）
+├── alembic/                     # 迁移环境（env.py 已配置 MANAGED_TABLES 白名单过滤）
+├── docs/                        # 本文档 + SQLModel定义示例.md（建模规范）
+├── scripts/                     # start.sh / celery_worker.sh / celery_beat.sh / celery_flower.sh
+├── tests/                       # pytest：conftest 用 sqlite 内存库，无需真实 MySQL
+├── alembic.ini / Makefile / pyproject.toml
+└── .env / .env.example          # 配置文件（.env 入库，敏感信息按环境覆盖）
+```
+
+## 3. 已有核心方法与工具函数清单（优先复用）
+
+> **强制要求：开发新功能前先检索本清单。能用现有方法解决的，必须调用现有方法，禁止重写等价实现。**
+
+### 3.1 数据访问层 — `CRUDBase`（`app/crud/base.py`）
+
+泛型基类 `CRUDBase[ModelType: SQLModel]`，所有业务 CRUD 继承它即可获得以下能力，**任何手写 select/commit 循环前必须先确认此处没有现成方法**：
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `get` | `(db: Session, obj_id: Any) -> ModelType \| None` | 按主键查询 |
+| `get_or_404` | `(db: Session, obj_id: Any) -> ModelType` | 按主键查询，不存在抛 `NotFoundError` |
+| `get_by_field` | `(db: Session, field: str, value: Any) -> ModelType \| None` | 按任意字段查单个（字段不存在抛 `ValueError`） |
+| `get_page_multi` | `(db: Session, *, filter_params: Filter \| None = None) -> PageResponse[Any]` | 分页 + 过滤 + 排序查询 |
+| `get_multi` | `(db: Session, *, filter_params: Filter \| None = None) -> Sequence[ModelType]` | 非分页列表查询 |
+| `count` | `(db: Session, query: Select \| SelectOfScalar \| None = None) -> int` | 记录总数（可传入自定义 query） |
+| `create` | `(db: Session, *, obj_in: BaseModel \| dict[str, Any]) -> ModelType` | 创建单条（自动 model_dump、commit、refresh） |
+| `create_multi` | `(db: Session, *, objs_in: list[...]) -> list[ModelType]` | 批量创建 |
+| `update` | `(db: Session, *, db_obj: ModelType, obj_in: BaseModel \| dict[str, Any]) -> ModelType` | 更新（`exclude_unset` 语义，只更新显式传入字段） |
+| `create_or_update` | `(db: Session, *, obj_in, unique_fields: str \| Sequence[str] \| None = None) -> ModelType` | 按唯一字段 upsert（未指定时用主键） |
+| `create_or_update_multi` | `(db: Session, *, objs_in: list[...], unique_fields=None) -> list[ModelType]` | 批量 upsert（同一事务提交） |
+| `remove` | `(db: Session, *, obj_id: int) -> ModelType` | 按主键删除（不存在抛 404） |
+| `remove_multi` | `(db: Session, *, obj_ids: list[Any]) -> list[ModelType]` | 批量删除 |
+| `exists` | `(db: Session, *, obj_id: Any) -> bool` | 判断是否存在 |
+
+使用示例（新增业务域的 CRUD 通常只需一行继承）：
+
+```python
+from app.crud.base import CRUDBase
+from app.models.product import Product
+
+class CRUDProduct(CRUDBase[Product]):
+    pass  # 复杂查询逻辑才在此扩展
+```
+
+### 3.2 业务层 — `ServiceBase`（`app/services/base.py`）
+
+泛型基类 `ServiceBase[CRUDType: CRUDBase]`，内部持有 `self.db` 与 `self.crud`，方法返回值标注为 `Any`（由子类按业务模型收窄）：
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `create` | `(obj_in: BaseModel \| dict) -> Any` | 创建 |
+| `create_multi` | `(objs_in: list) -> list[Any]` | 批量创建 |
+| `create_or_update` | `(obj_in, unique_fields=None) -> Any` | upsert |
+| `create_or_update_multi` | `(objs_in, unique_fields=None) -> list[Any]` | 批量 upsert |
+| `get` | `(obj_id: int) -> Any` | 获取单个，不存在抛 `NotFoundError` |
+| `update` | `(obj_id: int, obj_in) -> Any` | 更新（不存在抛 `NotFoundError`） |
+| `delete` | `(obj_id: int) -> Any` | 删除 |
+| `list_objs` | `(filter_params: Filter \| None = None) -> Sequence[Any]` | 列表查询 |
+| `list_page_objs` | `(filter_params: Filter \| None = None) -> PageResponse[Any]` | 分页查询 |
+
+使用示例（纯 CRUD 型业务，Service 通常也只是继承）：
+
+```python
+from app.crud.product import CRUDProduct
+from app.services.base import ServiceBase
+
+class ProductService(ServiceBase[CRUDProduct]):
+    def activate(self, obj_id: int) -> None:  # 自定义业务方法
+        obj = self.get(obj_id)
+        self.crud.update(self.db, db_obj=obj, obj_in={"is_active": True})
+```
+
+### 3.3 API 依赖（`app/api/deps.py`）
+
+| 名称 | 类型 | 说明 |
+|---|---|---|
+| `DBSession` | `Annotated[Session, Depends(get_session)]` | 端点中直接作参数注解，获取数据库会话 |
+| `CurrentUser` | `Annotated[str, Depends(get_current_user)]` | 当前登录用户。非生产环境返回 `settings.MOCK_USER`；生产环境抛 `UnauthorizedError`（认证占位，接入真实认证时只改 `get_current_user`） |
+
+```python
+@router.post("", response_model=Response[ProductRead])
+def create_product(payload: ProductCreate, service: ProductServiceDep, current_user: CurrentUser) -> Response[ProductRead]:
+    data: ProductRead = service.create(payload)
+    return Response(data=data)
+```
+
+### 3.4 统一响应与分页（`app/schemas/common.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `Response[T]` | 统一响应体 `{code, message, data, trace_id}`；`code=0` 为成功；trace_id 自动从请求上下文注入 |
+| `PageParams` | 分页入参（`page` / `page_size`，`size` 的 URL alias 为 `page_size`） |
+| `PageResult[T]` | 分页数据结构 `{total, page, page_size, content}` |
+| `PageResponse[T]` | 分页统一响应（继承 `Response[PageResult[T]]`），作为端点 `response_model` 使用 |
+
+### 3.5 统一异常（`app/core/exceptions.py`）
+
+**业务代码中禁止直接 `raise HTTPException` 或返回错误 dict**，统一抛以下异常，由全局异常处理器转换成统一返回体 `{code, message, data, trace_id}`：
+
+| 异常 | HTTP 状态码 | 业务码 | 默认消息 |
+|---|---|---|---|
+| `AppExceptionError(message, *, code, status_code, data)` | 400 | 1 | 业务异常基类，自定义业务异常继承它 |
+| `NotFoundError` | 404 | 40400 | 资源不存在 |
+| `UnauthorizedError` | 401 | 40100 | 未认证或凭证已失效 |
+| `ForbiddenError` | 403 | 40300 | 无访问权限 |
+| `ConflictError` | 409 | 40900 | 资源冲突 |
+
+```python
+from app.core.exceptions import ConflictError, NotFoundError, AppExceptionError
+
+raise NotFoundError(message="订单不存在")
+raise AppExceptionError(message="余额不足", code=10001, status_code=400)
+```
+
+未捕获异常统一返回 HTTP 500 + `{"code": 50000, "message": "服务器内部错误"}`，不会裸抛堆栈（应用实例固定 `debug=False`，勿改）。
+
+### 3.6 模型公共字段（`app/models/base.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `IDMixin` | 主键 `id: int`（primary_key + index） |
+| `TimestampMixin` | `create_time` / `update_time`，数据库自动生成与刷新，JSON 序列化为 `%Y-%m-%d %H:%M:%S` |
+| `utcnow()` | 当前时间（`default_factory` 用） |
+| `FormattedDatetime` | 可复用的 datetime 序列化类型标注 |
+
+新表模型标准写法：
+
+```python
+from sqlmodel import Field
+from app.models.base import IDMixin, TimestampMixin
+
+class ProductBase(TimestampMixin):
+    name: str = Field(max_length=128, description="名称")
+
+class Product(IDMixin, ProductBase, table=True):
+    __tablename__ = "t_product"
+```
+
+### 3.7 配置（`app/core/config.py`）
+
+- 单例 `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`。
+- 属性：`settings.is_production` / `settings.is_test`。
+- 新增配置项：在 `Settings` 类中加字段 + 默认值，并在 `.env.example` / `.env` 中补充说明。
+
+### 3.8 数据库（`app/core/database.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `engine` | 全局引擎。sqlite（测试）与 MySQL（连接池 + `pool_recycle=3600` + `REPEATABLE READ` + 3 秒连接超时）已分别调优，勿重复配置 |
+| `get_session()` | FastAPI 依赖，yield 语法保证 Session 关闭；**通过 `DBSession` 注解使用**，不要自建 Session |
+| `init_db()` | 本地/测试快速建表（生产用 alembic 迁移） |
+
+### 3.9 Celery（`app/core/celery_app.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `celery_app` | 全局单例（worker 与 web 共用），新任务直接 `@celery_app.task` |
+| `build_celery_app(broker_url, backend_url, *, name)` | 构造入口（自定义 broker 时使用） |
+| `degrade_to_memory(celery)` | 降级为 memory broker/backend（lifespan 探测失败时自动调用，勿手动调用） |
+
+新任务示例：
+
+```python
+from app.core.celery_app import celery_app
+
+@celery_app.task
+def send_notice(user_id: int) -> str:
+    ...
+```
+
+### 3.10 日志与 TraceID（`app/core/logging.py`、`app/core/context_var.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `setup_logging()` | lifespan 启动时自动调用，勿重复调用 |
+| `logger`（loguru） | 业务代码统一 `from loguru import logger`；标准 logging 已被拦截转发到 loguru |
+| `with_trace` | 装饰器：把请求 trace_id 透传到后台任务（`BackgroundTasks.add_task` 场景**必须**用它包裹） |
+| `get_trace_id()` | 获取当前请求 trace_id（无上下文返回空串） |
+
+## 4. 新增功能的标准开发流程
+
+### 4.1 新增业务域（以 `product` 为例，五件套 + 两处注册 + 迁移 + 测试）
+
+1. **Model**：`app/models/product.py`，继承 `IDMixin, TimestampMixin`（见 §3.6 示例）；在 `app/models/__init__.py` 中 import 并加入 `__all__`（否则 alembic autogenerate 无法发现）。
+2. **Schema**：`app/schemas/product.py`，定义 `ProductCreate` / `ProductUpdate` / `ProductRead`（继承 `ProductBase` + `id` 字段）与 `ProductFilter(Filter)`（`Constants.model` 指向模型，过滤字段用 `__ilike` / `__gte` 等后缀，参考 `app/schemas/item.py`）。
+3. **CRUD**：`app/crud/product.py`，`class CRUDProduct(CRUDBase[Product]): pass`。
+4. **Service**：`app/services/product_service.py`，`class ProductService(ServiceBase[CRUDProduct])`，业务规则写在这里。
+5. **Endpoint**：`app/api/v1/endpoints/product.py`，仿照 `items.py`：`get_service` 依赖 + `ServiceDep` + 各路由方法返回 `Response[...]` / `PageResponse[...]`。
+6. **注册路由**：`app/api/v1/router.py` 中 `include_router(product_router, prefix="/products", tags=["Products"])`。
+7. **迁移**：`make revision m="add t_product"` → 检查 `alembic/versions/` 生成脚本 → `make migrate`。注意 `alembic/env.py` 用 `MANAGED_TABLES` 白名单过滤，新表模型注册到 `app/models/__init__.py` 后会被自动纳入。
+8. **测试**：在 `tests/` 下仿照 `tests/api/test_items.py` 编写（conftest 已用 sqlite 内存库，无需真实 MySQL），运行 `make test && make lint`。
+
+### 4.2 其他扩展场景
+
+| 场景 | 做法 |
+|---|---|
+| 新增配置项 | `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`，全局处理器自动生效 |
+| 复杂查询 | 在业务 CRUD 子类中扩展方法，保持 Service 只编排不写 SQL 细节 |
+
+## 5. 编码规范与注意事项
+
+### 5.1 强制规范
+
+1. **统一响应**：所有端点 `response_model` 必须是 `Response[T]` 或 `PageResponse[T]`；错误场景抛异常（§3.5），禁止返回裸 dict / 直接 `HTTPException`。
+2. **禁止 `FastAPI(debug=True)`**：`main.py` 中已固定 `debug=False`。`DEBUG=true` 仅控制日志级别、SQL echo 与 uvicorn reload；传 True 会导致 Starlette 绕过统一异常处理器返回原始堆栈。
+3. **分层依赖方向**：endpoint → service → crud → model，单向依赖；core 不依赖业务层。
+4. **复用优先**：新写任何 select/commit/upsert/分页逻辑前，先查 §3 清单；CRUDBase / ServiceBase 未覆盖的场景才在子类扩展。
+5. **模型注册**：新模型必须加入 `app/models/__init__.py`，否则 `init_db()` 与 alembic autogenerate 均无法感知。
+6. **质量门禁**：提交前 `make format && make test && make lint`（ruff + mypy）必须全绿。类型注解用 PEP 695 语法（`class Foo[T]`），SQLModel `inspect()` 返回可空处沿用既有的 `cast(...)` + `# type: ignore[union-attr]` 惯例。
+7. **导入风格**：`from __future__ import annotations` 置于模块首行（docstring 之后）；第三方与本地导入分组，遵循 isort 规则（ruff 强制）。
+
+### 5.2 注意事项
+
+- **时间字段**：一律通过 `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。
+- **测试环境**：测试用 sqlite 内存库（`tests/conftest.py`），依赖 sqlite 不支持的特性时需显式跳过。
+- **`.env` 提交策略**：`.env` 与 `.env.example` 入库作默认配置；敏感信息（生产密码）放 `.env.production`（不入库）或真实环境变量。
+- **docs/**：`SQLModel定义示例.md` 是建模规范，新表定义先对照该文档。
+- **业务域隔离**：`item` 域为示例，可整体替换为实际业务；删除时同步清理 `router.py` 挂载与对应测试。