企业官网建设流程全解析

简介：面向SonarQube插件开发者与代码质量团队的PDF报告生成插件源码，覆盖5.5至7.x多个版本，可解决代码分析结果难以直观共享、归档和跨项目传播的问题。工程以96个Java文件为逻辑主体，承担报告生成、数据组装与SonarQube API对接等核心工作；5个properties和3个xml用于扩展点注册与运行配置，PNG/JPG图片、ttf字体及YML、LICENSE等资源共同构成完整项目，全部121个文件打包为14.86MB的zip。已有307人学习下载。资源价值在于：既可直接编译部署生成定制化PDF报告，也可作为插件开发范本，学习如何在多版本兼容前提下设计可维护的Java/Ruby混合架构；源码中的目录结构与构建逻辑，对理解SonarQube插件生命周期及报告自动化有明确参考意义。

1. 为什么要在 SonarQube 5.5 到 7.x 上自己做 PDF 报告插件

做过代码质量门禁的人都知道，SonarQube 自带的 Web 界面和 REST API 能看趋势、查问题、导 CSV，但客户和领导要的往往是「一份能直接归档的 PDF」。官方从 7.x 开始逐步把内置的 PDF 报告功能弱化，社区插件大多停在某个旧版本，新装的 7.x 实例根本找不到能用的现成插件。于是很多团队只能翻出老的 5.x 代码改一改，或者从零写一个。这个标题的价值就在这里：它要求你同时理解 SonarQube 的插件扩展点、版本间的 API 断代，以及 PDF 生成这条完整的数据管线。

适合读这篇文章的人是后台开发或 DevOps 工程师，你已经知道 SonarQube 的基本用法，但没写过插件，或者写过一个内部工具但被版本兼容问题折磨过。我会以「源码设计」为线索，从插件入口、敏感数据校验、PDF 渲染管线一直讲到跨版本回归验证。先给出一个反直觉的结论：真正难的不是画 PDF，而是处理好 SonarQube 5.5 到 7.x 之间 API 签名变更带来的 ClassNotFoundException。

2. SonarQube 插件机制与版本兼容层：从 5.5 到 7.x 的 API 变迁

2.1 插件生命周期与扩展点：为什么报告插件挂在 Batch 侧

SonarQube 插件有四种运行容器：Server、Batch、Compute Engine、Scanner。PDF 报告插件必须挂在 Server 侧，因为只有 Server 才能访问聚合后的 Measure 和 Issue 数据。常见的做法是定义一个Plugin实现类，在define方法里注册一个Page扩展点，这个 Page 会在项目仪表盘的「更多」菜单里出现，用户点击后触发 Servlet 生成 PDF。

public final class PdfReportPlugin implements Plugin { @Override public void define(Context context) { context.addExtensions( PdfReportPage.class, PdfReportServlet.class, PdfReportService.class ); } }

这里有三个扩展点，对应三类职责：PdfReportPage负责 UI 入口，PdfReportServlet负责 HTTP 下载，PdfReportService负责装配数据并调用 PDF 引擎。参数说明：addExtensions接受 Class 数组，插件框架会自动按依赖关系实例化；不需要手动注解@Scoped，默认是普通单例。

2.2 5.5 到 6.7 的分水岭：org.sonar.api.batch与org.sonar.api.ce的拆分

5.5 时代，批处理和 Compute Engine 部分 API 混用，很多插件直接引用org.sonar.api.batch.measure.Metric来读数据。6.x 引入 Compute Engine 后，Measure的获取方式从Resource变成了Component，org.sonar.api.resources.Project也被org.sonar.api.ce.measure.Component取代。写兼容层时，我一般先抽象一个ProjectDataProvider接口，再按 SonarQube 版本提供不同实现：

