02-模块依赖与架构¶

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

https://doc.xpku.com/raw/tech/backend/bams-sdk/02-architecture.md

本篇梳理 bams-sdk 11 个模块的依赖关系、分层架构和技术栈。

1. 模块依赖关系图¶

                    common-tool (底座，无内部依赖)
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
     bams-pojo      common-cache   common-permission
          │                             │
          ▼                             │
     bams-mapper ◄──────────────────────┘
          │
          ▼
     bams-service ◄── tdengine
          │
          ├── common-func (依赖 pojo/cache/permission/tool)
          ├── bams-file   (依赖 mapper/service/func/tool)
          ├── bams-mq     (依赖 pojo)
          └── bams-flow   (依赖 mapper/service/tool)

依赖层次说明¶

层次	模块	依赖
第 0 层（底座）	`common-tool`	无内部依赖。纯工具类 + 注解 + 常量 + 枚举 + 异常 + 响应体
第 1 层（基础）	`bams-pojo`	← common-tool, common-cache
	`common-cache`	← common-tool
	`common-permission`	← common-tool, bams-pojo, bams-service
第 2 层（数据访问）	`bams-mapper`	← bams-pojo（继承 BaseMapperExt 需要 pojo 的 BaseEntity）
第 3 层（业务服务）	`bams-service`	← bams-mapper, common-cache, common-tool, tdengine
第 4 层（功能模块）	`common-func`	← bams-pojo, common-cache, common-permission, common-tool
	`bams-file`	← bams-mapper, bams-service, common-func, common-tool
	`bams-mq`	← bams-pojo
	`bams-flow`	← bams-mapper, bams-service, common-tool

common-tool 是整个 SDK 的底座，所有模块都直接或间接依赖它。它提供了 Dict、JsonResult、BussinessException、Convert 等最基础的类型。

2. 分层架构¶

SDK 遵循经典三层架构，业务应用在此基础上扩展：

┌─────────────────────────────────────────────────────────┐
│  Controller 层                                          │
│  common-func 的 EnergyBaseController<S, E>              │
│  提供 /list /saveOrUpdate /exportToExcel 等 20+ 接口    │
│  + @SysLog 操作日志 / @ValidateToken JWT 校验           │
├─────────────────────────────────────────────────────────┤
│  Service 层                                             │
│  bams-service 的 ServiceExtImpl<M, E>                   │
│  提供 saveOrUpdateExt / listPage / tree / listMap       │
│  + 序列号生成 / 重复校验 / JSR303 校验 / 数据权限       │
├─────────────────────────────────────────────────────────┤
│  Mapper 层                                              │
│  bams-mapper 的 BaseMapperExt<E>                        │
│  继承 MyBatis-Plus BaseMapper + selectPageMaps + SQL    │
│  + SqlInjectorExt 自动注入自定义方法                    │
├─────────────────────────────────────────────────────────┤
│  数据层                                                  │
│  MySQL / 达梦 DM (主数据)                                │
│  TDengine (时序数据)                                     │
│  Redis (缓存/Session)                                    │
│  Kafka (异步消息)                                        │
│  MinIO/RustFS/本地/FTP (文件存储)                        │
└─────────────────────────────────────────────────────────┘

跨层领域分组¶

实体和服务按业务域分组（体现在包路径上）：

域	包路径前缀	含义	典型实体
`bd`	`.bd.`	基础数据	公司(BdCorp)、部门(BdDept)、人员(BdPerson)、岗位(BdPost)、单位(BdUnit)、字典(BdDictionary)
`sys`	`.sys.`	系统管理	用户(SysUser)、角色(SysRole)、资源(SysResource)、配置(SysConfig)、日志(SysLog)、租户库(SysTenantDb)
`pub`	`.pub.`	公共	文件上传(PubFileUpload)、序列号(PubSequence)
`file`	`.file.`	文件管理	FileDO、FileConfigDO、SysFileStorageConfig
`flow`	`.flow.`	流程引擎	SysLiteFlow

3. 跨模块协同关系¶

几个重要的跨模块协作点：

3.1 字段自动填充链¶

common-permission (PermissionContextHolder, ThreadLocal 存 userId)
        │ getCurrentLoginUser()
        ▼
