签入版本

DjangoAdmin_Tornado_EleVue/zh/volume2/repository.md

@@ -0,0 +1,102 @@
+# Repository 层
+
+Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。
+
+## 文件位置
+
+```
+src/modules/position/repository.py
+```
+
+## 完整代码
+
+```python
+# +======================================================================
+# | 模块: 岗位数据访问层
+# | 说明: 定义岗位仓储，继承 BaseRepository 获得通用 CRUD 与软删除能力
+# +======================================================================
+"""岗位数据访问。"""
+
+from core.base_repository import BaseRepository
+from modules.position.models import Position
+
+
+# ======================================================================
+# 岗位仓储
+# ======================================================================
+class PositionRepository(BaseRepository):
+    """岗位仓储。"""
+
+    # ============================================================
+    # 绑定的模型类
+    # ============================================================
+    model = Position
+```
+
+## 代码解析
+
+### 基类继承
+
+```python
+class PositionRepository(BaseRepository(Position]):
+```
+
+`BaseRepository(Position]` 是泛型基类，传入模型类型后自动获得以下能力：
+
+| 方法 | 说明 |
+|:----|:----|
+| `get_by_id(id)` | 根据 ID 查询单条（自动过滤软删除） |
+| `get_by_ids(ids)` | 根据 ID 列表查询多条 |
+| `get_one(**kwargs)` | 按等值条件查询单条（跳过 None 值） |
+| `all()` | 按等值条件查询全部（自动过滤软删除） |
+| `exists_by_field(field, value)` | 判断字段值是否存在 |
+| `count(**kwargs)` | 按条件计数 |
+| `filter(*criterion)` | 原始 SQLAlchemy 条件查询（不自动过滤软删除） |
+| `filter_by(**kwargs)` | 等值条件查询（自动过滤软删除，跳过 None） |
+| `create(**kwargs)` | 创建记录 |
+| `update(id, **kwargs)` | 更新记录 |
+| `paginate(page, limit)` | 分页查询 |
+| `batch_delete(ids)` | 批量软删除 |
+
+### Service 层使用方式
+
+Repository 不需要手动创建单例。Service 层通过 `repo_cls = PositionRepository` 声明关联的 Repository 类，`BaseService.__init__` 会自动实例化：
+
+```python
+# service.py 中的使用方式
+class PositionService(BaseService):
+    model = Position
+    repo_cls = PositionRepository  # 传入类，基类自动实例化
+```
+
+### 何时需要自定义方法
+
+大多数简单 CRUD 模块（如 Position、Level、Category）的 Repository 只需 `pass`。当需要以下场景时，才在子类中添加自定义方法：
+
+- **复杂联表查询**：如 User 需要关联 Dept、Role 查询
+- **特殊聚合查询**：如统计、分组
+- **非标准查询条件**：如区间查询、模糊 + 精确组合
+
+示例（UserRepository 中的自定义方法）：
+
+```python
+class UserRepository(BaseRepository(User]):
+    def get_by_username(self, username: str):
+        """根据用户名查询用户（含角色信息）"""
+        return self.filter(
+            User.username == username,
+            User.is_delete == 0
+        ).first()
+```
+
+## 开发要点
+
+1. **简单模块只需声明 `model`**：继承基类即可获得完整 CRUD 能力
+2. **Service 层通过 `repo_cls` 关联 Repository 类**：基类自动实例化，无需手动创建单例
+3. **`filter()` 不自动过滤软删除**：需要手动追加 `Model.is_delete == 0` 条件
+4. **`filter_by()` / `get_one()` / `all()` 自动过滤软删除**：且跳过 None 值，推荐优先使用
+5. **Repository 层不做响应封装**：返回 SQLAlchemy 查询结果，由 Service 层处理响应
+
+## 总结
+
+Repository 层继承 `BaseRepository` 获得通用 CRUD 能力，等值查询方法（`get_one`/`get_all`/`filter_by`）自动过滤软删除且跳过 None 值，`filter()` 为原始出口需手动追加软删除条件。Repository 层不做响应封装，由 Service 层处理。