09-通用功能 common-func¶

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

https://doc.xpku.com/raw/tech/backend/bams-sdk/09-common-func.md

common-func（29 个类）是 Spring Boot 应用的全局基础设施层：基础 Controller、AOP 注解、全局异常处理、Web 配置、Swagger、Excel 导入导出、MyBatis 字段拦截器、链路追踪。

一、EnergyBaseController —— 基础 CRUD Controller（核心）¶

cn.cnbm.bams.common.func.controller.EnergyBaseController<SERVICE, ENTITY>

泛型约束：<SERVICE extends IServiceExt<ENTITY>, ENTITY extends BaseEntity>。通过反射自动获取泛型类型并从 Spring 取 Bean。

继承它，你的 Controller 自动获得全套 REST 接口：

@RestController
@RequestMapping("/demo/product")
public class ProductController
        extends EnergyBaseController<ProductService, Product> {
    // 空的！全套接口已由父类提供
}

自动获得的接口¶

写操作带 @SysLog（自动记录操作日志），查询带 @TransProperty（属性翻译）。

自定义扩展¶

@RestController
@RequestMapping("/demo/product")
public class ProductController extends EnergyBaseController<ProductService, Product> {

    // 自定义接口，与父类接口共存
    @PostMapping("/custom")
    @SysLog  // 自定义接口也可加操作日志
    public JsonResult custom(@RequestBody Product product) {
        getService().saveOrUpdateExt(product);
        return JsonResult.success(product);
    }
}

二、@SysLog —— 操作日志 AOP¶

cn.cnbm.bams.common.func.annotation.SysLog + cn.cnbm.bams.common.func.aop.SysLogHandler

Controller 方法加注解，自动记录操作日志到 sys_log 表。

@PostMapping("/delete/{id}")
@SysLog  // 自动记录
public JsonResult delete(@PathVariable String id) { ... }

记录内容¶

三、@ValidateToken —— JWT 校验 AOP¶

cn.cnbm.bams.common.func.annotation.ValidateToken + ValidateTokenAnnotationHandler

Controller 方法加注解，强制 JWT 校验。从请求头取 Authorization，JwtUtil.verify 失败返回 JsonResult.fail(403, "禁止访问")。

@PostMapping("/sensitive")
@ValidateToken  // 强制 JWT 校验
public JsonResult sensitive() { ... }

四、全局异常处理¶

cn.cnbm.bams.common.func.config.ExceptionHandlerConfig（@ControllerAdvice）

所有异常先 log.error 打印。前端收到的统一是 JsonResult 格式。

五、全局配置¶

CORS（CoreConfig）¶

cn.cnbm.bams.common.func.config.CoreConfig（@Configuration @EnableWebMvc）

全局 CORS：addMapping("/**")，允许所有 origin/method/header，allowCredentials(true)，maxAge 3600。

Jackson（MyWebMvcConfigurer）¶

cn.cnbm.bams.common.func.config.MyWebMvcConfigurer

文件上传限制¶

静态资源¶

