干这行的都知道JavaWeb老项目在Eclipse里折腾覆盖率统计有多让人头大。项目代码堆在Dynamic Web Project里部署目标十有八九是Tomcat你可能连JUnit用例都没几条更麻烦的是还得从Eclipse这个启动入口把覆盖率工具无缝塞进去。JaCoCoJava Code Coverage作为目前最主流的Java覆盖率工具本身是好用的但官方文档给的示例大多是Maven命令行真正落到Eclipse Tomcat这套老开发环境时网上教程七零八落不是版本对不上就是参数配了半天没有数据。我这几年在好几个遗留系统上做过覆盖率改造从Eclipse里启动Tomcat到命令行手动跑junit再到把覆盖率报表交给客户看整个过程踩坑无数。这篇文章把整条链路拆开来写从JaCoCo的两种插桩模式怎么选到javaagent参数怎么填再到怎么用jacococli生成报表最后是Maven项目的另一条路整个过程尽量按实操来能直接照抄。1. 项目背景与整体配置思路拆解1.1 这个需求到底从哪来解决什么问题很多JavaWeb项目跑了好几年突然要做覆盖率评估多半是这几类情况一是客户或公司内部的质量门禁要求交付前必须给出核心模块的测试覆盖率报告哪怕是手工回归测试也得有数据说话。二是老系统要重构但业务人员不敢动项目组想先摸清现有的接口被测试覆盖到什么程度哪些代码是“死代码”哪些是核心路径。三是团队想给存量项目补单元测试但不知道从哪里下手覆盖率正好能指出哪些类命中率低、优先级高。单独看“Eclipse JavaWeb Jacoco Tomcat配置”这组关键词本质是传统Servlet/JSP项目在IDE环境下的覆盖率统计方案。这类项目通常没有干净的CI流水线也没有标准化的测试基建所有开发和验证都在开发者本机完成所以“在Eclipse启动的Tomcat里跑出覆盖率”就成了刚需。1.2 覆盖率工具选型为什么是JaCoCo在JaCoCo流行之前Java覆盖率工具主要是EMMA和Cobertura。EMMA是2005年前后的老古董支持类插桩但活跃度低Cobertura早年间用得不少但基于EMMA修改而来工具链老旧。我拿这三个做横向对比维度EMMACoberturaJaCoCo插桩方式支持离线插桩和在线插桩主要离线插桩on-the-fly运行时插桩 离线插桩报告粒度类、方法、行、块类、方法、行、分支指令、分支、行、方法、类、方法复杂度与JVM集成有自己的agent机制无官方agentjacocoagent直接随JVM启动活跃度停止维护停止维护持续维护官方支持反编译/源码关联弱一般支持maven、gradle、ant、sonar等生态JaCoCo的优势很直白支持on-the-fly插桩JVM启动时通过javaagent参数动态改写字节码不需要事后手动处理class文件对Eclipse启动Tomcat这个场景几乎是无侵入的。而且它还在持续更新对JDK8到JDK21都做了适配0.8.x系列一直在迭代这点很重要。1.3 整体配置链路先搞懂数据流再动手整套流程可以抽象成一条链路启动Tomcat时加载jacocoagent - JVM类加载阶段进行字节码插桩 - 测试或手工访问产生执行数据 - agent把执行记录写入本地exec文件 - 用jacococli读取exec文件结合class文件和源码生成覆盖率报表这里面最关键的一点是JaCoCo的agent模式并不会提前修改你磁盘上的class文件而是在类被JVM加载的那一刻动态地往字节码里“埋点”。所以只要让Tomcat的JVM启动参数带上javaagent项目里所有被加载的类都会被自动统计不需要额外改代码。这里有一个常见误区很多人以为只要在Eclipse里把jacocoagent.jar放进项目的classpath就行其实不是必须通过JVM启动参数加载否则agent根本不会生效。2. 环境准备Eclipse、Tomcat、Jacoco版本怎么搭配2.1 版本兼容性先看这里避免入坑Java覆盖率工具对JDK和Tomcat版本很敏感尤其是新版JDK的字节码结构变化后老版本JaCoCo会直接报错。我的建议是JDK8及以上JaCoCo必须用0.8.7以上版本JDK11及以上推荐0.8.8以上JDK17、JDK21需要0.8.10及以上。JDK版本JaCoCo版本要求说明JDK70.7.x/0.8.0太老能不用就不用JDK80.8.0最经典组合JDK110.8.6注意Unsupported class file major version 55JDK170.8.8注意Unsupported class file major version 61JDK210.8.10需要较新版本Tomcat版本方面Tomcat 8.5/9.0搭配JDK8非常稳定Eclipse也有对应的Server Runtime适配。Tomcat 10及以上迁移到了Jakarta命名空间javax改为jakarta如果你项目里还是javax.servlet的代码千万别直接配上Tomcat 10否则启动就报NoClassDefFoundError。老JavaWeb项目老老实实用Tomcat 9.0.x就好。2.2 Jacoco工具包下载与环境准备JaCoCo的发布包里同时包含了agent、CLI工具和Ant任务去GitHub官方Release页面下载文件名类似jacoco-0.8.11.zip。解压后里面结构很清晰jacoco-0.8.11/ ├── lib/ │ ├── jacocoagent.jar # 运行时插桩代理 │ ├── jacococli.jar # 命令行报告工具 │ └── jacocoant.jar # Ant任务工具 ├── doc/ # 官方文档 ├── test/ # 示例数据 └── index.html实际用到的只有两个jar文件jacocoagent.jar和jacococli.jar。我习惯把它们放在一个固定的目录比如D:\tools\jacoco-0.8.11\lib\这样后续配置启动参数时路径清清楚楚。下载时注意一点不要误下载jacoco-agent.zip那是给远程代理用的本地Eclipse调试用不到。2.3 Eclipse中的JavaWeb工程部署结构Eclipse里的JavaWeb项目有两种常见形态配置前务必确认清楚。传统Dynamic Web Project编译输出目录默认是build\classes在Servers视图中由Eclipse自动发布到临时部署目录这个目录通常是工作空间下的.metadata.plugins\org.eclipse.wst.server.core\tmp0\wtpwebapps\。如果你是这种项目生成报告时class文件路径就该指到build\classes。Maven Web项目编译输出目录是target\classesEclipse通过m2e插件识别部署到Tomcat时也是打成war或者exploded形式。生成报告时要指到target\classes。还有一个容易忽略的点如果你在Eclipse中修改了Java代码Eclipse会自动编译到对应的输出目录但Tomcat发布时不一定每次都完整同步导致实际运行的class文件和你用来生成报告的class文件不一致。覆盖率统计最大的敌人就是“报告里的class和实际跑的class对不上”后面我会专门讲这个问题。3. 核心环节在Eclipse中给Tomcat配置JaCoCo Agent3.1 两种插桩模式怎么选JaCoCo提供两种使用模式on-the-fly动态插桩和offline离线插桩。on-the-fly模式通过在JVM启动参数中加-javaagent在类加载时动态改写字节码。最明显的优点是不需要改动任何构建流程Tomcat里运行的代码就是原生代码。缺点是如果某个类在agent启动前就被加载比如JDK核心类这部分是统计不到的不过业务代码不存在这个问题。offline模式需要提前用一个instrument命令对class文件做字节码插桩再把插桩后的class部署到Tomcat。这种模式在动态代理、自定义ClassLoader特别多的场景下更稳定但操作繁琐每次代码变更都要重新插桩而且如果Tomcat容器有热加载机制插桩类很容易被原始类覆盖。对Eclipse Tomcat JavaWeb这个组合我强烈推荐直接上on-the-fly模式。原因是开发环境下代码变动频繁offline模式每改一次代码就要重新插桩再部署浪费时间而on-the-fly只要JVM参数正确代码怎么改都无所谓。3.2 Eclipse中Tomcat启动参数的三种配置入口要在Eclipse中给Tomcat注入javaagent有三个地方可以改作用和风险不一样第一种在Servers视图双击Tomcat实例打开Overview页点击“Open launch configuration”在Arguments的VM arguments里加参数。这个做法只对当前Eclipse里的这个Server实例生效修改保存在工作空间的.server配置里不会污染tomcat安装目录我最推荐。第二种修改Tomcat安装目录下的启动脚本比如Windows的bin\catalina.bat或Linux的bin\catalina.sh。在脚本里追加JAVA_OPTS参数。这样即使不通过Eclipse直接用命令行启动Tomcatagent也会生效适合后期做独立验证。第三种Eclipse的Run Configurations里找到对应Tomcat配置在Arguments标签页添加参数。效果和第一种类似但可读性不如Servers视图直观。我个人的固定操作是开发调试阶段用第一种最后要出正式覆盖率数据时把参数写进catalina脚本完全脱离Eclipse启动这样数据最干净。3.3 一条完整的javaagent参数逐段解释无论从哪里填参数核心就是这一条-javaagent:D:/tools/jacoco-0.8.11/lib/jacocoagent.jardestfileF:/logs/jacoco.exec,appendtrue,includescom.example.*,excludescom.example.framework.*,sessionidtomcat-debug-001一个一个参数拆开看destfileagent把执行数据写入的文件路径。目录必须先存在否则agent启动时报错。建议放在项目工作空间外的固定目录避免清理项目时误删。append取值true或false。true表示每次启动代理后新的执行数据追加到destfile已有的内容后面false表示覆盖旧文件。覆盖率统计如果不希望历史数据干扰可以每次统计前先删掉旧exec文件或者用appendfalse。includes类名的通配规则用逗号分隔多个匹配模式。这里填项目的包名前缀可以精确控制哪些类被统计。如果不填默认统计所有加载的非JDK类。JDK内部类、第三方框架类默认排除。excludes排除规则优先级高于includes。适合排除子框架代码比如我示例里的framework包。sessionid给当前执行会话起个名字报告里会显示多条会话记录方便区分不同轮次的测试。不是必填但多轮测试时强烈建议配。还有两个参数容易被忽略classdumpdir如果怀疑插桩方面出了问题可以配置此参数让agent把插桩后的class文件dump到指定目录检查字节码是否被改写。jmx配置为true后可以通过JMX远程控制agent重置数据。3.4 配置后的验证方式参数填好后在Eclipse中启动Tomcat观察控制台输出。正常的JaCoCo agent在JVM启动时不会打印太多信息但如果参数错误会立即报错。第一次配置我还闹过笑话-javaagent写成了-javagentTomcat启动时直接提示“Unrecognized option”这种低级错误最好通过控制台日志就能发现。如果启动过程中看到类似下面这样的信息说明agent加载成功了[2013-06-20 17:07:09] [JACOCO] JaCoCo Agent 0.8.11 started老版本约0.7.x会输出一些版本信息新版本默认静默。为了确认agent是否生效最稳妥的方法是启动Tomcat后随便访问一个项目接口然后停下Tomcat去destfile指定的路径看有没有生成exec文件文件大小是否在几十KB以上。一个空执行的agent文件通常只有一两KB业务类加载后exec会在几百KB到几MB之间。4. 实操过程从数据收集到生成覆盖率报告4.1 启动带Agent的Tomcat并产生数据这一步很多人忽略了一个关键行为agent数据什么时候落盘。JaCoCo的agent在执行过程中会逐步往destfile里写数据但如果Tomcat异常被杀掉比如Eclipse里直接点击红色停止按钮或者kill -9数据可能会丢失。我的习惯是设置appendtrue然后在Eclipse中正常“停止”Tomcat其实Eclipse点击停止按钮时通常会尝试优雅关停agent会收到JVM Shutdown Hook并完成数据落盘。如果你跑的是自动化测试比如JUnit或接口脚本完全可以通过脚本调用curl http://localhost:8080/your-web/order/list?pageNo1 curl http://localhost:8080/your-web/order/detail?id1001每个请求都会触发业务代码执行从而被agent记录。这样做的核心价值是即使项目没有任何单元测试只要能手工或脚本化访问Web服务覆盖率报告依然能生成。4.2 用jacococli生成HTML/XML/CSV报告数据收集完成后打开命令行使用jacococli.jar生成报告java -jar D:/tools/jacoco-0.8.11/lib/jacococli.jar report F:/logs/jacoco.exec \ --classfiles D:/workspace/demo-web/build/classes \ --sourcefiles D:/workspace/demo-web/src/main/java \ --html F:/logs/jacoco-report \ --xml F:/logs/jacoco-report/coverage.xml \ --csv F:/logs/jacoco-report/coverage.csv参数逐一说明--classfiles指定编译后的class文件目录。动态Web项目通常是build\classesMaven项目是target\classes。特别注意JaCoCo会按class文件的包名路径匹配exec里的类名目录结构如果不对输出报告显示0%。--sourcefiles指定Java源码目录用来在报告中显示源码级覆盖情况。Maven项目一般是src\main\java动态Web项目通常也是src/java或者src/main/java视你的项目结构而定。--html和--xml分别指定HTML和XML报告的输出目录或文件。命令执行完毕后打开HTML目录下的index.html即可看到覆盖报表。4.3 读懂覆盖率报告的四个指标拿到报告别急着高兴先搞清楚JaCoCo报告的指标含义否则没法跟客户交代。指标名称含义参考价值指令覆盖率Instruction字节码指令被执行的比例粒度最小最精准官方推荐分支覆盖率Branch条件判断中if/else等分支被命中的比例反映逻辑覆盖情况行覆盖率Line代码行被执行的比例最直观客户常见方法覆盖率Method方法被执行的比例快速找出完全没被调用的方法实操中我对外汇报一般是“核心接口的指令覆盖率和行覆盖率”因为指令覆盖率准确度高行覆盖率直观容易理解二者结合不会太虚。4.4 简单说说接入CI的思路如果团队有持续集成环境JaCoCo生成的XML报告可以交给SonarQube、Jenkins等工具解析实现自动化覆盖率门禁。不过那不是今天的重点Eclipse本地配置主要目的是先把手头的数据跑出来CI接入属于后续升级。5. 如果你的项目其实用了Maven5.1 为什么Maven项目推荐另走一条路很多JavaWeb项目虽然在Eclipse里开发但底层已经Maven化了pom.xml里躺着几十个依赖。这种情况下继续手动配置javaagent虽然可行但总感觉有点“复古”。Maven生态下JaCoCo官方提供了jacoco-maven-plugin一条命令就能完成插桩、运行、报告的全过程。不过必须先把一个重要的点讲透Maven插件和Tomcat运行时是两码事。mvn test启动的是Maven进程里的JUnit虚拟机它统计的是单元测试的覆盖率而你通过Eclipse启动的Tomcat是另一个JVM两者互不相干。所以如果你想要的是“测试代码直接调用业务类”的覆盖率用Maven插件如果你要的是“Web应用真实启动后通过HTTP请求或集成测试”的覆盖率那必须让Tomcat的JVM挂上agentMaven插件帮不上忙。5.2 pom.xml里最精简的JaCoCo配置单元测试覆盖率场景在pom.xml中添加如下配置build plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.11/version executions execution iddefault-prepare-agent/id goals goalprepare-agent/goal /goals /execution execution iddefault-report/id phasetest/phase goals goalreport/goal /goals /execution /executions /plugin /plugins /build然后执行mvn clean test命令结束后在target\site\jacoco目录下会自动生成覆盖率报告。prepare-agent目标会自动为测试JVM添加javaagent参数这一步对开发者是透明的。5.3 Maven Tomcat 容器级覆盖率怎么配合如果你在Maven项目里用tomcat7-maven-plugin或者cargo-maven-plugin来启动嵌入式/独立Tomcat想统计容器内代码覆盖率原理还是一样的给启动的Tomcat JVM加javaagent。以tomcat7-maven-plugin为例你可以在pom.xml的plugins配置里设置系统属性或者配置环境变量JAVA_OPTS。但说实话这种玩法配置会非常绕。我自己更推荐的做法是本地用Maven构建出war包把war丢到独立Tomcat的webapps目录然后用独立Tomcat的catalina脚本启动在setenv.bat/sh中配置JAVA_OPTS。Windows下在tomcat根目录新建bin\setenv.batset JAVA_OPTS%JAVA_OPTS% -javaagent:D:/tools/jacoco-0.8.11/lib/jacocoagent.jardestfileF:/logs/jacoco.exec,appendtrue,includescom.example.*Linux/Mac下新建bin/setenv.shexport JAVA_OPTS$JAVA_OPTS -javaagent:/tools/jacoco-0.8.11/lib/jacocoagent.jardestfile/logs/jacoco.exec,appendtrue,includescom.example.*这样启动后Tomcat加载的所有业务类都会被插桩统计。这也是我后面最常用的一种方式比Eclipse里配置更可控。5.4 多模块项目的处理多模块Maven项目还需要注意一点exec文件里记录的是整个JVM里加载的所有匹配类。如果你的web项目依赖了另一个模块比如common模块那在生成报告时--classfiles参数可以传多个目录java -jar /tools/jacoco-0.8.11/lib/jacococli.jar report /logs/jacoco.exec \ --classfiles /workspace/common/target/classes \ --classfiles /workspace/web/target/classes \ --sourcefiles /workspace/common/src/main/java \ --sourcefiles /workspace/web/src/main/java \ --html /logs/jacoco-report或者更简单用jacoco-maven-plugin的report-aggregate目标来做聚合报告不过那个更适合在CI环境统一生成。6. 常见问题与排查技巧实录6.1 Tomcat启动报“找不到或无法加载主类 org.apache.catalina.startup.Bootstrap”这个问题在Eclipse启动Tomcat时太常见了和JaCoCo本身无关但经常在配置agent时一起冒出来。原因一般是Eclipse的Server Runtime配置不正确或者tomcat目录被移动过。解决方式Window Preferences Server Runtime Environments删除原来的Tomcat runtime重新添加指向正确的Tomcat安装目录。然后再到项目的Properties Targeted Runtimes勾选对应的Tomcat版本。如果配置正确但还报这个错检查eclipse的Servers视图里那个server实例右键delete后重新建一个新的很多时候是旧server的类路径快照坏了。6.2 Tomcat启动正常但exec文件只有1-2KB或完全是空的这个现象非常让人抓狂第一次踩坑时我排查了整整一下午。exec文件太小几乎可以断定两种情况第一种是agent根本没加载成功。你检查一下Tomcat启动日志里有没有JaCoCo的初始化信息或者临时在javaagent参数里加上...改成一个明显不存在的destfile路径如果启动直接报路径不存在说明参数被正确解析了。第二种是includes配置太苛刻把业务类全排除了。比如你填了includescom.yourcompany.*但实际项目的包名是org.something那所有类都不匹配自然没有统计。把includes先去掉统计所有非JDK类看看exec文件大小是否变化就能定位是不是这个问题。有一个技巧首次配置时先把includes和excludes都去掉只保留destfile和append确认数据正常后再逐步收敛统计范围。6.3 Tomcat中文控制台乱码看着心烦开发老项目时控制台日志动不动乱码虽然不是致命问题但配合调试覆盖率时真的很影响心情。Eclipse里Tomcat控制台乱码多半是编码不一致导致的。先检查项目文件的编码Window Preferences General Workspace把Text file encoding改成UTF-8再在eclipse.ini中加上-Dfile.encodingUTF-8如果还乱去Tomcat的conf\logging.properties里把java.util.logging.ConsoleHandler.encoding改为UTF-8。6.4 覆盖率报告显示0%但exec文件有数据报告显示0%而exec文件正常九成是--classfiles路径不对。JaCoCo报告工具会拿exec里的类名去classfiles目录寻找对应的class文件找到后和exec数据里的类ID进行匹配class文件版本不一致都会匹配失败。比如Eclipse自动编译的build\classes里的一个class和你用Maven重新构建的target\classes里的同名class按说是一样但如果你先启动Tomcat跑数据又用另一个目录的class去生成报告类ID就对不上结果就是0%。解决办法确保生成报表用的class目录和Tomcat运行时加载的class目录是同一个目录。为此我在Eclipse里启动Tomcat前会先确认Servers配置的Deploy Path里同步的class是来自build\classes还是target\classes一致性是覆盖率统计的命根子。6.5 重复append导致数据虚高appendtrue虽然好但如果你一天内跑了好几轮测试exec文件里积累了旧数据报表看着覆盖率挺高实际可能是多轮数据叠加的结果。区分会话的一个办法是在报告HTML里查看Session信息每个会话有名字和时间。另一个办法是每次统计前先删掉旧的exec文件直接从干净状态开始。我在脚本里习惯这样写rm -f /logs/jacoco.exec java -jar /tools/jacoco-0.8.11/lib/jacococli.jar report /logs/jacoco.exec ...数据只有一轮报告口径清楚也方便追溯。6.6 关于Tomcat使用安全的一点提醒覆盖率配置既然涉及到Tomcat顺手说一句安全上的事。前几年Tomcat远程命令执行漏洞闹过好几轮很多老运维一听到Tomcat就紧张。如果你们用的还是Tomcat 8.0以下版本建议尽快升级到8.5.x的更新版本或9.0.x。配置覆盖率工具的时候顺便检查一下tomcat版本属于零成本的顺手加固别等项目被人扫出漏洞再补。7. 最后再分享一点小经验这套配置我前后做了不下十次最后总结出来一个最稳妥的组合拳开发调试阶段直接在Eclipse的Tomcat启动参数里挂agent图的是方便代码改了热部署后覆盖率数据照样能累积真正要给客户或质量部门交报告时改成Maven打包war丢到独立Tomcat用setenv脚本统一注入javaagent配合脚本清理旧exec这样数据可控、过程可复现、报告也干净。如果项目里刚起步、测试用例还很少尽量让手工回归的过程也走一遍Web接口别只看JUnit跑出来的数据。因为JavaWeb项目很多问题暴露在容器环境里比如Filter、Listener、Servlet路径匹配这些纯单元测试根本覆盖不到。JaCoCo的价值就是让这些真实运行路径能体现在同一个报表里。工具是死的思路是活的。你们如果配完之后数据还是不对八成是先别急着怀疑JaCoCo回头检查一下Tomcat跑的是不是你最后编译的那份class。这个问题想通了整套配置就通了。
干这行的都知道JavaWeb老项目在Eclipse里折腾覆盖率统计有多让人头大。项目代码堆在Dynamic Web Project里部署目标十有八九是Tomcat你可能连JUnit用例都没几条更麻烦的是还得从Eclipse这个启动入口把覆盖率工具无缝塞进去。JaCoCoJava Code Coverage作为目前最主流的Java覆盖率工具本身是好用的但官方文档给的示例大多是Maven命令行真正落到Eclipse Tomcat这套老开发环境时网上教程七零八落不是版本对不上就是参数配了半天没有数据。我这几年在好几个遗留系统上做过覆盖率改造从Eclipse里启动Tomcat到命令行手动跑junit再到把覆盖率报表交给客户看整个过程踩坑无数。这篇文章把整条链路拆开来写从JaCoCo的两种插桩模式怎么选到javaagent参数怎么填再到怎么用jacococli生成报表最后是Maven项目的另一条路整个过程尽量按实操来能直接照抄。1. 项目背景与整体配置思路拆解1.1 这个需求到底从哪来解决什么问题很多JavaWeb项目跑了好几年突然要做覆盖率评估多半是这几类情况一是客户或公司内部的质量门禁要求交付前必须给出核心模块的测试覆盖率报告哪怕是手工回归测试也得有数据说话。二是老系统要重构但业务人员不敢动项目组想先摸清现有的接口被测试覆盖到什么程度哪些代码是“死代码”哪些是核心路径。三是团队想给存量项目补单元测试但不知道从哪里下手覆盖率正好能指出哪些类命中率低、优先级高。单独看“Eclipse JavaWeb Jacoco Tomcat配置”这组关键词本质是传统Servlet/JSP项目在IDE环境下的覆盖率统计方案。这类项目通常没有干净的CI流水线也没有标准化的测试基建所有开发和验证都在开发者本机完成所以“在Eclipse启动的Tomcat里跑出覆盖率”就成了刚需。1.2 覆盖率工具选型为什么是JaCoCo在JaCoCo流行之前Java覆盖率工具主要是EMMA和Cobertura。EMMA是2005年前后的老古董支持类插桩但活跃度低Cobertura早年间用得不少但基于EMMA修改而来工具链老旧。我拿这三个做横向对比维度EMMACoberturaJaCoCo插桩方式支持离线插桩和在线插桩主要离线插桩on-the-fly运行时插桩 离线插桩报告粒度类、方法、行、块类、方法、行、分支指令、分支、行、方法、类、方法复杂度与JVM集成有自己的agent机制无官方agentjacocoagent直接随JVM启动活跃度停止维护停止维护持续维护官方支持反编译/源码关联弱一般支持maven、gradle、ant、sonar等生态JaCoCo的优势很直白支持on-the-fly插桩JVM启动时通过javaagent参数动态改写字节码不需要事后手动处理class文件对Eclipse启动Tomcat这个场景几乎是无侵入的。而且它还在持续更新对JDK8到JDK21都做了适配0.8.x系列一直在迭代这点很重要。1.3 整体配置链路先搞懂数据流再动手整套流程可以抽象成一条链路启动Tomcat时加载jacocoagent - JVM类加载阶段进行字节码插桩 - 测试或手工访问产生执行数据 - agent把执行记录写入本地exec文件 - 用jacococli读取exec文件结合class文件和源码生成覆盖率报表这里面最关键的一点是JaCoCo的agent模式并不会提前修改你磁盘上的class文件而是在类被JVM加载的那一刻动态地往字节码里“埋点”。所以只要让Tomcat的JVM启动参数带上javaagent项目里所有被加载的类都会被自动统计不需要额外改代码。这里有一个常见误区很多人以为只要在Eclipse里把jacocoagent.jar放进项目的classpath就行其实不是必须通过JVM启动参数加载否则agent根本不会生效。2. 环境准备Eclipse、Tomcat、Jacoco版本怎么搭配2.1 版本兼容性先看这里避免入坑Java覆盖率工具对JDK和Tomcat版本很敏感尤其是新版JDK的字节码结构变化后老版本JaCoCo会直接报错。我的建议是JDK8及以上JaCoCo必须用0.8.7以上版本JDK11及以上推荐0.8.8以上JDK17、JDK21需要0.8.10及以上。JDK版本JaCoCo版本要求说明JDK70.7.x/0.8.0太老能不用就不用JDK80.8.0最经典组合JDK110.8.6注意Unsupported class file major version 55JDK170.8.8注意Unsupported class file major version 61JDK210.8.10需要较新版本Tomcat版本方面Tomcat 8.5/9.0搭配JDK8非常稳定Eclipse也有对应的Server Runtime适配。Tomcat 10及以上迁移到了Jakarta命名空间javax改为jakarta如果你项目里还是javax.servlet的代码千万别直接配上Tomcat 10否则启动就报NoClassDefFoundError。老JavaWeb项目老老实实用Tomcat 9.0.x就好。2.2 Jacoco工具包下载与环境准备JaCoCo的发布包里同时包含了agent、CLI工具和Ant任务去GitHub官方Release页面下载文件名类似jacoco-0.8.11.zip。解压后里面结构很清晰jacoco-0.8.11/ ├── lib/ │ ├── jacocoagent.jar # 运行时插桩代理 │ ├── jacococli.jar # 命令行报告工具 │ └── jacocoant.jar # Ant任务工具 ├── doc/ # 官方文档 ├── test/ # 示例数据 └── index.html实际用到的只有两个jar文件jacocoagent.jar和jacococli.jar。我习惯把它们放在一个固定的目录比如D:\tools\jacoco-0.8.11\lib\这样后续配置启动参数时路径清清楚楚。下载时注意一点不要误下载jacoco-agent.zip那是给远程代理用的本地Eclipse调试用不到。2.3 Eclipse中的JavaWeb工程部署结构Eclipse里的JavaWeb项目有两种常见形态配置前务必确认清楚。传统Dynamic Web Project编译输出目录默认是build\classes在Servers视图中由Eclipse自动发布到临时部署目录这个目录通常是工作空间下的.metadata.plugins\org.eclipse.wst.server.core\tmp0\wtpwebapps\。如果你是这种项目生成报告时class文件路径就该指到build\classes。Maven Web项目编译输出目录是target\classesEclipse通过m2e插件识别部署到Tomcat时也是打成war或者exploded形式。生成报告时要指到target\classes。还有一个容易忽略的点如果你在Eclipse中修改了Java代码Eclipse会自动编译到对应的输出目录但Tomcat发布时不一定每次都完整同步导致实际运行的class文件和你用来生成报告的class文件不一致。覆盖率统计最大的敌人就是“报告里的class和实际跑的class对不上”后面我会专门讲这个问题。3. 核心环节在Eclipse中给Tomcat配置JaCoCo Agent3.1 两种插桩模式怎么选JaCoCo提供两种使用模式on-the-fly动态插桩和offline离线插桩。on-the-fly模式通过在JVM启动参数中加-javaagent在类加载时动态改写字节码。最明显的优点是不需要改动任何构建流程Tomcat里运行的代码就是原生代码。缺点是如果某个类在agent启动前就被加载比如JDK核心类这部分是统计不到的不过业务代码不存在这个问题。offline模式需要提前用一个instrument命令对class文件做字节码插桩再把插桩后的class部署到Tomcat。这种模式在动态代理、自定义ClassLoader特别多的场景下更稳定但操作繁琐每次代码变更都要重新插桩而且如果Tomcat容器有热加载机制插桩类很容易被原始类覆盖。对Eclipse Tomcat JavaWeb这个组合我强烈推荐直接上on-the-fly模式。原因是开发环境下代码变动频繁offline模式每改一次代码就要重新插桩再部署浪费时间而on-the-fly只要JVM参数正确代码怎么改都无所谓。3.2 Eclipse中Tomcat启动参数的三种配置入口要在Eclipse中给Tomcat注入javaagent有三个地方可以改作用和风险不一样第一种在Servers视图双击Tomcat实例打开Overview页点击“Open launch configuration”在Arguments的VM arguments里加参数。这个做法只对当前Eclipse里的这个Server实例生效修改保存在工作空间的.server配置里不会污染tomcat安装目录我最推荐。第二种修改Tomcat安装目录下的启动脚本比如Windows的bin\catalina.bat或Linux的bin\catalina.sh。在脚本里追加JAVA_OPTS参数。这样即使不通过Eclipse直接用命令行启动Tomcatagent也会生效适合后期做独立验证。第三种Eclipse的Run Configurations里找到对应Tomcat配置在Arguments标签页添加参数。效果和第一种类似但可读性不如Servers视图直观。我个人的固定操作是开发调试阶段用第一种最后要出正式覆盖率数据时把参数写进catalina脚本完全脱离Eclipse启动这样数据最干净。3.3 一条完整的javaagent参数逐段解释无论从哪里填参数核心就是这一条-javaagent:D:/tools/jacoco-0.8.11/lib/jacocoagent.jardestfileF:/logs/jacoco.exec,appendtrue,includescom.example.*,excludescom.example.framework.*,sessionidtomcat-debug-001一个一个参数拆开看destfileagent把执行数据写入的文件路径。目录必须先存在否则agent启动时报错。建议放在项目工作空间外的固定目录避免清理项目时误删。append取值true或false。true表示每次启动代理后新的执行数据追加到destfile已有的内容后面false表示覆盖旧文件。覆盖率统计如果不希望历史数据干扰可以每次统计前先删掉旧exec文件或者用appendfalse。includes类名的通配规则用逗号分隔多个匹配模式。这里填项目的包名前缀可以精确控制哪些类被统计。如果不填默认统计所有加载的非JDK类。JDK内部类、第三方框架类默认排除。excludes排除规则优先级高于includes。适合排除子框架代码比如我示例里的framework包。sessionid给当前执行会话起个名字报告里会显示多条会话记录方便区分不同轮次的测试。不是必填但多轮测试时强烈建议配。还有两个参数容易被忽略classdumpdir如果怀疑插桩方面出了问题可以配置此参数让agent把插桩后的class文件dump到指定目录检查字节码是否被改写。jmx配置为true后可以通过JMX远程控制agent重置数据。3.4 配置后的验证方式参数填好后在Eclipse中启动Tomcat观察控制台输出。正常的JaCoCo agent在JVM启动时不会打印太多信息但如果参数错误会立即报错。第一次配置我还闹过笑话-javaagent写成了-javagentTomcat启动时直接提示“Unrecognized option”这种低级错误最好通过控制台日志就能发现。如果启动过程中看到类似下面这样的信息说明agent加载成功了[2013-06-20 17:07:09] [JACOCO] JaCoCo Agent 0.8.11 started老版本约0.7.x会输出一些版本信息新版本默认静默。为了确认agent是否生效最稳妥的方法是启动Tomcat后随便访问一个项目接口然后停下Tomcat去destfile指定的路径看有没有生成exec文件文件大小是否在几十KB以上。一个空执行的agent文件通常只有一两KB业务类加载后exec会在几百KB到几MB之间。4. 实操过程从数据收集到生成覆盖率报告4.1 启动带Agent的Tomcat并产生数据这一步很多人忽略了一个关键行为agent数据什么时候落盘。JaCoCo的agent在执行过程中会逐步往destfile里写数据但如果Tomcat异常被杀掉比如Eclipse里直接点击红色停止按钮或者kill -9数据可能会丢失。我的习惯是设置appendtrue然后在Eclipse中正常“停止”Tomcat其实Eclipse点击停止按钮时通常会尝试优雅关停agent会收到JVM Shutdown Hook并完成数据落盘。如果你跑的是自动化测试比如JUnit或接口脚本完全可以通过脚本调用curl http://localhost:8080/your-web/order/list?pageNo1 curl http://localhost:8080/your-web/order/detail?id1001每个请求都会触发业务代码执行从而被agent记录。这样做的核心价值是即使项目没有任何单元测试只要能手工或脚本化访问Web服务覆盖率报告依然能生成。4.2 用jacococli生成HTML/XML/CSV报告数据收集完成后打开命令行使用jacococli.jar生成报告java -jar D:/tools/jacoco-0.8.11/lib/jacococli.jar report F:/logs/jacoco.exec \ --classfiles D:/workspace/demo-web/build/classes \ --sourcefiles D:/workspace/demo-web/src/main/java \ --html F:/logs/jacoco-report \ --xml F:/logs/jacoco-report/coverage.xml \ --csv F:/logs/jacoco-report/coverage.csv参数逐一说明--classfiles指定编译后的class文件目录。动态Web项目通常是build\classesMaven项目是target\classes。特别注意JaCoCo会按class文件的包名路径匹配exec里的类名目录结构如果不对输出报告显示0%。--sourcefiles指定Java源码目录用来在报告中显示源码级覆盖情况。Maven项目一般是src\main\java动态Web项目通常也是src/java或者src/main/java视你的项目结构而定。--html和--xml分别指定HTML和XML报告的输出目录或文件。命令执行完毕后打开HTML目录下的index.html即可看到覆盖报表。4.3 读懂覆盖率报告的四个指标拿到报告别急着高兴先搞清楚JaCoCo报告的指标含义否则没法跟客户交代。指标名称含义参考价值指令覆盖率Instruction字节码指令被执行的比例粒度最小最精准官方推荐分支覆盖率Branch条件判断中if/else等分支被命中的比例反映逻辑覆盖情况行覆盖率Line代码行被执行的比例最直观客户常见方法覆盖率Method方法被执行的比例快速找出完全没被调用的方法实操中我对外汇报一般是“核心接口的指令覆盖率和行覆盖率”因为指令覆盖率准确度高行覆盖率直观容易理解二者结合不会太虚。4.4 简单说说接入CI的思路如果团队有持续集成环境JaCoCo生成的XML报告可以交给SonarQube、Jenkins等工具解析实现自动化覆盖率门禁。不过那不是今天的重点Eclipse本地配置主要目的是先把手头的数据跑出来CI接入属于后续升级。5. 如果你的项目其实用了Maven5.1 为什么Maven项目推荐另走一条路很多JavaWeb项目虽然在Eclipse里开发但底层已经Maven化了pom.xml里躺着几十个依赖。这种情况下继续手动配置javaagent虽然可行但总感觉有点“复古”。Maven生态下JaCoCo官方提供了jacoco-maven-plugin一条命令就能完成插桩、运行、报告的全过程。不过必须先把一个重要的点讲透Maven插件和Tomcat运行时是两码事。mvn test启动的是Maven进程里的JUnit虚拟机它统计的是单元测试的覆盖率而你通过Eclipse启动的Tomcat是另一个JVM两者互不相干。所以如果你想要的是“测试代码直接调用业务类”的覆盖率用Maven插件如果你要的是“Web应用真实启动后通过HTTP请求或集成测试”的覆盖率那必须让Tomcat的JVM挂上agentMaven插件帮不上忙。5.2 pom.xml里最精简的JaCoCo配置单元测试覆盖率场景在pom.xml中添加如下配置build plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.11/version executions execution iddefault-prepare-agent/id goals goalprepare-agent/goal /goals /execution execution iddefault-report/id phasetest/phase goals goalreport/goal /goals /execution /executions /plugin /plugins /build然后执行mvn clean test命令结束后在target\site\jacoco目录下会自动生成覆盖率报告。prepare-agent目标会自动为测试JVM添加javaagent参数这一步对开发者是透明的。5.3 Maven Tomcat 容器级覆盖率怎么配合如果你在Maven项目里用tomcat7-maven-plugin或者cargo-maven-plugin来启动嵌入式/独立Tomcat想统计容器内代码覆盖率原理还是一样的给启动的Tomcat JVM加javaagent。以tomcat7-maven-plugin为例你可以在pom.xml的plugins配置里设置系统属性或者配置环境变量JAVA_OPTS。但说实话这种玩法配置会非常绕。我自己更推荐的做法是本地用Maven构建出war包把war丢到独立Tomcat的webapps目录然后用独立Tomcat的catalina脚本启动在setenv.bat/sh中配置JAVA_OPTS。Windows下在tomcat根目录新建bin\setenv.batset JAVA_OPTS%JAVA_OPTS% -javaagent:D:/tools/jacoco-0.8.11/lib/jacocoagent.jardestfileF:/logs/jacoco.exec,appendtrue,includescom.example.*Linux/Mac下新建bin/setenv.shexport JAVA_OPTS$JAVA_OPTS -javaagent:/tools/jacoco-0.8.11/lib/jacocoagent.jardestfile/logs/jacoco.exec,appendtrue,includescom.example.*这样启动后Tomcat加载的所有业务类都会被插桩统计。这也是我后面最常用的一种方式比Eclipse里配置更可控。5.4 多模块项目的处理多模块Maven项目还需要注意一点exec文件里记录的是整个JVM里加载的所有匹配类。如果你的web项目依赖了另一个模块比如common模块那在生成报告时--classfiles参数可以传多个目录java -jar /tools/jacoco-0.8.11/lib/jacococli.jar report /logs/jacoco.exec \ --classfiles /workspace/common/target/classes \ --classfiles /workspace/web/target/classes \ --sourcefiles /workspace/common/src/main/java \ --sourcefiles /workspace/web/src/main/java \ --html /logs/jacoco-report或者更简单用jacoco-maven-plugin的report-aggregate目标来做聚合报告不过那个更适合在CI环境统一生成。6. 常见问题与排查技巧实录6.1 Tomcat启动报“找不到或无法加载主类 org.apache.catalina.startup.Bootstrap”这个问题在Eclipse启动Tomcat时太常见了和JaCoCo本身无关但经常在配置agent时一起冒出来。原因一般是Eclipse的Server Runtime配置不正确或者tomcat目录被移动过。解决方式Window Preferences Server Runtime Environments删除原来的Tomcat runtime重新添加指向正确的Tomcat安装目录。然后再到项目的Properties Targeted Runtimes勾选对应的Tomcat版本。如果配置正确但还报这个错检查eclipse的Servers视图里那个server实例右键delete后重新建一个新的很多时候是旧server的类路径快照坏了。6.2 Tomcat启动正常但exec文件只有1-2KB或完全是空的这个现象非常让人抓狂第一次踩坑时我排查了整整一下午。exec文件太小几乎可以断定两种情况第一种是agent根本没加载成功。你检查一下Tomcat启动日志里有没有JaCoCo的初始化信息或者临时在javaagent参数里加上...改成一个明显不存在的destfile路径如果启动直接报路径不存在说明参数被正确解析了。第二种是includes配置太苛刻把业务类全排除了。比如你填了includescom.yourcompany.*但实际项目的包名是org.something那所有类都不匹配自然没有统计。把includes先去掉统计所有非JDK类看看exec文件大小是否变化就能定位是不是这个问题。有一个技巧首次配置时先把includes和excludes都去掉只保留destfile和append确认数据正常后再逐步收敛统计范围。6.3 Tomcat中文控制台乱码看着心烦开发老项目时控制台日志动不动乱码虽然不是致命问题但配合调试覆盖率时真的很影响心情。Eclipse里Tomcat控制台乱码多半是编码不一致导致的。先检查项目文件的编码Window Preferences General Workspace把Text file encoding改成UTF-8再在eclipse.ini中加上-Dfile.encodingUTF-8如果还乱去Tomcat的conf\logging.properties里把java.util.logging.ConsoleHandler.encoding改为UTF-8。6.4 覆盖率报告显示0%但exec文件有数据报告显示0%而exec文件正常九成是--classfiles路径不对。JaCoCo报告工具会拿exec里的类名去classfiles目录寻找对应的class文件找到后和exec数据里的类ID进行匹配class文件版本不一致都会匹配失败。比如Eclipse自动编译的build\classes里的一个class和你用Maven重新构建的target\classes里的同名class按说是一样但如果你先启动Tomcat跑数据又用另一个目录的class去生成报告类ID就对不上结果就是0%。解决办法确保生成报表用的class目录和Tomcat运行时加载的class目录是同一个目录。为此我在Eclipse里启动Tomcat前会先确认Servers配置的Deploy Path里同步的class是来自build\classes还是target\classes一致性是覆盖率统计的命根子。6.5 重复append导致数据虚高appendtrue虽然好但如果你一天内跑了好几轮测试exec文件里积累了旧数据报表看着覆盖率挺高实际可能是多轮数据叠加的结果。区分会话的一个办法是在报告HTML里查看Session信息每个会话有名字和时间。另一个办法是每次统计前先删掉旧的exec文件直接从干净状态开始。我在脚本里习惯这样写rm -f /logs/jacoco.exec java -jar /tools/jacoco-0.8.11/lib/jacococli.jar report /logs/jacoco.exec ...数据只有一轮报告口径清楚也方便追溯。6.6 关于Tomcat使用安全的一点提醒覆盖率配置既然涉及到Tomcat顺手说一句安全上的事。前几年Tomcat远程命令执行漏洞闹过好几轮很多老运维一听到Tomcat就紧张。如果你们用的还是Tomcat 8.0以下版本建议尽快升级到8.5.x的更新版本或9.0.x。配置覆盖率工具的时候顺便检查一下tomcat版本属于零成本的顺手加固别等项目被人扫出漏洞再补。7. 最后再分享一点小经验这套配置我前后做了不下十次最后总结出来一个最稳妥的组合拳开发调试阶段直接在Eclipse的Tomcat启动参数里挂agent图的是方便代码改了热部署后覆盖率数据照样能累积真正要给客户或质量部门交报告时改成Maven打包war丢到独立Tomcat用setenv脚本统一注入javaagent配合脚本清理旧exec这样数据可控、过程可复现、报告也干净。如果项目里刚起步、测试用例还很少尽量让手工回归的过程也走一遍Web接口别只看JUnit跑出来的数据。因为JavaWeb项目很多问题暴露在容器环境里比如Filter、Listener、Servlet路径匹配这些纯单元测试根本覆盖不到。JaCoCo的价值就是让这些真实运行路径能体现在同一个报表里。工具是死的思路是活的。你们如果配完之后数据还是不对八成是先别急着怀疑JaCoCo回头检查一下Tomcat跑的是不是你最后编译的那份class。这个问题想通了整套配置就通了。