public interface ProjectDataProvider { String projectKey(); String projectName(); Map<String, Double> metricValues(); } public class V55DataProvider implements ProjectDataProvider { private final Resource project; // 5.5 用 Resource 取 Measure } public class V7DataProvider implements ProjectDataProvider { private final Component project; // 7.x 用 Component.childrenMeasures() 取 Measure }

选择 Provider 的判断逻辑不能放在Plugin.define里，因为 define 阶段还没有版本号。正确位置是在 Servlet 或 Service 的构造函数里，通过SonarQubeVersion判断。代码片段如下：

public PdfReportService(PdfReportPage page, SonarQubeVersion version) { this.version = version; this.provider = version.isGreaterThanOrEquals(6, 0) ? new V7DataProvider() : new V55DataProvider(); }

这段代码的价值在于把版本差异收敛到一个边界上。SonarQubeVersion.isGreaterThanOrEquals(6, 0)在 5.5 和 7.x 里都存在，签名稳定，可以放心调用。

2.3 7.x 的Plugin.Context变化：别再硬编码getExtensions()

到了 7.x，Plugin.Context的内部实现从List改成了ExtensionInstaller驱动的集合，直接反射getExtensions()会抛NoSuchMethodError。如果源码设计里依赖了这个方法，就必须用addExtensions的 Class 数组重写。还有一个坑是org.sonar.api.resources.Qualifiers中PROJECT和VIEW的字符串常量，6.3 之后取消了VIEW，要用APP代替。下表总结了 5.5 → 7.x 的关键差异：

2.4 依赖打包的硬约束：用maven-shade-plugin避免 PDF 库类冲突

PDF 插件必然引入iText或OpenPDF，这些库如果直接打进 war 类加载器，会和 SonarQube 自带的类冲突。SonarQube 插件使用单例类加载器，规则是「父类优先，插件不能覆盖服务器类」。解决手段是做 shaded jar，并把 PDF 库 relocate 到com.example.pdf名下。

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <executions> <execution> <phase>package</phase> <goals><goal>shade</goal></goals> <configuration> <relocations> <relocation> <pattern>com.lowagie.text</pattern> <shadedPattern>com.example.pdf.lowagie.text</shadedPattern> </relocation> </relocations> <filters> <filter> <artifact>*:*</artifact> <excludes> <exclude>META-INF/*.SF</exclude> <exclude>META-INF/*.DSA</exclude> </excludes> </filter> </filters> </configuration> </execution> </executions> </plugin>

注意参数relocations里的pattern必须是 PDF 库的根包名。如果不做 relocate，插件上线后会间歇性出现NoClassDefFoundError，且只在某些页面触发，排查成本极高。

3. 源码结构设计：扩展点、权限校验与 PDF 渲染管线

3.1 插件目录与模块划分：接口、版本适配、前端资源分离

源码设计不需要把所有类塞进一个模块。按可维护性，我倾向于分成api-adapter（版本适配）、pdf-core（渲染）、server-plugin（扩展点注册）三个模块。目录结构如下：

sonarqube-pdf-plugin/ ├── api-adapter/ │ ├── src/main/java/org/example/adapter/ │ │ ├── ProjectDataProvider.java │ │ ├── V55DataProvider.java │ │ └── V7DataProvider.java ├── pdf-core/ │ ├── src/main/java/org/example/report/ │ │ ├── PdfRenderer.java │ │ ├── HtmlTemplateLoader.java │ │ └── ReportData.java └── server-plugin/ ├── src/main/java/org/example/plugin/ │ ├── PdfReportPlugin.java │ └── PdfReportServlet.java └── src/main/resources/static/ └── report.html

这个结构的好处是：pdf-core完全不知道 SonarQube 的类存在，可以单独测试；api-adapter依赖 SonarQube 但只放薄适配层，版本升级时替换整个模块不会波及核心渲染逻辑。

3.2 权限校验：不能只靠按钮可见性

报告里含项目名、Bug 数、漏洞详情，这些数据敏感，必须在 Servlet 里做二次校验。SonarQube 的Page扩展点可以在前端控制菜单显示，但正常浏览器可以构造 URL 直接访问 Servlet。所以源码里要注入UserSession并调用hasComponentPermission：

@Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) { String projectKey = req.getParameter("projectKey"); UserSession session = UserSession.get(); if (!session.hasComponentPermission(Permission.SCAN, projectKey)) { resp.sendError(HttpServletResponse.SC_FORBIDDEN); return; } // 后续生成 PDF }

这里Permission.SCAN是 SonarQube API 里最稳定的权限枚举之一。注意 5.5 里UserSession.get()已存在，但 6.0 后hasComponentPermission的第一个参数类型从String改成了Permission，写双版本兼容时要做一个PermissionResolver，传入项目 key 并返回 boolean。

3.3 PDF 渲染管线的三个步骤：拉数据、填模板、输出流

渲染管线我常用「JSON 中间层」设计：先聚合数据到ReportData，再序列化成 JSON 给模板，最后用 OpenPDF 渲染。这样测试时不需要起 SonarQube，直接喂 JSON 就能验证 PDF。

public class PdfRenderer { public byte[] render(ReportData data) throws IOException { String html = HtmlTemplateLoader.render("report.html", data); return ITextRenderer.fromHtml(html).pdf().build(); } }

ITextRenderer来自名称为openpdf的库，它的fromHtml能接受 HTML 字符串并输出 PDF 字节。参数说明：HtmlTemplateLoader.render使用 Freemarker 或 Thymeleaf，但为了减少依赖，可以用String.format拼装简单表格。真实项目里我会用 Freemarker，因为模板里要遍历 Measure 列表，String.format会失控。

3.4 数据聚合：把 Measure 和 Issue 的异步结果对齐

SonarQube 的指标计算是异步的，ProjectDataProvider拿到的 Measure 可能携带空值，尤其是「未分析」的项目。设计时需要约定：如果某指标无值，在 PDF 表格里显示—，而不是抛出 NPE。聚合逻辑如下：

public ReportData aggregate(String projectKey) { ReportData data = new ReportData(); for (MetricDefinition m : reportMetrics) { Double value = provider.metricValue(projectKey, m.key()); data.addMetric(m.displayName(), value == null ? null : round2(value)); } data.setIssueCount(provider.countIssuesBySeverity(projectKey)); return data; }

round2用来处理浮点数精度，避免出现 3.3000000000000003 这样的行。countIssuesBySeverity在 5.5 中可以用IssueQuery服务，在 7.x 中推荐用IssueFinder，但两者的返回结构差异不大，适配层封装即可。

4. 用 PDF 模板引擎输出可读报告：从 HTML 到 PDF 的参数与控制

4.1 为什么选择 HTML 转 PDF 而不是直接用 iText 画布

直接用 iText 的Document+PdfPTable写报告，代码会变成一长串 setter 调用，改个 Logo 位置就要重新编译。HTML 转 PDF 的方式把布局交给 CSS，维护成本低很多。OpenPDF 支持的 CSS 子集有限，但表格、字体、颜色、基本边框都没问题。模板头部我一般这样写：

<!DOCTYPE html> <html> <head> <style> body { font-family: "Noto Sans CJK SC", sans-serif; font-size: 10pt; } table.metrics { width: 100%; border-collapse: collapse; } .bug { color: #d4333f; font-weight: bold; } </style> </head> <body> <h2>${projectName} - 质量报告</h2> <table class="metrics"> <tr><th>指标</th><th>数值</th></tr> <#list metrics as m> <tr><td>${m.name}</td><td>${m.value}</td></tr> </#list> </table> </body> </html>

模板里的${projectName}和<#list metrics as m>是 Freemarker 语法。注意 OpenPDF 对 CSSborder-collapse支持不完整，如果边框消失，可以改成在每个<td>上直接写style="border:1px solid #ccc"，这是兼容性最好的做法。

4.2 分页与页眉页脚的三个控制参数

PDF 报告如果超过一页，默认没有页号，归档时不专业。OpenPDF 提供PdfWriter事件机制来加页眉页脚，但 HTML 转 PDF 时可以通过设置页面属性来实现：

ITextRenderer renderer = new ITextRenderer(); renderer.setDocumentFromString(html); renderer.getSharedContext().setPrintBackgroundColor(true); renderer.getSharedContext().setReplacedElementFactory( new Base64ImageReplacementFactory(renderer.getSharedContext()));

真正可控分页的是 CSS@page规则：

<style> @page { size: A4; margin: 2cm 1.5cm; @bottom-center { content: counter(page) " / " counter(pages); } } </style>

参数说明：@bottom-center里的counter(page)是 PagedMedia 规范的一部分，OpenPDF 支持这个方式；size: A4对应实际物理纸张，如果报告要电子分发，也可以设置成size: A4 landscape让表格更宽。

4.3 中文与 Logo 图片的编码坑：字体路径和 Base64 嵌入

中文乱码是 PDF 插件最常见的问题。SonarQube 服务器通常是 Linux 环境，系统里可能没有中文字体。两个办法：一是把字体文件打进插件 jar，二是使用服务器已安装的字体。我推荐前者，因为可控。把字体放进src/main/resources/fonts/，然后注册：

ITextFontResolver resolver = renderer.getFontResolver(); resolver.addFont("fonts/NotoSansSC-Regular.ttf", BaseFont.IDENTITY_H, BaseFont.EMBEDDED);

BaseFont.IDENTITY_H表示 UTF-16 编码，支持中文；BaseFont.EMBEDDED表示把字体内嵌到 PDF 里，避免打开 PDF 的机器没字体导致显示异常。Logo 图片不要用绝对路径引用服务器文件，最好转成 Base64 字符串直接写入 HTML：

String logoBase64 = Base64.getEncoder().encodeToString(logoBytes); String imgTag = "<img src='data:image/png;base64," + logoBase64 + "' width='120'/>";

这样 PDF 渲染时不需要访问真实文件系统，也不容易因为路径不存在而抛异常。

4.4 报告内容模块：Bug、漏洞、坏味道、重复率与覆盖率

一份能被客户接受的报告，至少要包含四类内容：问题分布、严重级别汇总、质量门禁结果、项目元信息。下表是我常用的指标映射：

在ProjectDataProvider里取这些指标时，5.5 的Resource.getMeasure("coverage")返回对象带getValue()；7.x 的Measure有getDoubleValue()，要注意空指针。我一般写成：

Double value = measure == null ? null : measureValue(measure);

其中measureValue内部判断 Version 再调用对应方法。

5. 兼容性回归的 3 个验证技巧：在 5.5 与 7.x 之间跑同一套测试

5.1 用嵌入式 Runner 在本地同时起两个 SonarQube 实例

插件源码设计完成后，光靠 mvn test 不够，必须在真实容器里验证。常见做法是用 Docker 分别启动sonarqube:5.5和sonarqube:7.9镜像，两个实例端口不一样。启动后把插件 jar 复制到extensions/plugins/，重启并运行一次扫描。

docker run -d --name sonar55 -p 9001:9000 sonarqube:5.5 docker run -d --name sonar79 -p 9002:9000 sonarqube:7.9

说明：5.5 镜像里默认没有中文字体，必须用docker cp把字体文件传进去并设置fc-cache。7.9 是 7.x 的最终版，API 行为能覆盖整个 7 系。

5.2 断言 PDF 中关键字符串而不是像素对比

PDF 回归测试不建议做像素级对比，环境差异会导致渲染差异。正确思路是解析 PDF 文本，断言包含「项目名称」「Bug 数」「质量门禁 OK」。这一步可以用pdfbox的PDFTextStripper。

PDDocument doc = PDDocument.load(pdfBytes); String text = new PDFTextStripper().getText(doc); assertTrue(text.contains("sample-project")); assertTrue(text.contains("质量门禁")); doc.close();

参数说明：PDFTextStripper.getText会按阅读顺序输出文本块，如果模板里用了 CSSorder属性改变视觉顺序，文本顺序可能与页面视觉不一致。解决方法是断言比文本块更小的粒度，比如「Blocker: 3」而不是整个表格。

5.3 模拟旧的 Scanner 版本触发 5.5 专属代码路径

很多团队只升级 SonarQube，不升级 Scanner，导致 5.5 服务器上跑的 Scanner 版本很老。插件内部如果调用了org.sonar.api.batch.ScannerSide的类，在 5.5 下正常工作，但 7.x 把这类移到org.sonar.scanner，会触发NoClassDefFoundError。回归技巧：在 CI 里加一个 job，用sonar-scanner-cli:3.0.3配合 5.5 实例扫描，再在 7.x 实例上用新 Scanner 扫描，确保两端都能生成 PDF。

sonar-scanner -Dsonar.host.url=http://localhost:9001 \ -Dsonar.projectKey=sample \ -Dsonar.sources=src \ -Dsonar.java.binaries=target/classes

这段命令里-Dsonar.host.url指向本地 5.5 实例；同样的命令把端口改成 9002 再跑一次，即可验证 7.x。如果 5.5 实例出现Unsupported major.minor version，说明插件编译用的 JDK 版本过高，需要降级<maven.compiler.source>1.8</maven.compiler.source>。

最后一招：在插件里加一个隐藏的系统属性开关-Dsonar.pdf.skip=true，一旦生成 PDF 导致扫描失败，可以临时跳过 PDF 步骤排查问题。把这个开关写进PdfReportServlet的第一个判断里，能省掉很多事故现场的抢救时间。

本文还有配套的精品资源，点击获取