简介面向Java后端开发者的一份UReport报表工具实践材料围绕UReport2的环境搭建与报表制作展开适合需要在Spring Boot项目中快速接入报表导出能力的初中级开发者参考。压缩包内仅含1个doc文件体积约1.15MB正文串联了Maven依赖引入、context.xml与application.yml配置、模板设计、数据源绑定以及与Spring Boot集成的完整流程并给出PDF、Excel、Word等多格式输出的实现思路。文档中的pom.xml示例明确标注了ureport2-console 2.2.9版本与MySQL驱动、Thymeleaf等配套依赖便于读者对照自身工程逐项补齐同时整理了报表生成失败、生成速度偏慢等常见问题的排查方向以及报表模板设计与数据源配置的最佳实践。目前已有5687人学习下载可作为UReport入门与落地集成的查阅手册。1. 一份能跑起来的 UReport2 使用手册从 demo 到可维护报表临时接到“把业务数据做成可配置报表、还要能导出 Excel 和 PDF”的需求时很多团队第一反应是找开源报表工具。UReport 报表这套使用手册配了一个能启动的 demo价值不在“又有一个报表引擎”而在于它把 Maven 依赖、Servlet 注册、内置数据源、SpringBean 数据源、本地存储和 FTP 存储这些落地环节都摆出来了。新手可以照着把第一张报表跑通熟手更该关注它的边界/ureport/*映射不能改、ureport.disableFileProvider在 yml 里读不到、java -jar启动时默认存储会丢报表。这份资源适合正在做后台管理系统、需要快速嵌入报表设计器的 Java 团队也适合想判断 UReport2 是否值得接进现有 Spring Boot 项目的工程师。2. 把 UReport2 塞进 Spring Boot依赖、Servlet 与启动链路2.1 pom.xml 里真正不能少的依赖UReport2 的 demo 用的是 Spring Boot 2.0.0.RELEASE核心依赖是ureport2-console。这个包不只是控制台还带了设计器静态资源和 UReport 自己的 Spring 配置。下面这段是能启动的最小骨架保留输入里的版本方便对照排查如果项目已有依赖管理spring-beans的显式版本可以交给 Boot 管。project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.bstek.ureport/groupId artifactIdureport2-demo/artifactId version0.0.1-SNAPSHOT/version parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.0.0.RELEASE/version /parent dependencies !-- UReport2 控制台与设计器 -- dependency groupIdcom.bstek.ureport/groupId artifactIdureport2-console/artifactId version2.2.9/version /dependency !-- Web 容器与 Servlet 注册能力 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 数据源与 JdbcTemplate 基础能力 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency !-- demo 里带 JPA实际按需保留 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency !-- 旧项目里常见的连接池依赖按需保留 -- dependency groupIdcommons-dbcp/groupId artifactIdcommons-dbcp/artifactId version1.4/version /dependency dependency groupIdcommons-pool/groupId artifactIdcommons-pool/artifactId version1.5.4/version /dependency !-- MySQL 5.x 旧驱动换新驱动时类名要一起改 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version5.1.46/version /dependency /dependencies repositories repository idsonatype/id urlhttps://oss.sonatype.org/content/groups/public//url /repository /repositories /project这段配置的逻辑是ureport2-console提供报表引擎和/ureport/*的 Servlet 实现spring-boot-starter-web提供 Servlet 容器spring-boot-starter-jdbc提供DataSource给内置数据源复用。参数上最容易被忽略的是mysql-connector-java 5.1.46对应旧驱动类com.mysql.jdbc.Driver如果换成新驱动driver-class-name要改成com.mysql.cj.jdbc.Driver。另外demo 里的TestBean若用了RandomStringUtils和RandomUtils还需要补commons-lang、commons-lang3否则编译阶段就翻车。我一般会把模拟数据改成 JDK 的ThreadLocalRandom和UUID少两个依赖后续升级也省心。2.2 context.xml 与 Application.java 的注册顺序UReport2 不是只加依赖就能用它需要把ureport-console-context.xml导入 Spring 容器再把UReportServlet注册到/ureport/*。这两个动作一个是容器初始化一个是 Servlet 映射缺一个都会出现“页面 404 但日志没明显报错”的情况。?xml version1.0 encodingUTF-8? beans xmlnshttp://www.springframework.org/schema/beans xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd !-- 导入 UReport2 自己的 Spring 配置 -- import resourceclasspath:ureport-console-context.xml/ !-- 如果要用 properties 覆盖 UReport 内部配置再打开下面这段 -- !-- bean idpropertyConfigurer parentureport.props property namelocation valueclasspath:application.properties/value /property /bean -- /beanspackage com.bstek.ureport.test; import com.bstek.ureport.console.UReportServlet; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.web.servlet.ServletRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ImportResource; ImportResource(classpath:context.xml) SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } Bean public ServletRegistrationBeanUReportServlet buildUReportServlet() { // /ureport/* 是 UReport2 控制台和设计器的入口不要随意改成 /report/* return new ServletRegistrationBean(new UReportServlet(), /ureport/*); } }ImportResource(classpath:context.xml)的作用是把 UReport2 的 Bean 定义拉进容器ServletRegistrationBean则把UReportServlet挂到 Web 容器。参数上唯一不能动的是/ureport/*输入里也明确写了这个映射一定不能变改成别的路径后设计器里的静态资源、请求转发都会对不上。context.xml里注释掉的ureport.props不要随手打开它会影响 UReport 内部属性文件的读取顺序后面讲存储开关时会踩到。2.3 application.yml 的位置与最小配置demo 把application.yml放在resources/config下这里有个现实问题Spring Boot 默认读取的是src/main/resources/application.yml不是resources/config/application.yml。如果坚持放在 config 目录启动时要加--spring.config.locationclasspath:/config/或者把文件移到 resources 根目录。数据源配置本身不复杂但 URL 里的建议加引号避免 YAML 解析时出现不必要的歧义。spring: datasource: url: jdbc:mysql://127.0.0.1:3306/notified?useUnicodetruecharacterEncodingUTF-8zeroDateTimeBehaviorconvertToNull username: root password: change_me driver-class-name: com.mysql.jdbc.Driver # 如果 application.yml 放在 resources/config 下启动参数需要补 # --spring.config.locationclasspath:/config/这段配置的逻辑是给 Spring 容器提供一个DataSourceUReport 的内置数据源会从这个DataSource取连接。参数上useUnicodetruecharacterEncodingUTF-8处理中文zeroDateTimeBehaviorconvertToNull是旧版 MySQL 驱动对零日期的兼容参数换新驱动后这个参数可能不再需要。注意不要把生产密码直接写进 ymldemo 可以这么干实际项目用环境变量或配置中心替换。2.4 启动后的第一轮自检启动类跑起来后不要急着做复杂模板先做三件事访问/ureport/designer看设计器是否加载看日志里UReportServlet是否初始化在设计器里新建一个内存数据源随便填两行数据预览。常见的通过标准是页面能打开、左侧数据源列表能看到MyDataSource或testBean、预览不报Connection is null。如果页面 404先查ServletRegistrationBean的映射如果页面能开但数据源为空先查BuildinDatasource实现类有没有被扫描到。这个顺序比一上来调模板样式有效得多。3. 数据源接法内置数据源与 SpringBean 数据源怎么选3.1 BuildinDatasource复用 Spring 数据源内置数据源适合“报表直接写 SQL”的场景。实现BuildinDatasource接口把 Spring 容器里的DataSource注入进来name()返回设计器里显示的数据源名称getConnection()从连接池取连接。UReport 会在设计器里把这个名称列出来报表数据集里写 SQL 就能查库。package com.bstek.ureport.test; import com.bstek.ureport.definition.datasource.BuildinDatasource; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import javax.sql.DataSource; import java.sql.Connection; import java.sql.SQLException; Component public class UreportDataSource implements BuildinDatasource { private static final String NAME MyDataSource; private final Logger log LoggerFactory.getLogger(UreportDataSource.class); Autowired private DataSource dataSource; Override public String name() { // 设计器里看到的数据源名称报表数据集靠它选中这个数据源 return NAME; } Override public Connection getConnection() { try { return dataSource.getConnection(); } catch (SQLException e) { log.error(UReport 数据源获取连接失败, e); return null; } } }这段代码的关键是name()和getConnection()。name()不是 Bean 名而是设计器里的数据源显示名改了就相当于换了一个数据源已有报表数据集可能找不到它。getConnection()返回的连接由 UReport 负责关闭但取连接失败时不要只打印日志返回null否则设计器预览时只会看到“数据集为空”排查起来像黑匣子。我一般会在 catch 里把数据库 URL、用户名和异常码一起打出来方便定位是权限问题还是网络问题。3.2 SpringBean 数据源方法签名和返回类型当报表数据不是一条 SQL 能查出来或者需要做权限过滤、字段脱敏、跨服务聚合时用 SpringBean 数据源更合适。它的约束很硬方法必须包含String dsName、String datasetName、MapString,Object parameters三个参数返回ListMapString,Object或ListPOJO。Bean 名就是设计器里选择的数据源名。package com.bstek.ureport.test; import org.springframework.stereotype.Component; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.UUID; import java.util.concurrent.ThreadLocalRandom; Component(testBean) public class TestBean { /** * 返回 Map 列表字段名就是 Map 的 key */ public ListMapString, Object loadReportData(String dsName, String datasetName, MapString, Object parameters) { ListMapString, Object list new ArrayList(); for (int i 0; i 1000; i) { MapString, Object row new HashMap(); row.put(id, i); row.put(name, UUID.randomUUID().toString().replace(-, ).substring(0, 10)); row.put(salary, ThreadLocalRandom.current().nextInt(10000) i); list.add(row); } return list; } /** * 返回 POJO 列表字段名来自 getter报表里用 id/name/salary */ public ListUser buildReport(String dsName, String datasetName, MapString, Object parameters) { ListUser list new ArrayList(); for (int i 0; i 1000; i) { User user new User(); user.setId(i); user.setName(UUID.randomUUID().toString().replace(-, ).substring(0, 10)); user.setSalary(ThreadLocalRandom.current().nextInt(10000) i); list.add(user); } return list; } }package com.bstek.ureport.test; public class User { private int id; private String name; private int salary; public int getId() { return id; } public void setId(int id) { this.id id; } public String getName() { return name; } public void setName(String name) { this.name name; } public int getSalary() { return salary; } public void setSalary(int salary) { this.salary salary; } }Component(testBean)里的testBean就是设计器里看到的数据源名如果只写ComponentBean 名会变成类名首字母小写和文档里的testBean对不上。dsName和datasetName是 UReport 传进来的上下文parameters是报表参数比如页面上传了startDate这里就能用parameters.get(startDate)拿到。返回Map时字段名靠 key返回 POJO 时字段名靠 getter大小写要和模板里绑定的字段一致。demo 里造了 1000 条数据实际报表不要这么干分页、过滤、聚合尽量在方法内部完成别把全量数据塞给设计器预览。3.3 两种数据源怎么选内置数据源和 SpringBean 数据源不是替代关系而是两种边界。下面这张表按实际落地场景对比选型时先看数据从哪里来、要不要权限过滤、报表参数多不多。对比项BuildinDatasourceSpringBean 数据源数据来源数据库 SQLJava 方法返回集合适合场景单库查询、简单关联、运营报表跨服务聚合、权限过滤、字段脱敏报表参数SQL 里用${参数名}或数据集参数方法第三个参数parameters字段名来源SQL 别名Map key 或 POJO getter大数据量依赖 SQL 分页和索引方法内部做分页别一次性全查常见故障连接为空、SQL 写错、数据源名对不上方法签名不对、Bean 名不对、返回 null我一般会先用内置数据源把 SQL 跑通确认字段和参数没问题再把需要业务逻辑的部分迁到 SpringBean 数据源。不要一上来就写复杂 Java 方法否则报表预览失败时分不清是 SQL 问题还是方法返回值问题。参数传递上内置数据源的 SQL 参数和 SpringBean 的parameters都来自报表设计器里的参数定义名字要完全一致大小写也别错。4. 报表文件存哪默认目录、本地目录与 FTP 存储4.1 默认存储为什么在 java -jar 下会丢UReport2 默认会把报表文件存在 Web 容器的WEB-INF/ureportfiles目录下。用 Tomcat 部署 war 时这个目录还在用java -jar启动 Spring Boot 时容器的工作目录是临时解压目录重启后报表文件就没了。输入里还写了一个关键点ureport.disableFileProvidertrue只能在 properties 文件里配置放在 yml 里读不到。这个坑很隐蔽配置看起来生效了实际默认 provider 还在。# 放在 src/main/resources/application.properties 中不要只写进 yml ureport.disableFileProvidertrue # 自定义本地存储目录按操作系统写绝对路径 ureport.fileStoreDir/data/ureport-files这段配置的逻辑是ureport.disableFileProvidertrue关掉默认文件存储避免java -jar重启丢报表ureport.fileStoreDir给自定义FileReportProvider提供根目录。参数上路径要用应用进程有读写权限的目录Linux 下不要用/root或没有权限的挂载点。禁用默认 provider 后必须自己提供一个ReportProvider否则设计器里“保存”会失败不要以为关掉就万事大吉。4.2 自定义本地存储 FileReportProvider自定义本地存储的核心是实现ReportProvider把报表文件读写落到固定目录。下面这段保留输入里的关键方法做了两个实战修正prefix用file:setApplicationContext里先判断路径是不是绝对路径避免basePath /data/ureport拼出错误路径。package com.bstek.ureport.test; import com.bstek.ureport.exception.ReportException; import com.bstek.ureport.provider.report.ReportFile; import com.bstek.ureport.provider.report.ReportProvider; import org.springframework.beans.BeansException; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.ApplicationContext; import org.springframework.context.ApplicationContextAware; import org.springframework.stereotype.Component; import org.springframework.web.context.WebApplicationContext; import javax.servlet.ServletContext; import java.io.*; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.util.ArrayList; import java.util.Comparator; import java.util.Date; import java.util.List; Component public class FileReportProvider implements ReportProvider, ApplicationContextAware { private String prefix file:; Value(${ureport.fileStoreDir:./ureport-files}) private String fileStoreDir; private boolean disabled; Override public InputStream loadReport(String file) { try { return new FileInputStream(resolve(file)); } catch (FileNotFoundException e) { throw new ReportException(e); } } Override public void saveReport(String file, String content) { File target resolve(file); File parent target.getParentFile(); if (parent ! null !parent.exists()) { parent.mkdirs(); } try { Files.write(target.toPath(), content.getBytes(StandardCharsets.UTF_8)); } catch (IOException e) { throw new ReportException(e); } } Override public void deleteReport(String file) { File target resolve(file); if (target.exists()) { target.delete(); } } Override public ListReportFile getReportFiles() { File dir new File(fileStoreDir); ListReportFile list new ArrayList(); File[] files dir.listFiles(); if (files null) { return list; } for (File f : files) { if (f.isFile()) { list.add(new ReportFile(f.getName(), new Date(f.lastModified()))); } } list.sort(Comparator.comparing(ReportFile::getUpdateDate).reversed()); return list; } Override public String getName() { return 服务器文件系统; } Override public boolean disabled() { return disabled; } Override public String getPrefix() { return prefix; } Override public void setApplicationContext(ApplicationContext applicationContext) throws BeansException { File dir new File(fileStoreDir); if (dir.isAbsolute()) { dir.mkdirs(); return; } if (applicationContext instanceof WebApplicationContext) { WebApplicationContext context (WebApplicationContext) applicationContext; ServletContext servletContext context.getServletContext(); String basePath servletContext.getRealPath(/); fileStoreDir new File(basePath, fileStoreDir).getAbsolutePath(); new File(fileStoreDir).mkdirs(); } } private File resolve(String file) { String name file.startsWith(prefix) ? file.substring(prefix.length()) : file; return new File(fileStoreDir, name); } }这段代码的逻辑是所有报表文件都以file:开头resolve去掉前缀后拼到fileStoreDir根目录saveReport自动创建父目录避免第一次保存时报“路径不存在”getReportFiles按修改时间倒序设计器里最近改过的报表排在前面。参数上prefix必须和设计器里存储 provider 的识别前缀一致默认file:已经能和 UReport 默认文件存储衔接。disabled()返回false表示启用如果项目里同时有多个 providerprefix 不要重复否则保存时可能落到另一个实现里。4.3 FTP 存储的工厂类与配置当报表需要多节点共享或者不想把文件放本机磁盘时FTP 存储是 demo 里给出的另一条路。它分两层FTPClientFactory负责创建、校验、销毁 FTP 连接ReportProvider实现负责按ftp-前缀读写报表。配置上ConfigurationProperties(ftp.factory)要求工厂类必须有 getter/setter否则 yml 里的值注入不进来这是输入里特别强调的点。ftp: factory: hostname: 192.168.1.100 port: 21 username: ftpuser password: change_me client-timeout: 60000 encoding: UTF-8 passive-mode: true file-type: 2 rename-uploaded: false ureport: ftp: provider: prefix: ftp- disabled: false basePath: /ureportpackage com.bstek.ureport.test.ftp; import lombok.Data; import org.apache.commons.net.ftp.FTP; import org.apache.commons.net.ftp.FTPClient; import org.apache.commons.net.ftp.FTPClientConfig; import org.apache.commons.net.ftp.FTPReply; import org.apache.commons.pool.PoolableObjectFactory; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Data Component ConfigurationProperties(ftp.factory) public class FTPClientFactory implements PoolableObjectFactoryFTPClient { private String hostname; private int port 21; private String username; private String password; private boolean passiveMode true; private String encoding UTF-8; private int clientTimeout 60000; private int fileType FTP.BINARY_FILE_TYPE; Override public FTPClient makeObject() throws Exception { FTPClient client new FTPClient(); client.setConnectTimeout(clientTimeout); client.setControlEncoding(encoding); client.connect(hostname, port); int reply client.getReplyCode(); if (!FTPReply.isPositiveCompletion(reply)) { client.disconnect(); throw new IllegalStateException(FTP 服务端拒绝连接reply reply); } if (!client.login(username, password)) { client.disconnect(); throw new IllegalStateException(FTP 登录失败); } FTPClientConfig conf new FTPClientConfig(FTPClientConfig.SYST_NT); conf.setServerLanguageCode(zh); client.configure(conf); if (passiveMode) { client.enterLocalPassiveMode(); } client.setFileType(fileType); return client; } Override public void destroyObject(FTPClient client) throws Exception { if (client ! null client.isConnected()) { client.logout(); client.disconnect(); } } Override public boolean validateObject(FTPClient client) { try { return client ! null client.isConnected() client.sendNoOp(); } catch (Exception e) { return false; } } Override public void activateObject(FTPClient client) { } Override public void passivateObject(FTPClient client) { } }这段工厂类的逻辑是makeObject建立连接并登录destroyObject退出并断开validateObject用NOOP判断连接是否还活着。参数上passive-mode: true在很多内网 FTP 环境里是必须的否则数据连接建不起来client-timeout不要设得太短报表文件大时上传会超时file-type: 2对应二进制传输避免 Excel/PDF 内容被文本模式改坏。FTP 的ReportProvider实现要按loadReport、saveReport、deleteReport、getReportFiles四个方法落到 FTP 命令上其中loadReport取到输入流后不要立刻断开连接先把流读完再归还连接否则会出现“预览为空、下载一半断流”的问题。凭据不要写死在 yml 里demo 可以实际项目用环境变量覆盖。5. 避坑排查启动失败、数据源为空、报表丢失怎么查5.1 启动期404 与 Servlet 映射现象应用启动成功访问/ureport/designer返回 404。原因通常是ServletRegistrationBean没注册或者映射被改成了/report/*。解决方式是回到Application.java确认new ServletRegistrationBean(new UReportServlet(), /ureport/*)存在并且启动类在父包或能扫描到配置类。另一个常见原因是ImportResource没加ureport-console-context.xml没进容器Servlet 初始化时拿不到必要 Bean。现象设计器页面能打开但静态资源 404样式全乱。原因多半是应用加了全局路径前缀比如server.servlet.context-path或者安全框架拦截了/ureport/**。解决时先看浏览器 Network 里静态资源的实际请求路径再确认安全框架是否放行/ureport/**和/ureport/designer。不要只改 Servlet 映射映射改了反而更乱。现象启动日志报NoClassDefFoundError或ClassNotFoundException。先查ureport2-console是否真的从仓库拉下来了再看有没有和 Spring 版本冲突。demo 显式写了spring-beans 5.0.4.RELEASE如果项目父 POM 管理了不同版本容易出现类冲突。解决方式是先跑mvn dependency:tree看spring-beans、spring-web的版本必要时删掉显式版本交给 Boot 统一管理。5.2 运行期数据源和参数为空现象设计器里数据源列表为空看不到MyDataSource。原因一般是UreportDataSource没加Component或者启动类扫描包不包含它。解决时先确认类上有Component再看启动类所在包是否能覆盖com.bstek.ureport.test。如果用了多模块检查ComponentScan有没有漏掉子模块。现象选中testBean后预览报“方法不存在”或数据集为空。原因通常是方法签名不对。UReport 要求方法包含String、String、Map三个参数返回List。少一个参数、参数顺序反了、返回null都会让设计器认为数据集不可用。解决时把方法头固定成public ListMapString,Object loadReportData(String dsName, String datasetName, MapString,Object parameters)先在 Java 里直接调用一次确认能返回数据再回设计器绑定。现象报表里参数传不进去SQL 条件一直为空。原因可能是报表参数名和 SQL 里的${}名称不一致或者 SpringBean 方法里没从parameters取值。解决时在设计器里看参数定义的大小写SQL 里先用固定值跑通再替换成参数SpringBean 里打印parameters.keySet()确认前端传进来的 key 到底是什么。不要靠猜参数名大小写在报表里很敏感。5.3 存储期重启丢报表与路径权限现象java -jar启动后保存的报表重启就没了。原因是用了默认文件存储落到了临时解压目录。解决方式是在application.properties里加ureport.disableFileProvidertrue并提供一个自定义ReportProvider。注意这个开关写在 yml 里读不到必须放 propertiescontext.xml里如果没打开ureport.propsUReport 内部属性读取也可能不生效。现象自定义本地存储保存时报“路径不存在”或“权限不足”。原因可能是ureport.fileStoreDir配了相对路径setApplicationContext里又拼了basePath最后落到了容器临时目录也可能是进程用户没有写权限。解决时先把目录配成绝对路径手动mkdir -p并chmod给应用用户再在代码里判断File.isAbsolute()绝对路径不再拼basePath。现象FTP 存储预览正常保存或下载大文件时断流。原因通常是 FTP 被动模式没开、client-timeout太短或者loadReport返回流之后连接被提前归还。解决时先开passive-mode: true把超时调到 60 秒以上再检查 provider 的loadReport是否先把流复制到内存或临时文件再关闭连接。大报表不要直接把 FTP 输入流交给上层连接池回收时机很难控。5.4 上线前检查表检查项检查位置通过标准Servlet 映射Application.java路径为/ureport/*未被安全框架拦截UReport 上下文context.xml已导入ureport-console-context.xml数据源名称BuildinDatasource.name()设计器里能看到且与报表数据集一致SpringBean 签名数据源方法三参数、返回 List、Bean 名与设计器一致默认存储开关application.propertiesureport.disableFileProvidertrue生效自定义存储目录ureport.fileStoreDir绝对路径、进程可读写、重启后文件还在FTP 连接ftp.factory配置登录成功、被动模式可用、大文件不中断导出格式设计器预览与导出Excel/PDF 字段完整、中文不乱码这张表建议在每次部署前走一遍尤其是换容器、换启动方式、换数据源的时候。UReport2 的很多问题不是代码写错而是配置落点不对把检查项固定下来比事后翻日志快得多。6. 进阶验证用一份最小报表跑通设计、预览与导出最小验证不要拿业务大表造一张三行数据的数据集就够。内置数据源里写select 1 as id, A as name, 100 as salary union all select 2, B, 200在设计器里新建数据集、绑定字段、拖到模板单元格预览能出三行再谈样式。这个动作能同时验证数据源连接、SQL 别名、字段绑定和模板渲染四件事。导出时分别点 Excel 和 PDF重点看中文、数字格式和空值列Excel 看表头是否合并错位PDF 看字体是否缺字。验证动作观察点失败时先查设计器打开左侧数据源列表Servlet 映射、context.xml数据集预览返回行数和字段名SQL 别名、数据源名称模板预览单元格绑定是否生效字段大小写、表达式写法导出 Excel合并单元格、中文模板样式、字体导出 PDF分页、缺字PDF 字体配置、列宽我一般会把这份最小报表留在工程里作为升级依赖后的回归用例。从那以后我每次接 UReport2都先把/ureport/*、数据源名、存储目录这三件事写进启动检查单再谈模板美观这三处不稳后面调样式全是白费。希望帮到你。本文还有配套的精品资源点击获取
简介面向Java后端开发者的一份UReport报表工具实践材料围绕UReport2的环境搭建与报表制作展开适合需要在Spring Boot项目中快速接入报表导出能力的初中级开发者参考。压缩包内仅含1个doc文件体积约1.15MB正文串联了Maven依赖引入、context.xml与application.yml配置、模板设计、数据源绑定以及与Spring Boot集成的完整流程并给出PDF、Excel、Word等多格式输出的实现思路。文档中的pom.xml示例明确标注了ureport2-console 2.2.9版本与MySQL驱动、Thymeleaf等配套依赖便于读者对照自身工程逐项补齐同时整理了报表生成失败、生成速度偏慢等常见问题的排查方向以及报表模板设计与数据源配置的最佳实践。目前已有5687人学习下载可作为UReport入门与落地集成的查阅手册。1. 一份能跑起来的 UReport2 使用手册从 demo 到可维护报表临时接到“把业务数据做成可配置报表、还要能导出 Excel 和 PDF”的需求时很多团队第一反应是找开源报表工具。UReport 报表这套使用手册配了一个能启动的 demo价值不在“又有一个报表引擎”而在于它把 Maven 依赖、Servlet 注册、内置数据源、SpringBean 数据源、本地存储和 FTP 存储这些落地环节都摆出来了。新手可以照着把第一张报表跑通熟手更该关注它的边界/ureport/*映射不能改、ureport.disableFileProvider在 yml 里读不到、java -jar启动时默认存储会丢报表。这份资源适合正在做后台管理系统、需要快速嵌入报表设计器的 Java 团队也适合想判断 UReport2 是否值得接进现有 Spring Boot 项目的工程师。2. 把 UReport2 塞进 Spring Boot依赖、Servlet 与启动链路2.1 pom.xml 里真正不能少的依赖UReport2 的 demo 用的是 Spring Boot 2.0.0.RELEASE核心依赖是ureport2-console。这个包不只是控制台还带了设计器静态资源和 UReport 自己的 Spring 配置。下面这段是能启动的最小骨架保留输入里的版本方便对照排查如果项目已有依赖管理spring-beans的显式版本可以交给 Boot 管。project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.bstek.ureport/groupId artifactIdureport2-demo/artifactId version0.0.1-SNAPSHOT/version parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.0.0.RELEASE/version /parent dependencies !-- UReport2 控制台与设计器 -- dependency groupIdcom.bstek.ureport/groupId artifactIdureport2-console/artifactId version2.2.9/version /dependency !-- Web 容器与 Servlet 注册能力 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 数据源与 JdbcTemplate 基础能力 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency !-- demo 里带 JPA实际按需保留 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency !-- 旧项目里常见的连接池依赖按需保留 -- dependency groupIdcommons-dbcp/groupId artifactIdcommons-dbcp/artifactId version1.4/version /dependency dependency groupIdcommons-pool/groupId artifactIdcommons-pool/artifactId version1.5.4/version /dependency !-- MySQL 5.x 旧驱动换新驱动时类名要一起改 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version5.1.46/version /dependency /dependencies repositories repository idsonatype/id urlhttps://oss.sonatype.org/content/groups/public//url /repository /repositories /project这段配置的逻辑是ureport2-console提供报表引擎和/ureport/*的 Servlet 实现spring-boot-starter-web提供 Servlet 容器spring-boot-starter-jdbc提供DataSource给内置数据源复用。参数上最容易被忽略的是mysql-connector-java 5.1.46对应旧驱动类com.mysql.jdbc.Driver如果换成新驱动driver-class-name要改成com.mysql.cj.jdbc.Driver。另外demo 里的TestBean若用了RandomStringUtils和RandomUtils还需要补commons-lang、commons-lang3否则编译阶段就翻车。我一般会把模拟数据改成 JDK 的ThreadLocalRandom和UUID少两个依赖后续升级也省心。2.2 context.xml 与 Application.java 的注册顺序UReport2 不是只加依赖就能用它需要把ureport-console-context.xml导入 Spring 容器再把UReportServlet注册到/ureport/*。这两个动作一个是容器初始化一个是 Servlet 映射缺一个都会出现“页面 404 但日志没明显报错”的情况。?xml version1.0 encodingUTF-8? beans xmlnshttp://www.springframework.org/schema/beans xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd !-- 导入 UReport2 自己的 Spring 配置 -- import resourceclasspath:ureport-console-context.xml/ !-- 如果要用 properties 覆盖 UReport 内部配置再打开下面这段 -- !-- bean idpropertyConfigurer parentureport.props property namelocation valueclasspath:application.properties/value /property /bean -- /beanspackage com.bstek.ureport.test; import com.bstek.ureport.console.UReportServlet; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.web.servlet.ServletRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ImportResource; ImportResource(classpath:context.xml) SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } Bean public ServletRegistrationBeanUReportServlet buildUReportServlet() { // /ureport/* 是 UReport2 控制台和设计器的入口不要随意改成 /report/* return new ServletRegistrationBean(new UReportServlet(), /ureport/*); } }ImportResource(classpath:context.xml)的作用是把 UReport2 的 Bean 定义拉进容器ServletRegistrationBean则把UReportServlet挂到 Web 容器。参数上唯一不能动的是/ureport/*输入里也明确写了这个映射一定不能变改成别的路径后设计器里的静态资源、请求转发都会对不上。context.xml里注释掉的ureport.props不要随手打开它会影响 UReport 内部属性文件的读取顺序后面讲存储开关时会踩到。2.3 application.yml 的位置与最小配置demo 把application.yml放在resources/config下这里有个现实问题Spring Boot 默认读取的是src/main/resources/application.yml不是resources/config/application.yml。如果坚持放在 config 目录启动时要加--spring.config.locationclasspath:/config/或者把文件移到 resources 根目录。数据源配置本身不复杂但 URL 里的建议加引号避免 YAML 解析时出现不必要的歧义。spring: datasource: url: jdbc:mysql://127.0.0.1:3306/notified?useUnicodetruecharacterEncodingUTF-8zeroDateTimeBehaviorconvertToNull username: root password: change_me driver-class-name: com.mysql.jdbc.Driver # 如果 application.yml 放在 resources/config 下启动参数需要补 # --spring.config.locationclasspath:/config/这段配置的逻辑是给 Spring 容器提供一个DataSourceUReport 的内置数据源会从这个DataSource取连接。参数上useUnicodetruecharacterEncodingUTF-8处理中文zeroDateTimeBehaviorconvertToNull是旧版 MySQL 驱动对零日期的兼容参数换新驱动后这个参数可能不再需要。注意不要把生产密码直接写进 ymldemo 可以这么干实际项目用环境变量或配置中心替换。2.4 启动后的第一轮自检启动类跑起来后不要急着做复杂模板先做三件事访问/ureport/designer看设计器是否加载看日志里UReportServlet是否初始化在设计器里新建一个内存数据源随便填两行数据预览。常见的通过标准是页面能打开、左侧数据源列表能看到MyDataSource或testBean、预览不报Connection is null。如果页面 404先查ServletRegistrationBean的映射如果页面能开但数据源为空先查BuildinDatasource实现类有没有被扫描到。这个顺序比一上来调模板样式有效得多。3. 数据源接法内置数据源与 SpringBean 数据源怎么选3.1 BuildinDatasource复用 Spring 数据源内置数据源适合“报表直接写 SQL”的场景。实现BuildinDatasource接口把 Spring 容器里的DataSource注入进来name()返回设计器里显示的数据源名称getConnection()从连接池取连接。UReport 会在设计器里把这个名称列出来报表数据集里写 SQL 就能查库。package com.bstek.ureport.test; import com.bstek.ureport.definition.datasource.BuildinDatasource; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import javax.sql.DataSource; import java.sql.Connection; import java.sql.SQLException; Component public class UreportDataSource implements BuildinDatasource { private static final String NAME MyDataSource; private final Logger log LoggerFactory.getLogger(UreportDataSource.class); Autowired private DataSource dataSource; Override public String name() { // 设计器里看到的数据源名称报表数据集靠它选中这个数据源 return NAME; } Override public Connection getConnection() { try { return dataSource.getConnection(); } catch (SQLException e) { log.error(UReport 数据源获取连接失败, e); return null; } } }这段代码的关键是name()和getConnection()。name()不是 Bean 名而是设计器里的数据源显示名改了就相当于换了一个数据源已有报表数据集可能找不到它。getConnection()返回的连接由 UReport 负责关闭但取连接失败时不要只打印日志返回null否则设计器预览时只会看到“数据集为空”排查起来像黑匣子。我一般会在 catch 里把数据库 URL、用户名和异常码一起打出来方便定位是权限问题还是网络问题。3.2 SpringBean 数据源方法签名和返回类型当报表数据不是一条 SQL 能查出来或者需要做权限过滤、字段脱敏、跨服务聚合时用 SpringBean 数据源更合适。它的约束很硬方法必须包含String dsName、String datasetName、MapString,Object parameters三个参数返回ListMapString,Object或ListPOJO。Bean 名就是设计器里选择的数据源名。package com.bstek.ureport.test; import org.springframework.stereotype.Component; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.UUID; import java.util.concurrent.ThreadLocalRandom; Component(testBean) public class TestBean { /** * 返回 Map 列表字段名就是 Map 的 key */ public ListMapString, Object loadReportData(String dsName, String datasetName, MapString, Object parameters) { ListMapString, Object list new ArrayList(); for (int i 0; i 1000; i) { MapString, Object row new HashMap(); row.put(id, i); row.put(name, UUID.randomUUID().toString().replace(-, ).substring(0, 10)); row.put(salary, ThreadLocalRandom.current().nextInt(10000) i); list.add(row); } return list; } /** * 返回 POJO 列表字段名来自 getter报表里用 id/name/salary */ public ListUser buildReport(String dsName, String datasetName, MapString, Object parameters) { ListUser list new ArrayList(); for (int i 0; i 1000; i) { User user new User(); user.setId(i); user.setName(UUID.randomUUID().toString().replace(-, ).substring(0, 10)); user.setSalary(ThreadLocalRandom.current().nextInt(10000) i); list.add(user); } return list; } }package com.bstek.ureport.test; public class User { private int id; private String name; private int salary; public int getId() { return id; } public void setId(int id) { this.id id; } public String getName() { return name; } public void setName(String name) { this.name name; } public int getSalary() { return salary; } public void setSalary(int salary) { this.salary salary; } }Component(testBean)里的testBean就是设计器里看到的数据源名如果只写ComponentBean 名会变成类名首字母小写和文档里的testBean对不上。dsName和datasetName是 UReport 传进来的上下文parameters是报表参数比如页面上传了startDate这里就能用parameters.get(startDate)拿到。返回Map时字段名靠 key返回 POJO 时字段名靠 getter大小写要和模板里绑定的字段一致。demo 里造了 1000 条数据实际报表不要这么干分页、过滤、聚合尽量在方法内部完成别把全量数据塞给设计器预览。3.3 两种数据源怎么选内置数据源和 SpringBean 数据源不是替代关系而是两种边界。下面这张表按实际落地场景对比选型时先看数据从哪里来、要不要权限过滤、报表参数多不多。对比项BuildinDatasourceSpringBean 数据源数据来源数据库 SQLJava 方法返回集合适合场景单库查询、简单关联、运营报表跨服务聚合、权限过滤、字段脱敏报表参数SQL 里用${参数名}或数据集参数方法第三个参数parameters字段名来源SQL 别名Map key 或 POJO getter大数据量依赖 SQL 分页和索引方法内部做分页别一次性全查常见故障连接为空、SQL 写错、数据源名对不上方法签名不对、Bean 名不对、返回 null我一般会先用内置数据源把 SQL 跑通确认字段和参数没问题再把需要业务逻辑的部分迁到 SpringBean 数据源。不要一上来就写复杂 Java 方法否则报表预览失败时分不清是 SQL 问题还是方法返回值问题。参数传递上内置数据源的 SQL 参数和 SpringBean 的parameters都来自报表设计器里的参数定义名字要完全一致大小写也别错。4. 报表文件存哪默认目录、本地目录与 FTP 存储4.1 默认存储为什么在 java -jar 下会丢UReport2 默认会把报表文件存在 Web 容器的WEB-INF/ureportfiles目录下。用 Tomcat 部署 war 时这个目录还在用java -jar启动 Spring Boot 时容器的工作目录是临时解压目录重启后报表文件就没了。输入里还写了一个关键点ureport.disableFileProvidertrue只能在 properties 文件里配置放在 yml 里读不到。这个坑很隐蔽配置看起来生效了实际默认 provider 还在。# 放在 src/main/resources/application.properties 中不要只写进 yml ureport.disableFileProvidertrue # 自定义本地存储目录按操作系统写绝对路径 ureport.fileStoreDir/data/ureport-files这段配置的逻辑是ureport.disableFileProvidertrue关掉默认文件存储避免java -jar重启丢报表ureport.fileStoreDir给自定义FileReportProvider提供根目录。参数上路径要用应用进程有读写权限的目录Linux 下不要用/root或没有权限的挂载点。禁用默认 provider 后必须自己提供一个ReportProvider否则设计器里“保存”会失败不要以为关掉就万事大吉。4.2 自定义本地存储 FileReportProvider自定义本地存储的核心是实现ReportProvider把报表文件读写落到固定目录。下面这段保留输入里的关键方法做了两个实战修正prefix用file:setApplicationContext里先判断路径是不是绝对路径避免basePath /data/ureport拼出错误路径。package com.bstek.ureport.test; import com.bstek.ureport.exception.ReportException; import com.bstek.ureport.provider.report.ReportFile; import com.bstek.ureport.provider.report.ReportProvider; import org.springframework.beans.BeansException; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.ApplicationContext; import org.springframework.context.ApplicationContextAware; import org.springframework.stereotype.Component; import org.springframework.web.context.WebApplicationContext; import javax.servlet.ServletContext; import java.io.*; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.util.ArrayList; import java.util.Comparator; import java.util.Date; import java.util.List; Component public class FileReportProvider implements ReportProvider, ApplicationContextAware { private String prefix file:; Value(${ureport.fileStoreDir:./ureport-files}) private String fileStoreDir; private boolean disabled; Override public InputStream loadReport(String file) { try { return new FileInputStream(resolve(file)); } catch (FileNotFoundException e) { throw new ReportException(e); } } Override public void saveReport(String file, String content) { File target resolve(file); File parent target.getParentFile(); if (parent ! null !parent.exists()) { parent.mkdirs(); } try { Files.write(target.toPath(), content.getBytes(StandardCharsets.UTF_8)); } catch (IOException e) { throw new ReportException(e); } } Override public void deleteReport(String file) { File target resolve(file); if (target.exists()) { target.delete(); } } Override public ListReportFile getReportFiles() { File dir new File(fileStoreDir); ListReportFile list new ArrayList(); File[] files dir.listFiles(); if (files null) { return list; } for (File f : files) { if (f.isFile()) { list.add(new ReportFile(f.getName(), new Date(f.lastModified()))); } } list.sort(Comparator.comparing(ReportFile::getUpdateDate).reversed()); return list; } Override public String getName() { return 服务器文件系统; } Override public boolean disabled() { return disabled; } Override public String getPrefix() { return prefix; } Override public void setApplicationContext(ApplicationContext applicationContext) throws BeansException { File dir new File(fileStoreDir); if (dir.isAbsolute()) { dir.mkdirs(); return; } if (applicationContext instanceof WebApplicationContext) { WebApplicationContext context (WebApplicationContext) applicationContext; ServletContext servletContext context.getServletContext(); String basePath servletContext.getRealPath(/); fileStoreDir new File(basePath, fileStoreDir).getAbsolutePath(); new File(fileStoreDir).mkdirs(); } } private File resolve(String file) { String name file.startsWith(prefix) ? file.substring(prefix.length()) : file; return new File(fileStoreDir, name); } }这段代码的逻辑是所有报表文件都以file:开头resolve去掉前缀后拼到fileStoreDir根目录saveReport自动创建父目录避免第一次保存时报“路径不存在”getReportFiles按修改时间倒序设计器里最近改过的报表排在前面。参数上prefix必须和设计器里存储 provider 的识别前缀一致默认file:已经能和 UReport 默认文件存储衔接。disabled()返回false表示启用如果项目里同时有多个 providerprefix 不要重复否则保存时可能落到另一个实现里。4.3 FTP 存储的工厂类与配置当报表需要多节点共享或者不想把文件放本机磁盘时FTP 存储是 demo 里给出的另一条路。它分两层FTPClientFactory负责创建、校验、销毁 FTP 连接ReportProvider实现负责按ftp-前缀读写报表。配置上ConfigurationProperties(ftp.factory)要求工厂类必须有 getter/setter否则 yml 里的值注入不进来这是输入里特别强调的点。ftp: factory: hostname: 192.168.1.100 port: 21 username: ftpuser password: change_me client-timeout: 60000 encoding: UTF-8 passive-mode: true file-type: 2 rename-uploaded: false ureport: ftp: provider: prefix: ftp- disabled: false basePath: /ureportpackage com.bstek.ureport.test.ftp; import lombok.Data; import org.apache.commons.net.ftp.FTP; import org.apache.commons.net.ftp.FTPClient; import org.apache.commons.net.ftp.FTPClientConfig; import org.apache.commons.net.ftp.FTPReply; import org.apache.commons.pool.PoolableObjectFactory; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Data Component ConfigurationProperties(ftp.factory) public class FTPClientFactory implements PoolableObjectFactoryFTPClient { private String hostname; private int port 21; private String username; private String password; private boolean passiveMode true; private String encoding UTF-8; private int clientTimeout 60000; private int fileType FTP.BINARY_FILE_TYPE; Override public FTPClient makeObject() throws Exception { FTPClient client new FTPClient(); client.setConnectTimeout(clientTimeout); client.setControlEncoding(encoding); client.connect(hostname, port); int reply client.getReplyCode(); if (!FTPReply.isPositiveCompletion(reply)) { client.disconnect(); throw new IllegalStateException(FTP 服务端拒绝连接reply reply); } if (!client.login(username, password)) { client.disconnect(); throw new IllegalStateException(FTP 登录失败); } FTPClientConfig conf new FTPClientConfig(FTPClientConfig.SYST_NT); conf.setServerLanguageCode(zh); client.configure(conf); if (passiveMode) { client.enterLocalPassiveMode(); } client.setFileType(fileType); return client; } Override public void destroyObject(FTPClient client) throws Exception { if (client ! null client.isConnected()) { client.logout(); client.disconnect(); } } Override public boolean validateObject(FTPClient client) { try { return client ! null client.isConnected() client.sendNoOp(); } catch (Exception e) { return false; } } Override public void activateObject(FTPClient client) { } Override public void passivateObject(FTPClient client) { } }这段工厂类的逻辑是makeObject建立连接并登录destroyObject退出并断开validateObject用NOOP判断连接是否还活着。参数上passive-mode: true在很多内网 FTP 环境里是必须的否则数据连接建不起来client-timeout不要设得太短报表文件大时上传会超时file-type: 2对应二进制传输避免 Excel/PDF 内容被文本模式改坏。FTP 的ReportProvider实现要按loadReport、saveReport、deleteReport、getReportFiles四个方法落到 FTP 命令上其中loadReport取到输入流后不要立刻断开连接先把流读完再归还连接否则会出现“预览为空、下载一半断流”的问题。凭据不要写死在 yml 里demo 可以实际项目用环境变量覆盖。5. 避坑排查启动失败、数据源为空、报表丢失怎么查5.1 启动期404 与 Servlet 映射现象应用启动成功访问/ureport/designer返回 404。原因通常是ServletRegistrationBean没注册或者映射被改成了/report/*。解决方式是回到Application.java确认new ServletRegistrationBean(new UReportServlet(), /ureport/*)存在并且启动类在父包或能扫描到配置类。另一个常见原因是ImportResource没加ureport-console-context.xml没进容器Servlet 初始化时拿不到必要 Bean。现象设计器页面能打开但静态资源 404样式全乱。原因多半是应用加了全局路径前缀比如server.servlet.context-path或者安全框架拦截了/ureport/**。解决时先看浏览器 Network 里静态资源的实际请求路径再确认安全框架是否放行/ureport/**和/ureport/designer。不要只改 Servlet 映射映射改了反而更乱。现象启动日志报NoClassDefFoundError或ClassNotFoundException。先查ureport2-console是否真的从仓库拉下来了再看有没有和 Spring 版本冲突。demo 显式写了spring-beans 5.0.4.RELEASE如果项目父 POM 管理了不同版本容易出现类冲突。解决方式是先跑mvn dependency:tree看spring-beans、spring-web的版本必要时删掉显式版本交给 Boot 统一管理。5.2 运行期数据源和参数为空现象设计器里数据源列表为空看不到MyDataSource。原因一般是UreportDataSource没加Component或者启动类扫描包不包含它。解决时先确认类上有Component再看启动类所在包是否能覆盖com.bstek.ureport.test。如果用了多模块检查ComponentScan有没有漏掉子模块。现象选中testBean后预览报“方法不存在”或数据集为空。原因通常是方法签名不对。UReport 要求方法包含String、String、Map三个参数返回List。少一个参数、参数顺序反了、返回null都会让设计器认为数据集不可用。解决时把方法头固定成public ListMapString,Object loadReportData(String dsName, String datasetName, MapString,Object parameters)先在 Java 里直接调用一次确认能返回数据再回设计器绑定。现象报表里参数传不进去SQL 条件一直为空。原因可能是报表参数名和 SQL 里的${}名称不一致或者 SpringBean 方法里没从parameters取值。解决时在设计器里看参数定义的大小写SQL 里先用固定值跑通再替换成参数SpringBean 里打印parameters.keySet()确认前端传进来的 key 到底是什么。不要靠猜参数名大小写在报表里很敏感。5.3 存储期重启丢报表与路径权限现象java -jar启动后保存的报表重启就没了。原因是用了默认文件存储落到了临时解压目录。解决方式是在application.properties里加ureport.disableFileProvidertrue并提供一个自定义ReportProvider。注意这个开关写在 yml 里读不到必须放 propertiescontext.xml里如果没打开ureport.propsUReport 内部属性读取也可能不生效。现象自定义本地存储保存时报“路径不存在”或“权限不足”。原因可能是ureport.fileStoreDir配了相对路径setApplicationContext里又拼了basePath最后落到了容器临时目录也可能是进程用户没有写权限。解决时先把目录配成绝对路径手动mkdir -p并chmod给应用用户再在代码里判断File.isAbsolute()绝对路径不再拼basePath。现象FTP 存储预览正常保存或下载大文件时断流。原因通常是 FTP 被动模式没开、client-timeout太短或者loadReport返回流之后连接被提前归还。解决时先开passive-mode: true把超时调到 60 秒以上再检查 provider 的loadReport是否先把流复制到内存或临时文件再关闭连接。大报表不要直接把 FTP 输入流交给上层连接池回收时机很难控。5.4 上线前检查表检查项检查位置通过标准Servlet 映射Application.java路径为/ureport/*未被安全框架拦截UReport 上下文context.xml已导入ureport-console-context.xml数据源名称BuildinDatasource.name()设计器里能看到且与报表数据集一致SpringBean 签名数据源方法三参数、返回 List、Bean 名与设计器一致默认存储开关application.propertiesureport.disableFileProvidertrue生效自定义存储目录ureport.fileStoreDir绝对路径、进程可读写、重启后文件还在FTP 连接ftp.factory配置登录成功、被动模式可用、大文件不中断导出格式设计器预览与导出Excel/PDF 字段完整、中文不乱码这张表建议在每次部署前走一遍尤其是换容器、换启动方式、换数据源的时候。UReport2 的很多问题不是代码写错而是配置落点不对把检查项固定下来比事后翻日志快得多。6. 进阶验证用一份最小报表跑通设计、预览与导出最小验证不要拿业务大表造一张三行数据的数据集就够。内置数据源里写select 1 as id, A as name, 100 as salary union all select 2, B, 200在设计器里新建数据集、绑定字段、拖到模板单元格预览能出三行再谈样式。这个动作能同时验证数据源连接、SQL 别名、字段绑定和模板渲染四件事。导出时分别点 Excel 和 PDF重点看中文、数字格式和空值列Excel 看表头是否合并错位PDF 看字体是否缺字。验证动作观察点失败时先查设计器打开左侧数据源列表Servlet 映射、context.xml数据集预览返回行数和字段名SQL 别名、数据源名称模板预览单元格绑定是否生效字段大小写、表达式写法导出 Excel合并单元格、中文模板样式、字体导出 PDF分页、缺字PDF 字体配置、列宽我一般会把这份最小报表留在工程里作为升级依赖后的回归用例。从那以后我每次接 UReport2都先把/ureport/*、数据源名、存储目录这三件事写进启动检查单再谈模板美观这三处不稳后面调样式全是白费。希望帮到你。本文还有配套的精品资源点击获取
