Repository 层

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

文件位置

src/modules/system/position/repository.py

完整代码

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


# ============================================================
# 岗位仓库类
# ============================================================
class PositionRepository(BaseRepository[Position]):
    """岗位数据仓库，继承基础仓库获得通用 CRUD 能力"""
    pass


# ============================================================
# 仓库实例
# ============================================================
position_repo = PositionRepository(Position)

代码解析

基类继承

class PositionRepository(BaseRepository[Position]):

BaseRepository[Position] 是泛型基类，传入模型类型后自动获得以下能力：

方法	说明
get_by_id(id)	根据 ID 查询单条（自动过滤软删除）
get_by_ids(ids)	根据 ID 列表查询多条
get_one(**kwargs)	按等值条件查询单条（跳过 None 值）
get_all(**kwargs)	按等值条件查询全部（自动过滤软删除）
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)	批量软删除

单例实例

position_repo = PositionRepository(Position)

每个模块在文件末尾创建一个模块级单例 xxx_repo，业务代码通过导入此实例访问数据库，避免重复创建 Repository 对象。

何时需要自定义方法

大多数简单 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. 简单模块直接 pass：继承基类即可获得完整 CRUD 能力
2. 必须创建模块级单例：xxx_repo = XxxRepository(XModel)，供 Service 层调用
3. filter() 不自动过滤软删除：需要手动追加 Model.is_delete == 0 条件
4. filter_by() / get_one() / get_all() 自动过滤软删除：且跳过 None 值，推荐优先使用
5. Repository 层不做响应封装：返回 SQLAlchemy 查询结果，由 Service 层处理响应

总结

Repository 层继承 BaseRepository 获得通用 CRUD 能力，等值查询方法（get_one/get_all/filter_by）自动过滤软删除且跳过 None 值，filter() 为原始出口需手动追加软删除条件。Repository 层不做响应封装，由 Service 层处理。