BaixuanZhu Java 质量门禁
面向 Java 代码交付前验证的工具门禁助手。用 JVM 插件链（PMD 7 + 自带规则集、SpotBugs + FindSecBugs）实跑扫描并按严重级修复，直到 Blocker/Critical 清零才算交付。
三条铁律
- 工具兜底，不再造规范：约束靠实跑的静态扫描（PMD 7 + SpotBugs），不重复堆砌编码规则；发现的告警若属编码手法问题，用本技能 references 速查表修复。
- 零侵入优先：默认在项目根建
.qualitygate/包装工程扫描，项目自身 pom 零改动；通过一次后才询问一次是否持久化进项目 pom，拒绝则不再问。 - 安全告警不自行豁免：误报抑制必须附注释理由并经用户确认；FindSecBugs 安全类告警 Agent 一律不得擅自 suppress。
工具链
| 层 | 工具 | 坐标（已实跑核实 2026-07） | 作用 |
|---|---|---|---|
| 规范层 | maven-pmd-plugin（PMD 7 内核） | org.apache.maven.plugins:maven-pmd-plugin:3.27.0（默认 PMD 7.14.0） |
源码级规范：空 catch、魔法值、命名、线程池、BigDecimal 等 |
| 规则集 | 技能自带 assets/pmd7-ruleset.xml |
随技能分发，无外部依赖 | 编码强制项（内置规则调参 + XPath 自定义） |
| bug/安全 | SpotBugs + FindSecBugs | com.github.spotbugs:spotbugs-maven-plugin:4.9.6.0 + com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0 |
字节码级 bug 模式 + 138 类安全漏洞 |
第 0 步：环境探测（激活时先执行）
读 pom.xml / build.gradle 一次性探测（读不到则一次问全，勿分多轮）：
- 构建工具：Maven（有
pom.xml）还是 Gradle；mvn -v/gradle -v是否可用。 - 目标 JDK：
maven.compiler.release/<source>/sourceCompatibility——决定 PMD 的targetJdk与编译参数（SpotBugs 需先编译）。 - 项目是否已配质量插件：pom/gradle 中是否已有
maven-pmd-plugin/spotbugs-maven-plugin/checkstyle/sonar——- 已配 → 直接复用项目自己的配置与规则集，不引入技能默认规则集（尊重团队既有基线）；仅在项目无规则集时才用技能自带的。
- 未配 → 走「接入方式」用技能自带规则集扫描。
- 无 Maven/Gradle 或不可用 → 告知无法实跑门禁，降级为「按 references 做人工对照检查」，并如实说明未做运行时验证。
接入方式（零侵入优先）
默认（零侵入）：在项目根建 .qualitygate/ 目录，写入包装 pom + 从技能 assets/ 拷入 pmd7-ruleset.xml；PMD 包装 pom 的 sourceDirectory 指向 ../src/main/java；SpotBugs 包装 pom 用 <classFilesDirectory> 指向 ../target/classes（被检项目须先 mvn compile）；把 .qualitygate/ 追加进 .gitignore。项目自身 pom 全程零改动。完整模板见 references/01-setup.md。
持久化（询问后）：.qualitygate/ 扫描通过一次后，询问一次是否把 PMD/SpotBugs 插件片段写入项目 pom（供团队 / CI 共享）；拒绝则保持零侵入、不再问。
门禁流程与退出条件
编译（SpotBugs 前置）→ PMD 扫描 + SpotBugs(FindSecBugs) 扫描 → 解析报告按严重级归并
→ 修复（Blocker→Critical→Major）→ 复扫 → Blocker/Critical 清零 → 交付
- 修复顺序：Blocker → Critical → Major；Minor 仅报告不强改。
- 退出条件：Blocker 与 Critical 必须清零才算通过；Major 尽量修，无法修的登记说明。
- 死循环保护：同一告警连续 2 轮修复仍无法消除 → 停下向用户说明原因并申请豁免，不无限重试。
- 严重级如何从 PMD priority / SpotBugs rank 映射到 Blocker/Critical/Major/Minor，见
references/04-fix-workflow.md。
误报 / 豁免规则
- 抑制手段（
@SuppressWarnings("PMD.RuleName")/ SpotBugs@SuppressFBWarnings/ exclude filter）必须附注释写明理由且须用户确认后才可加。 - Agent 不得自行豁免安全类告警（FindSecBugs SECURITY 类别、PMD security 规则）；只能如实上报并给修复建议。
- 判定为误报的标准与各工具的抑制写法见
references/04-fix-workflow.md。
决策路由表（按需读对应 reference，勿全量加载）
| 需求场景 | 读取文件 | 关键内容 |
|---|---|---|
搭建 .qualitygate/ 包装工程、包装 pom 模板、持久化片段、Gradle 等价配置、多模块适配、适用边界、报告路径 |
references/01-setup.md |
零侵入包装 pom、skipPmdError 容错、报告 XML 解析、多模块/Gradle/测试代码边界 |
| 自带规则集设计说明、规则映射表（含日志/性能/空集合）、XPath 自定义规则清单、高频告警→修复速查、规则集增改维护 | references/02-pmd-rules.md |
41 条内置规则 + 2 条 XPath 明细、如何新增一条 XPath 规则 |
| SpotBugs 高频 bug pattern→修复、FindSecBugs 安全规则重点（SQL 注入/弱加密/路径穿越/XXE/SSRF/硬编码密钥/反序列化/XSS/CRLF）→修复 | references/03-spotbugs-security.md |
NP_/EI_/DM_ 系列 + 安全类，已内联修复 |
| 严重级映射表、修复-复检循环操作、误报判定与抑制写法、批量告警分组修复策略 | references/04-fix-workflow.md |
priority/rank→四级分级、豁免规范 |
使用流程
- 第 0 步环境探测：构建工具 + JDK + 是否已配质量插件；已配则复用，未配走技能自带规则集。
- 接入：默认建
.qualitygate/零侵入包装工程（读references/01-setup.md）。 - 实跑扫描：先编译，再跑 PMD 与 SpotBugs(FindSecBugs)，产出 XML 报告。
- 按严重级修复：Blocker→Critical→Major 顺序（读
references/04-fix-workflow.md做分级），修复手法查02/03速查表。 - 复扫收敛：直到 Blocker/Critical 清零；同一告警 2 轮不消 → 说明并申请豁免。
- 询问持久化：通过后问一次是否把插件写进项目 pom，拒绝则保持零侵入。