Become a sponsor
Repository 层
Repository 层是数据访问层，封装所有数据库查询操作。项目通过 BaseRepository 基类提供通用 CRUD 能力，子类只需声明 model 并按需实现 page() 和 list_enabled() 方法。
文件位置
src/modules/system/position/repository.py完整代码
以岗位模块为例，src/modules/system/position/repository.py 完整内容：
python
"""
岗位仓储模块
=============================================================
岗位数据访问层，继承 BaseRepository 获得通用 CRUD 能力。
"""
from src.common.base_repository import BaseRepository
from src.common.constants.common import PAGE_SIZE
from src.modules.system.position.models import Position
class PositionRepository(BaseRepository):
"""岗位数据仓储，提供岗位相关的数据库访问操作"""
model = Position
@classmethod
def page(cls, params: dict):
"""
岗位分页查询
支持按名称模糊搜索、按状态精确过滤，按 sort 字段升序排列。
Args:
params: 查询参数字典
- pageNo: 当前页码
- pageSize: 每页记录数
- name: 岗位名称（模糊匹配）
- status: 状态（精确匹配）
Returns:
tuple: (items, total, pages)
- items: 当前页数据列表
- total: 总记录数
- pages: 总页数
"""
return cls.find_page(
page=int(params.get('pageNo', 1)),
page_size=int(params.get('pageSize', PAGE_SIZE)),
filters={'status': params.get('status')},
like_filters={'name': params.get('name')},
order_by='sort',
)
@classmethod
def list_enabled(cls, params=None):
"""
查询启用的岗位列表
用于下拉选择场景，仅返回启用状态的岗位（status=1 为硬性条件，不可传参覆盖）。
支持与分页一致的条件筛选（name 模糊匹配）。
Args:
params: 查询参数字典，可包含 name 字段用于模糊搜索
Returns:
list: 启用状态的岗位实例列表，按 sort 升序排列
"""
params = params or {}
return cls.find_list(
filters={'status': 1},
like_filters={'name': params.get('name')},
order_by='sort',
)代码解析
基类继承
python
class PositionRepository(BaseRepository):
model = PositionBaseRepository 是基类，子类只需声明 model 即可获得通用 CRUD 能力。所有方法均为 @classmethod，无需创建实例。
必须实现的方法
| 方法 | 说明 | 何时需要 |
|---|---|---|
page(params) | 分页查询 | 所有模块（Service 的 get_page 依赖此方法） |
list_enabled(params) | 无分页列表查询 | 需要下拉选择的模块（Service 的 get_list 依赖此方法） |
page() 和 list_enabled() 内部调用基类的 find_page() 和 find_list() 方法，传入筛选条件和排序规则。
BaseRepository 提供的通用方法
| 方法 | 说明 |
|---|---|
get_by_id(obj_id) | 按主键查询单条未删除记录 |
get_by_ids(ids) | 按主键列表批量查询未删除记录 |
first_by(filters) | 按等值条件查询单条记录 |
exists_by(filters, exclude_id) | 检查是否存在未删除记录（唯一性校验） |
count_by(filters) | 按等值条件统计未删除记录数 |
exists(obj_id) | 检查未删除记录是否存在 |
count_children(parent_id) | 统计子记录数（树形结构删除前校验） |
find_page(...) | 统一分页查询（支持等值/模糊/范围过滤） |
find_list(...) | 统一不分页查询 |
create(**kwargs) | 创建并保存新实例 |
update_by_id(obj_id, data) | 按主键更新字段 |
update_status(obj_id, status) | 单独更新状态字段 |
delete_by_id(obj_id) | 软删除单条记录 |
batch_delete(ids) | 批量软删除 |
batch_restore(ids) | 批量恢复已删除记录 |
何时需要自定义方法
大多数模块只需实现 page() 和 list_enabled()。当需要以下场景时，才在子类中添加自定义方法：
- 复杂联表查询：如 User 需要关联 Dept、Role 查询
- 特殊聚合查询：如统计、分组
- 非标准查询条件：如区间查询、模糊 + 精确组合
示例（UserRepository）：
python
# src/modules/system/user/repository.py
class UserRepository(BaseRepository):
"""用户数据仓储"""
model = User
@classmethod
def page(cls, params: dict):
"""用户分页查询"""
return cls.find_page(
page=int(params.get('pageNo', 1)),
page_size=int(params.get('pageSize', PAGE_SIZE)),
like_filters={'realname': params.get('realname')},
filters={'gender': params.get('gender'), 'status': params.get('status')},
order_desc='id',
)Repository 与 Service 的关系
┌─────────────────────────────────────────────────────────────┐
│ Router 层 │
│ - 定义路由（Blueprint） │
│ - 权限校验（@check_permission） │
│ - 参数解析（parse_request_body） │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Service 层 │
│ - 业务逻辑（BaseService 模板方法 + 钩子） │
│ - 表单校验（WTForms） │
│ - 存在性校验（Repository.exists_by） │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Repository 层 │
│ - 数据库查询（classmethod） │
│ - CRUD 操作 │
│ - 软删除过滤（is_delete == 0） │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Model 层 │
│ - 表结构定义（BaseModel + BaseDB） │
│ - 字段映射 │
└─────────────────────────────────────────────────────────────┘开发要点
- 所有方法均为 classmethod：无需创建实例，直接通过类调用
- 必须实现
page(params)：Service 的get_page依赖此方法 - 按需实现
list_enabled(params)：需要下拉选择的模块实现此方法 find_page/find_list自动过滤软删除：且跳过空值查询条件exists_by(filters, exclude_id)用于唯一性校验：支持排除自身 ID（更新时校验）- Repository 层不做响应封装：返回 SQLAlchemy 查询结果，由 Service 层处理响应
总结
Repository 层继承 BaseRepository 获得通用 CRUD 能力，所有方法均为 classmethod。子类只需声明 model 并实现 page() / list_enabled() 方法。find_page / find_list 自动过滤软删除且跳过空值条件，exists_by 用于唯一性校验。Repository 层不做响应封装，由 Service 层处理。