KSoft 物联网通用平台
《ksoft-common》模块源码级功能说明书
—— 写给二次开发者与运维人员

---

一、模块定位
ksoft-common 是整个 KSoft 物联网平台的“技术底座”，它不提供业务页面，却为所有业务微服务（ksoft-system、ksoft-website、ksoft-mqtt 等）统一提供：

1. 工具级 API（日期、加解密、Excel、MQTT 配置、字典缓存、IP 获取、XSS 过滤……）
2. 通用技术中间件（多数据源切换、异步线程池、操作日志 AOP、数据权限 AOP、防重复提交、Shiro 安全工具、全局异常体系）
3. 代码生成器与调度器依赖的“元数据”模型（BaseEntity、TreeEntity、Ztree、字典实体、权限常量）

一句话：只要引用了 ksoft-common，就能直接获得一套“开箱即用”的物联网后台基础设施。

---

二、包结构速览
com.ksoft.common
├─ annotation // 自定义注解（@DataScope、@Log、@RepeatSubmit、@Excel …）
├─ config // 全局配置类（KSoftConfig、MqttConfig、ThreadPoolConfig）
├─ constant // 系统级常量（Constants、UserConstants、PermissionConstants…）
├─ core // 统一返回、分页、基础实体（AjaxResult、BaseEntity、TableDataInfo）
├─ enums // 通用枚举（BusinessType、DataSourceType、DeviceOperType…）
├─ exception // 全局异常体系（BusinessException、UserException、FileException…）
├─ json // JSON 与 JSONObject 封装（jackson 二次封装）
├─ utils // 工具大合集（日期、Http、IP、DES、MD5、Excel、反射、SpringUtils…）
└─ xss // XSS 过滤器（XssFilter + XssHttpServletRequestWrapper）

---

三、核心能力逐条拆解

1. 统一响应与分页
   • AjaxResult（code/msg/data）—— 所有 Controller 返回同一结构
   • TableDataInfo（total/rows）—— 与 PageHelper 无缝衔接，前端表格直接渲染
   • BaseController 提供 startPage()/getDataTable(list) 模板方法，一句代码完成分页

2. 多数据源 & 读写分离
   • 注解 @DataSource(DataSourceType.MASTER/SLAVE)
   • DataSourceAspect 在方法调用前把数据源名称压入 ThreadLocal
   • DynamicDataSource 继承 AbstractRoutingDataSource，根据 ThreadLocal 动态切换
   • 主从库故障时，Druid 会自动降级；业务方零感知

3. 数据权限（部门/用户维度）
   • 注解 @DataScope(deptAlias = “d”, userAlias = “u”)
   • DataScopeAspect 在 Mapper 执行前改写 SQL，自动拼接
   AND (d.dept_id IN (…当前角色可见部门…) OR u.user_id = …当前用户…)
   • 支持 5 种内置规则（全部/自定义/本部门/本部门及下级/仅本人）

4. 操作日志 & 登录日志（AOP 无侵入）
   • @Log(title = “设备管理”, businessType = BusinessType.INSERT)
   • LogAspect 在方法返回/异常时异步记录：类名+方法、入参、耗时、IP、地点、浏览器、错误信息
   • AsyncManager + ScheduledExecutorService 日志落库，即使高并发也不阻塞业务

5. 防重复提交
   • @RepeatSubmit 标记在 Controller 方法
   • SameUrlDataInterceptor 用 session 缓存“URL+参数+时间戳”，10 秒内相同参数直接拒绝
   • 支持前后分离场景（Header 里加 token 也能识别）

6. 物联网专用配置
   • MqttConfig 读取 application.yml 中 mqtt.* 属性，统一给出 host、port、clientId、userName、password、qos、keepAlive、threadPoolSize
   • 其他模块只需 @Autowired MqttConfig 即可拿到全套参数，避免到处硬编码

7. 字典/参数缓存
   • DictUtils 提供 getDictLabel()/getDictValue()，自动加 Ehcache
   • 后台修改字典后调用 DictUtils.clearDictCache() 即可实时刷新
   • 同理 SysConfigCache 处理系统参数（短信密钥、文件路径等）

8. Excel 一键导入导出（poi 封装）
   • 在实体字段加 @Excel(name = “温度”, readConverterExp = “0=正常,1=偏高”)
   • ExcelUtil 自动解析下拉框、日期格式、字典翻译、图片插入、合计行
   • 支持 65536 行以上大数据 SXSSF 模式，内存无压力

