通用报表系统采用分层解耦设计：数据层处理查询，展现层负责模板渲染，服务层管理权限与导出；通过动态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代码。
立即学习“Java免费学习笔记（深入）”；
- 参数配置JSON示例：
{"dateRange":"required","deptId":"optional","keyword":"like"} - 敏感报表（如薪资）SQL加
/*+ ROLE_CHECK */注释，执行前触发权限钩子校验当前用户是否在HR组 - 提供后台页面增删改报表配置，操作记录进审计日志
基本上就这些。不复杂但容易忽略的是参数清洗、模板容错和配置热加载——上线后别让用户等重启才生效。