common-func (MyBatisPlusMetaObjectHandler)
        │ insertFill/updateFill
        ▼
bams-pojo (BaseEntity 的 createdBy/updatedBy/createdTime/updatedTime 自动填充)

3.2 数据权限链¶

common-permission (DataPermissionHandlerInterceptor)
        │ 从 Session 取 corpCode/dataScope → PermissionContextHolder
        ▼
common-permission (DataScopeAspect)
        │ Controller 方法切面，按 @CommonData/@RequireDataScope 调整 dataScope
        ▼
common-permission (DataPermissionInterceptor, MyBatis 拦截器)
        │ 拦截 SELECT → JSqlParser 改写 SQL → 注入 corp_code IN(...) 条件
        ▼
bams-service (CommonServiceImpl.queryCommonData)
        │ 也可手动注入权限条件

3.3 Excel 导入导出链¶

common-func (EnergyBaseController /exportToExcel /importExcelData)
        │
        ▼
common-func (ExcelHelper)
        │ @ExcelProperty / @ExcelDictionaryColumn / @ExcelUniqueColumn
        ▼
bams-service (ServiceExtImpl.processImportRowData)
        │ Excel 行数据 → 实体 → saveOrUpdateBatchExt

3.4 文件存储链¶

bams-file (RustFSFileController /upload)
        │
        ▼
bams-file (StorageManager, 多租户路由)
        │ resolve(key) → 按 key 前缀选 Provider
        ▼
bams-file (LocalStorageProvider 或 RustFSStorageProvider)

4. 技术栈清单¶

类别	技术	版本/说明	用于哪个模块
核心框架	Spring Boot	2.x（bams-parent 管理）	所有
ORM	MyBatis-Plus	含 jsqlparser	bams-mapper, bams-service
数据库	MySQL	开发环境	bams-service, common-cache
	达梦 DM	生产环境（DmJdbcDriver18）	bams-service, bams-file
缓存	Redis (Jedis)	连接池	common-cache
	Guava Cache	本地缓存	common-tool (CacheUtils)
	Ehcache		bams-service (CacheService)
消息队列	Kafka (spring-kafka)		bams-mq
文件存储	AWS S3 SDK v2	RustFS/MinIO/OSS 兼容	bams-file
	Apache Commons Net	FTP	bams-file
	JSch	SFTP	bams-file
时序数据库	TDengine	taos-jdbcdriver	tdengine
Excel	FastExcel	原 EasyExcel	common-func, bams-file
API 文档	Knife4j + SpringDoc OpenAPI	v3	common-func
数据库迁移	Flyway		主应用
表达式引擎	Aviator	序列号前后缀、公式计算、条件判断	common-tool, bams-service
工具库	Hutool	通用工具	几乎所有模块
	Guava	缓存/集合	common-tool
	Commons Lang3	字符串/反射	common-tool
	Commons Compress	打包压缩	common-tool
SSH	ganymed-ssh2	远程 Shell 执行	common-tool
	JSch	SFTP	common-tool, bams-file
JSON	Jackson	主力（JsonUtils）	common-tool
	Gson	辅助（GsonUtils）	common-tool
	FastJSON2		bams-pojo, bams-mq
流程引擎	LiteFlow	规则编排	bams-flow
	Warm-Flow	审批工作流	bams-flow

5. 关键设计模式¶

SDK 中使用的主要设计模式：

模式	应用位置	说明
模板方法	`EnergyBaseController` / `AbstractFileClient` / `BaseDataProcessingService`	父类定义骨架，子类实现钩子
策略	文件存储（5 种 FileClient）、序列号（Default/Batch Strategy）、FileStorageEnum	可插拔实现
工厂	`FileClientFactory` / `SequenceStrategyFactory`	按配置创建实例
拦截器	`DataPermissionInterceptor`(MyBatis) / `FieldValueFormatInterceptor` / `TraceLogInterceptor`(Spring)	AOP 式增强
观察者	`RefreshRedisEvent` (Spring ApplicationEvent)	缓存刷新广播
路由	`DynamicDataSource` (AbstractRoutingDataSource) / `StorageManager`	按上下文选择目标
建造者	ikidou `TypeBuilder` / `FilePresignedUrlRespDTO`	链式构造

6. 相关文档¶