54 lines
2.2 KiB
Plaintext
54 lines
2.2 KiB
Plaintext
---
|
||
description: app 包内分层编码规范（API / Service / Model / Schema）
|
||
globs: app/**/*
|
||
alwaysApply: false
|
||
---
|
||
|
||
# 分层编码规范
|
||
|
||
编辑 `app/` 下代码时遵循以下约定。
|
||
|
||
## api/v1（路由层）
|
||
|
||
- 使用 `APIRouter`，按领域分文件（如 `auth.py`），在 `router.py` 聚合。
|
||
- `response_model=ApiResponse[...]` 声明响应类型。
|
||
- 注入依赖：`DbSession`、`RedisClient`、`CurrentUser`（来自 `app.dependencies`）。
|
||
- 捕获 `services` 中的业务异常（如 `AuthError`），转为 `ApiResponse(ok=False, message=...)`。
|
||
- 不在路由内写 `select()` / `db.add()`；一行调用 service 后包装 `ApiResponse(ok=True, data=...)`。
|
||
- 副作用（写 Redis session）可在路由层于 service 成功后调用，与现有 `auth.py` 一致。
|
||
|
||
## services（业务层）
|
||
|
||
- 函数签名显式接收 `AsyncSession` 及业务参数；返回 Pydantic schema 或简单类型。
|
||
- 业务可预期失败：`raise XxxError("中文说明")`，由 API 层捕获。
|
||
- 使用 `sqlalchemy.select` / `session.get`；密码用 `core.security.hash_password` / `verify_password`。
|
||
- 不返回 ORM 给 API 时，用 `UserPublic.model_validate(user)` 等转换。
|
||
|
||
## models（ORM）
|
||
|
||
- 继承 `app.database.Base`，`__tablename__` 复数蛇形。
|
||
- 使用 SQLAlchemy 2 `Mapped[]` / `mapped_column`。
|
||
- 在 `app/models/__init__.py` 导出，供 Alembic `env.py` import。
|
||
|
||
## schemas（Pydantic）
|
||
|
||
- **请求**：`Field` 约束；与前端对齐的字段用 `alias` + `populate_by_name=True`（如 `confirmPassword`）。
|
||
- **响应**：`model_config = ConfigDict(from_attributes=True)` 以便从 ORM 转换。
|
||
- **信封**：所有对外业务 JSON 经 `ApiResponse[T]`，勿在路由返回裸 dict（`/health` 除外仍用 ApiResponse）。
|
||
|
||
## core
|
||
|
||
- 仅放无状态的纯函数/工具（JWT、密码、常量前缀）。
|
||
- 不依赖 FastAPI、Session。
|
||
|
||
## dependencies
|
||
|
||
- 集中定义 `Annotated[..., Depends(...)]` 别名。
|
||
- 鉴权逻辑放在 `get_current_user`：先 Redis session，再 JWT `sub` 查库。
|
||
|
||
## 命名与风格
|
||
|
||
- 文件名：领域名蛇形（`auth.py`）。
|
||
- API 路径：小写、复数资源或动词路径（`/auth/login`）。
|
||
- 用户可见 `message` 使用简体中文，与 aiclient 前端文案风格一致。
|