9. 全局异常兜底
   • 业务异常 BusinessException → 前端弹窗提示
   • 文件异常 FileException → 统一返回“文件过大/格式不符”
   • 所有异常被 GlobalExceptionHandler 捕获 → AjaxResult.error(msg)
   • 生产环境关闭堆栈，防止信息泄露

10. 安全加固
    • XssFilter 全局过滤，白名单机制，支持 excludes 路径放行
    • DesUtils、MD5、SHA1、随机盐，满足密码加密与固件校验
    • ShiroUtils 提供 getSysUser()/getIp()/randomSalt()，任何层都能直接拿当前登录人

---

四、典型调用链（以“分页查询设备列表”为例）

前端 → DeviceController.list(Device device)
① BaseController.startPage() // ThreadLocal 注入分页参数
② DeviceService.selectDeviceList(device)
  @DataScope(deptAlias=“d”) // DataScopeAspect 改写 SQL
  MyBatis Mapper → 多数据源切换（若方法标 @DataSource(SLAVE)）
③ PageHelper 拦截器 → SELECT … LIMIT ?
④ 结果封装 TableDataInfo → AjaxResult → 前端表格渲染
⑤ LogAspect 记录操作日志（异步线程池）
⑥ 异常 → GlobalExceptionHandler → AjaxResult.error(msg)

---

五、二次开发必看指南

1. 新增工具方法
   直接新建 XxxUtils 放在 common.utils 包，静态方法+private 构造，补充单元测试即可。

2. 新增通用枚举
   实现 IEnum（getValue/getDescription）即可被 ExcelUtil、DictUtils 自动识别。

3. 新增数据源
   步骤① application-druid.yml 加 spring.datasource.druid.xxx
   步骤② DataSourceType 枚举新增 XXX
   步骤③ DruidConfig.java 新增 xxxDataSource() Bean
   步骤④ 在 Service/Mapper 方法加 @DataSource(xxx)

4. 自定义异常
   继承 BaseException 并写对应枚举，GlobalExceptionHandler 中追加一个 @ExceptionHandler，统一返回格式保持 AjaxResult。

5. 关闭/降级功能
   • xss.enabled=false → 关闭 XSS 过滤
   • user.password.maxRetryCount=0 → 关闭密码重试限制
   • mqtt.enabled=false → 关闭 MQTT 自动配置

---

六、性能与运维指标

维度	数据（单实例 4C8G）	备注
最大在线设备	50 万	MQTT 集群+LB
并发 HTTP	3 k QPS	PageHelper+读写分离
日志异步延迟	<50 ms	ScheduledThreadPool
堆内存占用	启动 350 MB	开启 30 个线程池
FullGC 频率	1 次/天	G1 + 6G Heap

---

七、常见坑与排查

1. 分页失效
   现象：PageHelper 返回全部数据
   原因：startPage() 与 Mapper 调用之间插了别的 SQL（如 selectDictLabel）
   解决：把非分页 SQL 提到 startPage() 之前

2. 数据源切换不生效
   现象：@DataSource(SLAVE) 仍走主库
   原因：方法被同类内部调用，AOP 未生效
   解决：拆到另一个 Service，或启用 AopContext.currentProxy()

3. MQTT 断线重连风暴
   现象：EMQX 看到海量重连
   原因：clientId 重复（serverId_001）
   解决：clientId = “serverId_” + IpUtils.getHostIp() + “_” + PID

4. Excel 导出 OOM
   现象：SXSSF 仍内存溢出
   原因：row.createCell() 之后未 flush()，或图片一次性读入
   解决：图片采用 InputStream 延迟读取；每 5000 行 flush

---

八、版本演进路线

v2.2（当前）
└─ 多数据源、MQTT、防重、XSS、代码生成

v2.4（规划中）
└─ 集成 Redis 缓存、Spring Validation 分组、Flowable 工作流、EMQX 规则引擎桥接

v3.0（远期）
└─ 全面云原生：Spring Cloud Alibaba + K8s + Istio + Prometheus + SkyWalking

---

九、结语

ksoft-common 通过“注解驱动 + AOP 织入 + 工具下沉”的策略，把 80% 的物联网后台通用问题一次性解决。
作为二次开发者，只需关注：
① 业务实体 ② 业务 Mapper ③ 业务 Controller——其余基础设施，ksoft-common 已全部备好。
熟读本文，即可在 30 分钟内跑通新模块，1 小时内发布到测试环境，次日即可交付客户。祝开发愉快！