Repository 层

Repository 层是数据访问层，封装所有数据库查询操作。项目通过 BaseRepository 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。

文件位置

src/modules/position/repository.py

完整代码

# +======================================================================
# | 模块: 岗位数据访问层
# | 说明: 定义岗位仓储，继承 BaseRepository 获得通用 CRUD 与软删除能力
# +======================================================================
"""岗位数据访问。"""

from core.base_repository import BaseRepository
from modules.position.models import Position


# ======================================================================
# 岗位仓储
# ======================================================================
class PositionRepository(BaseRepository):
    """岗位仓储。"""

    # ============================================================
    # 绑定的模型类
    # ============================================================
    model = Position

代码解析

基类继承

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__ 会自动实例化：

# service.py 中的使用方式
class PositionService(BaseService):
    model = Position
    repo_cls = PositionRepository  # 传入类，基类自动实例化

何时需要自定义方法

大多数简单 CRUD 模块（如 Position、Level、Category）的 Repository 只需 pass。当需要以下场景时，才在子类中添加自定义方法：

• 复杂联表查询：如 User 需要关联 Dept、Role 查询
• 特殊聚合查询：如统计、分组
• 非标准查询条件：如区间查询、模糊 + 精确组合

示例（UserRepository 中的自定义方法）：

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 层处理。