17370845950

通用报表系统采用分层解耦设计：数据层处理查询，展现层负责模板渲染，服务层管理权限与导出；通过动态SQL、参数化查询、模板驱动及元数据配置实现业务方专注“查什么”和“怎么展示”。

报表系统核心设计原则

通用报表系统不是把所有查询逻辑堆在一起，而是分层解耦：数据查询归数据层，模板渲染归展现层，权限和导出逻辑归服务层。重点是让业务方只关心“查什么”和“怎么展示”，不碰SQL拼接或Excel样式代码。

动态SQL与参数化查询统一处理

避免硬编码SQL，用MyBatis的、等标签构建可复用的查询片段；所有外部输入必须走#{}占位符，禁止字符串拼接。对日期范围、多选下拉、模糊搜索等常见条件，封装成通用参数对象（如ReportQuery），字段名与数据库列保持映射一致，后端自动转为对应SQL条件。

• 日期字段统一用LocalDateTime接收，查询前由拦截器自动补上BETWEEN或>= AND
• 枚举类字段（如状态）在DAO层转为数据库值，前端传code，不传中文描述
• 支持“空值忽略”逻辑——参数为null或空集合时不参与WHERE条件

模板驱动的报表渲染机制

用Jinja2风格模板（如JFinal Enjoy）或Apache POI + Freemarker组合，把SQL结果集（List

• 模板文件按报表ID命名（如report_sales_monthly.ftl），存于resources/report-templates/下
• 模板中禁用Java代码块，只允许安全表达式，防止模板注入
• 导出前做字段校验：模板引用的字段必须在数据集中存在，缺失时打warn日志并填空字符串

权限与元数据驱动的报表管理

建一张report_config表，存报表ID、名称、描述、SQL语句（或Mapper路径）、参数配置JSON、可见角色、导出类型等。SQL可存库内（适合DBA管控），也可指向ReportMapper.xml中的id（适合开发迭代）。用户访问报表时，先查配置，再校验角色权限，再解析参数，最后执行查询+渲染。这样新增报表只需配一条记录+写个模板，不用改Java代码。

• 参数配置JSON示例：{"dateRange":"required","deptId":"optional","keyword":"like"}
• 敏感报表（如薪资）SQL加/*+ ROLE_CH

  

  ECK */注释，执行前触发权限钩子校验当前用户是否在HR组
• 提供后台页面增删改报表配置，操作记录进审计日志

基本上就这些。不复杂但容易忽略的是参数清洗、模板容错和配置热加载——上线后别让用户等重启才生效。