跳转至

BAMS-SDK 开发包文档

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

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

BAMS-APEX v2.0 后台开发基础 SDK —— 中国建材集团（CNBM）智能制造产品线统一的 Java 后端开发基础模块，包名 cn.cnbm.bams，Java 21。

本套文档基于 bams-sdk 仓库 dev 分支（比 main 领先 54 个提交，含最新的 bams-flow 流程引擎模块）的真实源码精读编写，所有类名、方法签名、配置项均来自源码，不编造。

SDK 是什么

bams-sdk 是 BAMS-APEX 平台的共享 SDK 聚合模块（Maven 多模块项目，packaging=pom），本身不含业务逻辑，把以下 11 个子模块聚合起来给业务应用（如 bams-apex 主应用、各定制项目）引用。它沉淀了部门后台开发的通用能力：数据访问增强、统一响应、数据权限、文件管理、缓存、消息队列、Excel 导入导出、流程引擎、时序数据库等。

  • 父工程：bams-parent（groupId cn.cnbm.bams，version 2.0）
  • Java 版本：21
  • 核心框架：Spring Boot 2.x / MyBatis-Plus / Redis / Kafka / MinIO / TDengine

模块一览（11 个模块）

# 模块 职责 Java 类数 代码行数 文档
1 common-tool 通用工具库：日期/JSON/加密/HTTP/树/Excel/ID/响应/异常等 104 个工具类 104 10,675 03-通用工具库
2 bams-pojo 共享实体（POJO）/DTO/VO/MyBatis 类型处理器/Redis 事件 50 3,928 04-实体与数据访问
3 bams-mapper 数据访问层 + MyBatis-Plus 增强（BaseMapperExt/SqlInjectorExt） 30 819 04-实体与数据访问
4 bams-service 业务服务层：ServiceExtImpl 基类/序列号/动态数据源/Session/业务 Service 70 5,409 05-业务服务层
5 common-func 通用功能：EnergyBaseController/@SysLog/异常处理/Swagger/Excel/字段拦截器 29 3,040 09-通用功能
6 common-cache Redis 缓存基础服务 + 基于 bd_cache 配置表的缓存自动加载框架 12 1,442 08-缓存与消息
7 common-permission 数据权限框架：MyBatis 拦截器 SQL 改写 + 6 级数据范围 + 权限上下文 13 916 07-数据权限
8 bams-mq Kafka 消息队列：生产者/消费者/数据处理模板 4 148 08-缓存与消息
9 bams-file 文件管理：StorageProvider(本地+RustFS) + FileClient(保留) + Excel 转换 61 4,535 06-文件管理
10 bams-flow 流程引擎：LiteFlow 规则编排 + Warm-Flow 审批流 31 — 10-流程引擎
11 tdengine TDengine 时序数据库封装：DDL/批量写入/查询 10 1,730 11-TDengine时序库

合计约 414 个 Java 类，约 3.7 万行代码。

按场景导航

我要做... 看这几篇
快速集成 SDK，跑起来 01-快速开始
了解整体架构和模块依赖 02-模块依赖与架构
做 CRUD（增删改查/分页/树） 04-实体与数据访问 + 05-业务服务层 + 09-通用功能
用工具类（日期/JSON/加密等） 03-通用工具库
做文件上传/下载 06-文件管理
实现数据权限（按公司/部门过滤） 07-数据权限
用 Redis 缓存 / Kafka 消息 08-缓存与消息
做 Excel 导入导出 09-通用功能（ExcelHelper 章节）
做审批流 / 规则编排 10-流程引擎
操作时序数据（设备测点） 11-TDengine时序库
生成业务单据号 05-业务服务层（序列号机制章节）
多租户数据源 05-业务服务层（动态数据源章节）
查已知坑和注意事项 12-FAQ与注意事项

文档清单

  1. 01-快速开始 — 集成接入、Maven 依赖、最小配置、HelloWorld 示例
  2. 02-模块依赖与架构 — 11 模块依赖关系图、分层架构、技术栈
  3. 03-通用工具库 — 104 个工具类详解
  4. 04-实体与数据访问 — BaseEntity / BaseMapperExt / 实体清单
  5. 05-业务服务层 — ServiceExtImpl / 序列号 / 动态数据源 / Session
  6. 06-文件管理 — StorageProvider + FileClient + Excel 转换
  7. 07-数据权限 — SQL 改写 / 6 级数据范围 / 注解
  8. 08-缓存与消息 — Redis 缓存框架 / Kafka
  9. 09-通用功能 — EnergyBaseController / @SysLog / 异常处理
  10. 10-流程引擎 — LiteFlow + Warm-Flow 双引擎
  11. 11-TDengine时序库 — 时序数据 DDL/写入/查询
  12. 12-FAQ与注意事项 — 异常双轨制 / JSON 三套 / 已知坑

版本与源码

项 值
仓库 https://git.cnbmtech.com/CNBM-CIMS/products/bams-apex/bams-sdk
分支 dev（开发主线，最新）
父工程 bams-parent:2.0
groupId cn.cnbm.bams
Java 21
最近提交 f69504a 2026-08-12 lijinpeng: Merge branch 'feature/task-19550-规则引擎' into dev