Service 层规范

概述

Service 层是业务逻辑层，各模块 Service 继承 BaseService 获得通用 CRUD 能力。子类只需声明差异点（repository / form / model_name），即可获得完整的增删改查接口。

设计模式

BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。所有方法均为 @classmethod。

标准模块结构

from src.common.base_service import BaseService
from src.core.exceptions import BizError
from src.modules.system.position.schema import PositionForm, PositionStatusForm
from src.modules.system.position.repository import PositionRepository
from src.modules.system.user.repository import UserRepository


class PositionService(BaseService):
    """
    岗位服务类

    继承 BaseService 获得标准 CRUD 能力，并扩展删除前用户引用校验。
    """
    repository = PositionRepository
    form = PositionForm
    status_form = PositionStatusForm
    model_name = "岗位"

    @classmethod
    def before_delete(cls, ids):
        """删除前校验：存在用户引用该岗位时禁止删除"""
        for pid in ids:
            if UserRepository.count_by({'position_id': pid}) > 0:
                raise BizError(f"岗位ID {pid} 已被用户引用，无法删除")


# ============================================================
# 模块级代理函数：保持 router 调用兼容
# ============================================================

get_position_page = PositionService.get_page
get_position_detail = PositionService.get_detail
get_info = PositionService.get_info
add_position = PositionService.add
update_position = PositionService.update
delete_positions = PositionService.remove
update_position_status = PositionService.update_status
get_position_list = PositionService.get_list

必须声明的属性

属性	类型	说明	示例
repository	Repository 类	数据访问层类	PositionRepository
form	Form 类	新增/更新表单校验类	PositionForm
status_form	Form 类	状态更新表单校验类（可选）	PositionStatusForm
model_name	str	业务对象名称，用于错误提示	"岗位"
serialize_maps	dict	枚举显示名映射（可选）	{'type': 'operation_type'}

基类提供的通用方法

方法	说明
get_page(params)	分页查询（委托 repository.page）
get_detail(id)	查询详情（返回字典）
get_info(id)	查询模型对象（内部使用）
add(data)	新增记录（含表单校验 + 钩子）
update(data)	更新记录（含表单校验 + 存在性校验 + 钩子）
remove(ids)	批量软删除（逗号分隔 ID 字符串）
update_status(data)	更新状态（含状态表单校验）
get_list(params)	无分页列表查询（委托 repository.list_enabled）

可覆写钩子方法

钩子	触发时机	说明
before_add(form)	新增操作前	可返回额外写入字段字典
after_add(obj)	新增操作后	用于缓存清理等
before_update(form, obj)	更新操作前	可返回额外更新字段字典
after_update(obj)	更新操作后	用于缓存清理等
before_delete(ids)	删除操作前	抛出 BizError 中止删除
after_delete(count)	删除操作后	记录审计日志等
_enrich_page_records(records)	分页富化时	追加关联数据（基类自动应用 serialize_maps）
_detail_dict(obj)	详情序列化时	自定义返回字段（基类自动应用 serialize_maps）

模块级代理函数

# 将 Service 类方法代理为模块级函数，方便路由层直接调用
get_position_page = PositionService.get_page
get_position_detail = PositionService.get_detail
get_info = PositionService.get_info
add_position = PositionService.add
update_position = PositionService.update
delete_positions = PositionService.remove
update_position_status = PositionService.update_status
get_position_list = PositionService.get_list

为什么需要代理函数？

Service 的所有方法都是 @classmethod，但 Router 层习惯通过模块级函数调用。代理函数将类方法暴露为模块级函数，保持 Router 层调用简洁。

复杂模块示例（User）

复杂模块可覆写 add / update 等方法，实现头像保存、密码加密、角色关联等定制逻辑：

# src/modules/system/user/service.py
class UserService(BaseService):
    repository = UserRepository
    form = UserForm
    status_form = UserStatusForm
    model_name = "用户"

    @classmethod
    def add(cls, data: dict) -> None:
        """新增用户（覆写基类方法）"""
        form = cls._validate_form(data)

        # 头像保存
        avatar = form.data.get("avatar")
        if avatar:
            form.avatar.data = save_file(avatar, "user")

        # 密码加密
        pwd = form.data.get("password") or DEFAULT_PASSWORD
        salt = generate_salt()

        # 行政区划校验
        city = form.data.get("city", [])
        if len(city) != 4:
            raise BizError("请选择完整的所在城市（省/市/区/街道）")
        roles = form.data.get("roles")

        # 清理表单数据
        create_data = cls._clean_form_data(form)
        create_data["password"] = encrypt_password(pwd, salt)
        create_data["salt"] = salt
        create_data["create_user"] = get_realname()
        _apply_city(create_data, city)

        # 创建用户
        user = cls.repository.create(**create_data)
        user.code = f"{user.id:06d}"

        # 关联角色
        _add_user_role(user.id, roles)
        # 清除权限缓存
        invalidate_user_cache(user.id)

    @classmethod
    def _enrich_page_records(cls, records):
        """分页富化：补充部门、职级、岗位、角色等关联数据"""
        return _enrich_user_records(records)

    @classmethod
    def _detail_dict(cls, obj):
        """详情序列化：剔除密码字段，补充关联数据"""
        data = model_to_dict(obj)
        if data:
            data.pop("password", None)
        return _enrich_user_detail(data)

开发要点

1. 必须声明 repository：基类所有数据访问方法依赖此属性
2. 声明 form 和 status_form：用于自动表单校验
3. 声明 model_name：用于错误提示信息
4. 删除前校验用 before_delete 钩子：抛出 BizError 中止操作
5. 必须创建模块级代理函数：供 Router 层调用
6. Service 层不直接读取 request：参数通过函数传入（dict 类型）
7. 业务失败通过 raise BizError 表达：不返回 R 对象

总结

Service 层继承 BaseService 获得通用 CRUD 能力，只需声明差异点（repository / form / model_name）并覆写钩子方法。所有方法均为 @classmethod，必须创建模块级代理函数供 Router 层调用。入参为数据字典，出参为纯数据，业务失败通过 raise BizError 表达。