05-业务服务层 service¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/bams-sdk/05-service.md

bams-service（70 个类）是 SDK 的业务核心。提供 ServiceExtImpl 业务 Service 基类、序列号生成、动态数据源、Session 管理、通用业务 Service。

一、ServiceExtImpl —— 业务 Service 基类（核心）¶

cn.cnbm.bams.service.ext.IServiceExt<T> / cn.cnbm.bams.service.ext.impl.ServiceExtImpl<MAPPER, ENTITY>

所有业务 Service 接口继承 IServiceExt，实现类继承 ServiceExtImpl。它在 MyBatis-Plus ServiceImpl 基础上增强了大量方法。

// 接口
public interface DemoService extends IServiceExt<DemoEntity> { }

// 实现
@Service
public class DemoServiceImpl extends ServiceExtImpl<DemoMapper, DemoEntity>
        implements DemoService { }

IServiceExt 扩展方法清单¶

saveOrUpdateExt 详解（核心方法）¶

增强版保存，相比 MyBatis-Plus 原生 saveOrUpdate 多了以下流程：

saveOrUpdateExt(entity)
  └─ before(entity)              // 前置钩子
       ├─ 填 corpCode            // 当前公司编码
       ├─ 填 innerCode           // 内部编码
       ├─ 序列号注解处理          // @SequenceGenerator 生成单据号
       ├─ @CheckRepeat 重复校验   // 编码唯一性检查
       └─ JSR303 分组校验         // Insert/Update 组校验
  └─ 判断 id 有无
       ├─ 无 id → save（insert）
       └─ 有 id → updateById
  └─ 失败时 catch → rollBackSequenceFieldValue()  // 回滚序列号

指定字段强制写 null¶

MyBatis-Plus 默认不写 null 字段。用第二个参数指定要强制写 null 的字段：

entity.setRemark(null);  // 想把 remark 清空
service.saveOrUpdateExt(entity, Arrays.asList("remark"));  // 强制写 null

before() 钩子（protected，子类可覆写）¶

@Override
protected void before(DemoEntity entity) {
    super.before(entity);  // 先执行默认逻辑
    // 添加自定义前置逻辑
    if (entity.getCode() == null) {
        entity.setCode(generateCode());
    }
}

ServiceExtImpl 内部能力¶

二、序列号生成机制（重点）¶

SDK 提供完整的业务单据号自动生成机制，集成在 saveOrUpdateExt 的 before() 钩子中。

@SequenceGenerator 注解¶

cn.cnbm.bams.common.annotations.sequence.SequenceGenerator（标记在实体字段上）

使用示例¶

@Data
@TableName("bd_unit")
public class BdUnit extends BaseEntity {
    @SequenceGenerator(
        sequenceCode = "UNIT_CODE",      // 对应 pub_sequence 表的 sequenceCode
        datePattern = "yyyyMMdd",         // 含日期
        prefixAviatorScript = "'U'",      // 前缀 U（Aviator 表达式）
        engine = SequenceGenerator.Engines.SPEL  // 或 AVIATOR
    )
    private String unitCode;  // 保存时自动生成
}

生成流程¶

SequenceAnnotationHandler.findAndSetSequenceFieldValue(entity)
  ├─ 扫描实体的 @SequenceGenerator 字段
  ├─ 字段已有值且 alwaysUpdate=false → 跳过
  ├─ 无 tableName → 走 DefaultSequenceStrategy（pub_sequence 表）
  │     └─ sequenceService.next(code, datePattern)
  │         └─ pub_sequence 表自增 currNo + step，支持按 resetType 重置
  ├─ 有 tableName+tableField → 走 BatchSequenceStrategy（表查最大值）
  │     └─ select field from table where field like 'prefix%' order by desc limit 1
  └─ 拼接：prefix + 中间号 + suffix

生成的号格式¶

由 PubSequence.assembleCode() 拼装：

[前缀][分隔符][日期][分隔符][后缀][零填充流水号]

示例：prefix=BM, separator=-, date=20260814, currNo=5, noLength=4 → BM-20260814-0005

pub_sequence 表¶

策略类¶

失败回滚¶

保存失败时 ServiceExtImpl 的 catch 块调用 rollBackSequenceFieldValue() → strategy.rollbackNo → currNo - 1。

三、动态多数据源机制¶

⚠️ 半成品状态：框架已就绪，但缺少 AOP 切面和 Bean 注册。详见 12-FAQ与注意事项。

架构（4 个核心类）¶

DynamicDataSourceContext (ThreadLocal)  ←──业务代码设置数据源 key
        ↓ determineCurrentLookupKey()
DynamicDataSource (继承 AbstractRoutingDataSource)
        ↓ targetDataSources
DataSourceManager (管理器)
        ↓ addDataSource(SysTenantDb)
DataSourceInitService (@TenantDataSource("sys"), 启动时加载)

各类职责¶

当前可用能力¶

• ✅ 启动时从 sys_tenant_db 加载多数据源到路由表
• ✅ 运行时新增数据源 addNewDataSource(config)
• ❌ 缺少 AOP 切面：@TenantDataSource 注解无法自动切换数据源（需手动调 DynamicDataSourceContext.setDataSourceKey()）
• ❌ DynamicDataSource Bean 未注册：无 @Configuration 配置类

四、Session 机制¶

cn.cnbm.bams.service.session.SessionService / SessionServiceImpl

基于 Redis 的自管理 Session（非 HttpSession）。

机制¶

Session 内容¶

方法¶

登录流程（SysUserService.login）¶

1. 按 loginName 查 sys_user
2. 校验状态（非停用）
3. 查 bd_corp 公司信息
4. 密码校验：前端 RSA 公钥加密 → 后端 RSAUtils 私钥解密（兼容明文）
5. 查角色列表，拼 roleName/roleIdList
6. 算 dataScope：超管=DATA_ALL，否则取角色 dataScope 最小值（范围最大）
7. sessionService.createSession() 创建会话

五、CommonServiceImpl —— 通用查询服务¶

cn.cnbm.bams.service.common.CommonServiceImpl

queryCommonData 数据权限¶

// SQL 会被自动改写，加上 corp_code IN (本公司+父公司链) 条件
List<MyEntity> list = commonService.queryCommonData(
    "SELECT * FROM my_table WHERE status = 1", MyEntity.class);
// 实际执行：SELECT * FROM my_table WHERE status = 1
//         AND my_table.corp_code IN ('C001', 'C000')  -- 自动注入

六、其他服务¶

七、业务 Service 接口清单¶

bd 域 —— 基础数据¶

sys 域 —— 系统¶

pub 域 —— 公共¶

八、BaseServiceImpl（统计分析基类）¶

cn.cnbm.bams.service.base.BaseServiceImpl

注意：这个类不继承 IService，与 ServiceExtImpl 是两套独立体系。它面向统计分析/能源计算场景。

提供时间维度计算、同比环比、指标公式计算等能力：

相关文档¶

• 04-实体与数据访问 — BaseEntity / BaseMapperExt
• 07-数据权限 — 数据权限 SQL 改写
• 09-通用功能 — EnergyBaseController 调用 Service
• 12-FAQ与注意事项 — 动态数据源半成品状态