映射 /doc.html、/webjars/**、/favicon.ico、/swagger-ui/**（Knife4j/Swagger UI）。

六、Swagger / Knife4j¶

cn.cnbm.bams.common.func.config.Knife4jOpenApiCustomizer

• 修复 Spring Boot 3.4+ /v3/api-docs 兼容问题（issue #913）
• 扫描 @ApiSupport 注解的 RestController，把 order 值写入 tag 的 x-order，实现接口分组排序

SwaggerProperties¶

springdoc:
  swagger:
    title: "BAMS API"
    description: "接口文档"
    author: "开发团队"
    version: "2.0"
    url: "https://example.com"
    email: "dev@example.com"

七、版本信息¶

cn.cnbm.bams.common.func.config.VersionAutoConfiguration + VersionController

• 默认启用（project.version.enabled，matchIfMissing=true）
• 暴露 GET {project.version.path:/version}
• 读 classpath:version.json，返回 VersionInfo（version/buildTime/commitTime/author/commitHash）

GitInfoController¶

GET /dac/gitInfos：从 git.properties 读 git 构建信息（branch/commit/build time）。

八、Excel 导入导出（ExcelHelper）¶

cn.cnbm.bams.common.func.helper.ExcelHelper

基于 FastExcel（原 EasyExcel）的导入导出工具。

实体注解¶

导出示例¶

// 导出：用 TableData 动态表头
TableData data = new TableData();
data.setExportName("产品列表");
data.setTableHeaders(headers);  // 支持多级嵌套表头
data.setData(dataList);         // List<Map> 数据
data.setHeaderColor("#4384C7"); // 表头颜色
excelHelper.exportToExcel(data, response);

导入示例¶

// 导入：自动按 @ExcelProperty 映射，支持 @ExcelUniqueColumn 去重
List<Product> list = excelHelper.importExcelData(file, Product.class);
// ServiceExtImpl.processImportRowData 也支持更灵活的映射

模板生成¶

// 生成导入模板（含字典下拉）
excelHelper.generateTemplate(Product.class, response);

自动列宽¶

AutoColumnWithStyleStrategy：按内容字节长度自动设置列宽（最大 255）。

字典下拉¶

SelectColumnHandler：为字典列创建 Excel 数据验证下拉框，引用隐藏的"附件-字典"sheet。

九、字段拦截器（MyBatis）¶

@FieldValueFormat —— 字段格式化¶

cn.cnbm.bams.common.func.interceptors.ibatis.FieldValueFormatInterceptor

拦截 INSERT/UPDATE，对标记 @FieldValueFormat 的 String 字段执行格式化。

@FieldValueFormat(trim = true)  // 前后去空格
private String name;

@FieldValueFormat(replaceRegex = "\\s+", replaceReplacement = "")  // 去所有空白
private String code;

@RedisCache —— 查询后 Redis 回填¶

cn.cnbm.bams.common.func.interceptors.ibatis.FieldValueRedisCacheInterceptor

拦截查询结果集，对标记 @RedisCache 的字段从 Redis 取值回填。

@RedisCache(
    key = "user:{id}",      // key 模板，{字段名} 占位
    jsonKey = "userName",   // 从 Redis JSON 取这个子键
    redisType = "1"         // "1"=getObject, 其他=hget
)
private String userName;    // 查询后自动从 Redis 填充

十、链路追踪¶

cn.cnbm.bams.common.func.log.TraceLogInterceptor + TraceLogBeanRegistry

• preHandle：生成 UUID（无横线）→ request attribute TRACE_ID + SLF4J MDC.put("TRACE_ID", traceId)
• afterCompletion：响应头写 Trace-Id + MDC.remove

日志配置¶

在 logback 配置中加 %X{TRACE_ID} 即可输出 traceId：

<pattern>%d{yyyy-MM-dd HH:mm:ss} [%X{TRACE_ID}] %-5level %logger{36} - %msg%n</pattern>

十一、表达式求值（Aviator）¶

cn.cnbm.bams.common.func.Evaluator

基于 Aviator 表达式引擎。

公式解析器¶

十二、字段自动填充（MetaObjectHandler）¶

cn.cnbm.bams.common.func.sequence.MyBatisPlusMetaObjectHandler（@Component）

继承 bams-pojo 的 EnergyMetaObjectHandler，实现 getCurrentLoginUser() 从 PermissionContextHolder 取 userId。

insertFill:
  ├─ id 为空 → IDUtil.getId()
  ├─ createdTime/updatedTime → 当前时间
  └─ createdBy/updatedBy → PermissionContextHolder 的 userId

updateFill:
  ├─ updatedTime → 当前时间
  └─ updatedBy → userId

这是 BaseEntity 审计字段自动填充的实际实现。详见 04-实体与数据访问。

十三、自动建表¶

cn.cnbm.bams.common.func.config.SystemSettingsProperties

spring:
  settings:
    enable-table-auto-creation: true  # 首次启动自动建表（默认 true）

相关文档¶

• 01-快速开始 — EnergyBaseController 三行代码示例
• 04-实体与数据访问 — BaseEntity 自动填充
• 05-业务服务层 — ServiceExtImpl（EnergyBaseController 调用）
• 07-数据权限 — PermissionContextHolder
• 06-文件管理 — SysFileStorageConfigController 继承 EnergyBaseController