简介UReport是一款基于Java的开源报表工具支持PDF、Excel、Word等多种格式输出广泛用于数据报表生成与商业智能展示。文档将UReport使用demo与使用手册合二为一面向需要快速上手的Java后端开发者和报表设计人员从Maven依赖引入、Spring Boot集成、数据源配置、报表模板设计到常见问题排查均有讲解并配有可直接参考的配置示例可帮助读者避开配置雷区、快速搭建可用环境。包体为单个doc文件大小约1.15MB全部内容集中在一个文档中结构清晰适合边查边做。文档还介绍了UReport在表格、柱状图、折线图等模板上的灵活设计以及它在报表生成、数据分析、商业智能等场景中的最佳实践与常见问题处理思路。目前已有5684人学习下载适合正在选型或需要在项目中落地UReport的团队参考。1. UReport 是什么为什么 Java 业务系统做报表还得靠它报表引擎这东西听起来像是上个时代的产物但真正被业务方追着要报表的时候UReport 这套「服务端设计器 Web 预览」的路子反而比前端报表组件省心得多。它把报表模板、数据集、表达式引擎和导出能力全部收敛到 Java 服务里业务系统只要引入一个依赖就能打开在线设计器拖拽字段出报表再导出成 PDF 或 Excel 交出去。这篇使用笔记就是写给正在 Java 项目里被报表需求卡住的人——不需要懂前端不需要单独部署报表服务从最小 demo 开始把整条链路跑通再一步步补齐数据源、参数、导出的细节。我尽量按实际落地时踩过的顺序来讲有的配置看起来不起眼真正调的时候能救你一命。2. 从零搭一个可运行的 UReport Demo依赖、配置与最小工程2.1 引入一个依赖就够ureport-console 的 pom 写法在 Spring Boot 工程里集成 UReport常见做法是引入一个ureport-console的依赖就行。它会把服务端设计器页面、Servlet、表达式引擎、导出组件一起带到 classpath 里不需要再单独配置前端资源目录。pom.xml 里这样写dependency groupIdcom.bstek.ureport/groupId artifactIdureport-console/artifactId version2.2.x/version /dependency这里版本号我用2.2.x代替是因为不同小版本之间的差异集中在 bug 修复上集成方式基本一致不用为某个具体小版本纠结。你只要确保拉到的实际版本是 2.x 这条线就行1.x 和 2.x 之间配置方式差异比较大别把网上搜到的 1.x 配置直接往工程里套。其次要注意 Spring Boot 版本与这个依赖的兼容性。常见组合是 Spring Boot 2.x 配 UReport 2.x如果你的工程已经升到 Spring Boot 3.xServlet 的初始化方式变了直接按这里的写法大概率会报类型不匹配或找不到ServletRegistrationBean。所以稳妥起见先在一个独立的 Spring Boot 2.x demo 工程里跑通再决定要不要回头适配老项目。引入依赖后Maven 会自动带进一堆传递依赖包括 Apache Commons、POI 等导出组件。如果工程里原本已经用了 POI 的旧版本这里可能发生冲突典型现象是报表导出 Excel 时报NoClassDefFoundError。遇到这种情况把工程里其它 POI 依赖的版本统一到 UReport 传递进来的版本即可具体版本号看 Maven 依赖树的实际结果。2.2 通过 Servlet 注册把服务端设计器接进 Spring Boot依赖引进来之后UReport 的设计器并不是一个现成的 Controller而是通过一个 Servlet 对外提供服务。所以第一步要做的是把它的 Servlet 注册到 Spring Boot 的容器里。我一般单独写一个配置类来做这件事import com.bstek.ureport.console.UReportServlet; import org.springframework.boot.web.servlet.ServletRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.ImportResource; Configuration ImportResource(classpath:ureport-console-context.xml) public class UReportConfig { Bean public ServletRegistrationBeanUReportServlet ureportServlet() { ServletRegistrationBeanUReportServlet registration new ServletRegistrationBean(); registration.setServlet(new UReportServlet()); registration.addUrlMappings(/ureport/*); registration.setLoadOnStartup(1); return registration; } }这段代码里有两个关键动作。ImportResource会把 UReport 自带的一个 Spring 配置文件ureport-console-context.xml加载进来这个文件里定义了报表引擎核心对象报表渲染器、数据源管理器、模板存储服务等。少了这一行即使 Servlet 注册成功设计器页面也会打开但内部接口全部报 404 或空指针。ServletRegistrationBean则把 UReport 的 Servlet 挂到/ureport/*这个路径上。注意路径后面的星号不能丢因为设计器页面、导出接口、数据集调试接口都在这个路径下面。loadOnStartup设为 1是为了让这个 Servlet 随应用启动就初始化而不是等到第一次请求才创建能省去第一次打开设计器时多等几秒的问题。如果你在配置类里同时配了拦截器或过滤器记得把/ureport/**加入排除名单。否则登录拦截器会把设计器页面和报表预览接口全部挡掉表现就是报表集成进去了但外网访问时永远跳登录。这一步是很多团队集成半天打不开页面的主要原因。2.3 启动后先做三件最小验证设计器、模板、静态预览工程启动成功后浏览器访问http://localhost:8080/ureport/designer能看到服务端设计器的主界面这是第一层验证。如果这层通过了说明 Servlet 注册和 Spring 上下文加载都没问题。第二层验证是新建一张空白报表模板。在设计器里新建一个模板拖入任意单元格写几个固定值保存一次确认模板文件能正常写进存储目录。这个步骤看着简单实际上能暴露存储路径不存在、文件夹没有写权限等问题。保存报错时优先去控制台看异常堆栈大概率是文件系统路径问题跟报表表达式无关。第三层验证是静态预览不接任何数据源在单元格里写上固定文本比如「报表链路正常」点预览能在新窗口看到这张静态表。这一步过了说明从模板到渲染再到预览的整条链路是通的后面再往上加数据源和数据集出了问题就能把排查范围直接缩小到数据环节不至于整条链路一起找。这三件事做完你的最小 demo 工程就立住了。接下来要做的才是真正有业务价值的部分让报表能读到真实数据。3. 给 UReport 接上业务数据数据库数据源与 Bean 数据源3.1 在服务端设计器里建数据库连接一张参数表讲清UReport 的数据源分几种类型最直接的是数据库数据源。在设计器左侧的「数据源」区域新建数据源选择数据库类型然后填写连接参数。以 MySQL 为例关键参数如下参数填写内容备注数据源名称任意英文名建议包含业务含义如 order_ds数据库类型MySQL选择错误时会给出一堆默认参数别被误导JDBC 驱动类com.mysql.cj.jdbc.Driver8.x 驱动旧库可能要用 com.mysql.jdbc.DriverJDBC URLjdbc:mysql://127.0.0.1:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai时区不写时间字段容易差 8 小时用户名实际数据库账号建议专门给报表建只读账号密码实际密码测试环境可以用明文生产环境建议走配置中心这里的表格对应设计器里的表单页。填完之后一定要先点「测试连接」按钮再点保存。测试连接通过说明 JDBC 驱动、URL、账号密码这一整套参数没问题能省掉后面大量不确定性。有一点要特别提醒UReport 的数据源参数一旦保存就会写进它自己的存储位置具体存在文件还是数据库取决于你选的存储配置。如果你在本地 demo 阶段随便填了一个临时库连接后面项目里直接沿用很容易把测试库数据导进生产报表。我习惯在数据源名称里直接带环境后缀比如order_ds_prod看到名字就知道它连的是哪套环境。数据库连接池的相关参数比如最大连接数、初始连接数在设计器里也有一栏可以填。对于报表这种读多写少的场景最大连接数一般不用调太高20 就足够。真正的瓶颈通常不在连接数而在 SQL 查询效率和返回数据量这个放到后面避坑章节专门讲。3.2 从数据源建数据集拿到字段才算通数据源建好后下一步是在这个数据源下面创建数据集。数据集本质上就是一条 SQL 查询UReport 靠它把数据库里的行数据映射成报表能引用的字段集合。在数据源的「数据集」区域选择新建数据集名称用英文SQL 里可以直接写多表关联查询。这里我一般会先用一条最简单的查询确认链路比如select order_id, customer_name, order_amount, order_date from t_order order by order_date desc limit 10先写这条限制 10 行的 SQL点「测试」或者「预览数据集」看返回字段列表和示例数据是否正常。这一步能确认三件事一是 SQL 本身语法没问题二是账号对这张表有查询权限三是字段名和报表里要用的名字对得上。数据集测试通过后在设计器右侧的「数据集」面板里就能看到这些字段了。后面拖拽单元格时直接从这里拖字段到表格区域。这里有一个实际使用中的细节数据集名称不要用中文也不要用带空格的名称。报表模板文件是 XML 格式字段引用会以dataset_name.field_name的形式出现一旦名称里有特殊字符表达式解析很容易出边界问题。我见过因为数据集名称叫订单明细2024导致表达式整段无法解析的情况改回order_detail后一切正常。此外数据集的 SQL 是可以引用参数的比如按时间范围过滤。参数通过报表 URL 传入或者在数据集查询条件里绑定到表单控件。但参数传递的配置链路比常规查询复杂新手阶段建议先把无参数数据集跑通再往后加过滤条件不要一上来就做带参数的报表问题会交叉在一起很难定位。3.3 接已有 Service 用 Bean 数据源报表不用写 SQL数据库数据源适合简单查询但业务系统的报表需求很少只是单表查询更多情况是要复用已有服务的复杂计算逻辑。这时候再把 SQL 写进模板等于把业务逻辑分散到了报表文件里后续改逻辑要跑到设计器里改 SQL非常被动。更好的方式是用 Bean 数据源。UReport 支持在报表里直接调用一个 Spring Bean 的方法方法返回ListMapString, Object报表就能拿到字段。代码长这样Component(orderReportData) public class OrderReportData { private final JdbcTemplate jdbcTemplate; public OrderReportData(JdbcTemplate jdbcTemplate) { this.jdbcTemplate jdbcTemplate; } public ListMapString, Object load(String startDate, String endDate) { return jdbcTemplate.queryForList( select order_id, customer_name, order_amount, order_date from t_order where order_date between ? and ?, startDate, endDate ); } }对应到设计器里新建数据源时选择「Bean 数据源」Bean 名称填orderReportData方法名填load再按顺序传入startDate和endDate两个参数。方法返回的Map的 key 就是报表可引用的字段名。用这种方式报表模板不感知 SQL 细节只认字段名字。业务查询逻辑放回 Service 层可以单测、可以复用也能被 service 层统一的事务和缓存管理。我在实际项目里几乎都是这个套路数据库数据源只用来做临时分析所有正式报表一律走后端 Service。缺点也很明显就是每次报表要加字段都要改 Java 方法返回的 Map再重新发布应用。所以遇到字段经常变的需求我会评估一下如果不是太频繁用 Bean 数据源值得如果业务方隔三差五要加展示列那还是老老实实地用数据库数据源把 SQL 交给报表维护人员去改。4. 做第一张可导出的 UReport 报表单元格、表达式与导出4.1 用拖拽完成单元格绑定明细表 30 秒成型数据源就绪后新建一张空白报表模板左侧能看到数据集字段树。把order_id、customer_name、order_amount、order_date依次拖入单元格每个字段默认放在一个单元格里。拖进去之后选中单元格在属性面板确认扩展方向。明细表格最重要的是扩展方向。比如order_id放在主格方向设为向下扩展那其它字段如果也是逐行显示就应该设置为跟随主格扩展而不是各自独立扩展。如果方向设置错了常见现象是一列只有一行数据或者多列数据错位对不上。这里我给个具体步骤参考新建空白报表把数据集的四个字段依次拖到 A2、B2、C2、D2 单元格。在第一行写表头订单号、客户名称、金额、日期放在 A1 到 D1。选中 A2 到 D2 这一行检查扩展方向是否正确方向朝下。在单元格属性里把日期字段的显示格式设为yyyy-MM-dd。点预览确认能看到多行数据按顺序展开。这一步不要跳过因为大部分报表新人第一次预览时看到的是只有一行数据的效果往往第一反应是报表引擎坏了其实只是扩展方向没设对。4.2 表达式计算合计sum(E2) 和它背后的机制明细表出来之后下一步通常是加合计行。在明细区域下方找一个空白单元格作为合计单元格输入一段表达式这是报表工具和普通表格软件的关键差异——它操作的是「扩展后的单元格集合」。sum(E2)这里以金额列在 E2 为例。sum(E2)的意思是对 E2 这个单元格扩展后产生的所有数值单元格做求和而不是只对一个格子求和。如果你写成E2 1那它只对第一个明细行的金额做运算合计就完全不对了。输入表达式时要注意单元格内容以等号开头且单元格类型要设置为「表达式」。这一步很关键UReport 的单元格类型有文本、表达式、图片等几类默认可能是纯文本符号写对了也不会计算只会原样显示。选中单元格在属性面板里改类型再预览合计就出来了。表达式能做的事不止求和。如果想统计总行数可以用count(C2)想取最大值可以用max(E2)。这些函数名和 Excel 基本一致但作用对象从单值变成了「扩展后的单元格集合」。理解这一点比背十个函数都有用。合计行本身也可以加样式比如在属性面板里把字体加粗、背景色加深。样式只会影响展现不影响计算放心调。4.3 导出 PDF 和 Excel分页、纸张与常见参数报表在公司里真正被高频使用的是导出因为大多数场景是把 Excel 发给财务或业务而不是让人每天打开系统看。UReport 的预览页面工具栏自带导出按钮支持 PDF、Excel、Word 三种格式。但导出前有参数需要先确认。第一次导出 PDF 时我建议先查这几个设置参数位置建议值纸张大小页面设置A4除非业务明确要求其它尺寸导出方向页面设置列多选横向行多用纵向分页方式页面设置按固定行数分页默认即可缩放比例导出选项100%先不调这些设置直接影响导出 PDF 的页数。列数多的时候不调横向导出内容会被截断成两页第一页只有一半表格第二页是剩下一半业务方拿到基本没法用。Excel 导出相对简单它不依赖分页设置但要注意字段类型。比如日期字段如果没设显示格式Excel 里可能是原始时间戳数字需要业务方自己改格式。所以在设计器里就把日期字段的显示格式设置好导出的 Excel 才是干净的用户视角。Word 导出用得最少主要是把整个表格放进 Word 文档的版式容易乱。如果业务方真的要求 Word 格式我一般建议导出 PDF 再转 Word排版稳定性好得多。5. UReport 避坑与常见问题排查五个让我翻过车的点5.1 设计器能打开但预览空白先定位断在哪一层现象是设计器页面正常打开新建模板也正常但一点预览出来的内容是空白表格连表头都没有。这个问题的本质是链路中的某一层断了。我按层来拆第一层是模板本身有没有内容第二层是数据源连没连通第三层是数据集查没查到数据第四层是单元格绑定对不对。排查时我习惯先做一个静态单元格完全不放数据集字段直接在单元格里写死文本再预览。如果静态文本能显示说明渲染层没问题问题在数据源或数据集如果静态文本也显示不出来问题在模板本身。常见原因有两个一是这个模板在保存时就已经是空的单元格在拖拽过程中被误操作清空了二是数据集有字段但单元格绑定丢失比如数据集被删了重建字段引用还指向旧数据集名。后者在设计器界面看不出明显异常要到模板 XML 里看字段引用路径。解决方式也简单删掉当前预览的空白模板重新拖字段建一张不要在原模板上修补。模板文件就像是报表工程的源代码一旦内部绑定关系乱了修补往往比重建成本高。5.2 表格显示的是表达式原文单元格类型被设成了文本现象是单元格里写了sum(E2)预览时这个公式原样显示出来不出数字。原因非常基础单元格类型默认不是表达式而是文本。在 UReport 里每个单元格都有明确的类型属性输入等号开头的内容并不会自动触发计算还必须把单元格类型改成「表达式」。这个设置很容易被忽略尤其新建模板时单元格默认类型往往沿用上一次的配置。解决方式不复杂选中单元格在属性面板的「类型」下拉框里改成「表达式」预览即可生效。如果一次预览不对注意看单元格左下角的图标纯文本和表达式在 UI 上有区别熟练之后一眼就能扫出来。更隐蔽的变体是类型改成了表达式但结果还是错。这时候要看表达式里引用的格子是不是用英文括号以及函数名是不是小写。UReport 的表达式不区分大小写但括号全角半角是严格区分的中文输入法很容易混进去一个全角括号导致整段解析失败那才叫真正的玄学现场。5.3 导出 PDF 中文变方块字体链路而不是报表本身的问题现象是预览页面中文正常但导出 PDF 后所有中文都变成了方块或者乱码。原因在服务器的字体环境不在 UReport。PDF 导出需要把字体嵌入到 PDF 文件里如果运行 Java 服务的操作系统里找不到合适的中文字体PDF 里就只能用内置的默认字体替代结果就是方块。这跟报表模板怎么设计没有关系你在本地 Windows 上跑得好好的部署到无桌面环境的 Linux 服务器上就翻车。解决思路有两个方向。第一个方向是给服务器安装中文字体对于 Linux 服务器把一款开源中文字体文件放到系统字体目录再刷新字体缓存然后重启 Java 应用。第二个方向是在设计器里把相关单元格的字体设置成服务器上实际存在的字体名。这一步需要在模板里选中所有中文相关单元格统一把字体改成那个中文字体。排查时我建议先做一个最小复现单独导出一个只有三个字的静态模板 PDF看是否乱码。最小复现能直接排除数据集、表达式、格式等因素把问题锁定在字体链路。确认是字体问题后再决定是装字体还是改模板字体配置不要一上来就改一堆单元格样式。5.4 数据量稍大就内存溢出把聚合放在 SQL 层现象是数据集的 SQL 查出来的行数不大但报表预览时页面转圈很严重后台日志直接抛OutOfMemoryError。原因在于报表引擎的工作方式UReport 会把数据集查询结果全部加载到内存再基于内存做单元格扩展和计算。如果 SQL 里的 where 条件特别宽比如查了一整年订单明细十几万行数据全部进来了内存很快就顶不住。这不是 UReport 的缺陷而是报表引擎这类工具的共同特性它不适合把几十万行明细原样渲染出来。解决方式必须从源头控制数据量。最常见做法是把明细聚合放到 SQL 层比如图表只需要每天汇总值就在 SQL 里直接用group by算出结果返回几百行而不是几十万行。如果业务确实需要导出大量明细那就不要用预览方式而是做成定时任务直接生成文件绕开在线渲染这个环节。另外检查一下 JVM 堆内存设置。如果启动参数还没动过默认的堆大小对报表应用来说偏低建议至少给到 2G。但这个只是扩大承受上限不能解决 SQL 查询过宽的问题真正要控制的是数据集本身的返回规模。5.5 模板文件重启后消失存储目录要早做规划现象是本地跑得好好的报表模板保存完也能预览但应用一重启之前的模板全没了设计器里像新装的一样干净。原因很容易踩UReport 的模板文件默认存储在一个临时目录里这个目录在应用重启时被系统清理掉或者每次启动生成的目录路径都不一样导致模板「丢」了。严格来说模板文件还在但应用已经找不到它了。解决方式是在项目早期就把模板存储路径固定到项目外部的一个独立目录比如在配置里指定一个/data/ureport/templates目录并确认目录有持久化磁盘空间。更好的做法是把模板存储实现换成数据库存储模板文件以二进制记录存进表里这样多实例部署时所有节点读取的是同一份模板不会出现 A 节点改模板、B 节点看到的还是旧模板的问题。这里我给个操作建议新项目第一天就把存储目录想清楚不要等到做了 20 张报表再迁移。迁移模板不只是拷贝文件还涉及模板中引用的数据源名称、数据集名称是否在新环境里都存在这些关联配置丢了模板文件拷过去也是打不开的。6. 进阶用法把 UReport 从「跑通」打磨成「好维护」6.1 模板目录纳入版本管理报表模板本质上是配置文件应该跟代码一样做版本管理。把 UReport 的模板存储目录放到项目工作区的一个独立文件夹里每次修改模板后将变更提交到版本库。这样业务方改了一个报表格式回头能查到是谁在什么时间改的。我吃过模板改完没人留档的亏所以现在坚持模板必须可回溯和代码同等待遇。6.2 数据访问收敛到 Service报表团队和业务团队日常的摩擦点几乎都出在 SQL 口径上。同一个「销售额」不同人写出的 SQL 统计口径可能完全不同。用 Bean 数据源把所有报表查询收敛到 Service 层之后口径定义就是 Java 代码可以走代码评审、单测和统一修改而不是散落在一张张报表模板里。这不是 UReport 的强制要求但属于让项目长期不乱的最佳实践。6.3 用固定数据集做回归验证我会专门准备一份固定数据的报表模板数据量控制在几十行字段和线上结构一致但值是固定的。每次升级依赖、改动公共配置、迁移服务器之后第一件事就是预览这张模板核对关键数字是否和上次一致。这个成本很低效果却很大能让很多配置类问题在业务投诉前暴露出来。我自己的习惯是把这张固定报表永远留在模板库里当冒烟测试用。后来每次换环境、升版本都先点开它看一眼几乎成了肌肉记忆。报表这东西跑通一次不算成功能稳定复现才是真的会用。希望帮到你。本文还有配套的精品资源点击获取