java-coding-quality

Java 代码质量与安全的工具化门禁助手。在完成任何 Java / Spring Boot 代码的编写、修改、 重构后，或用户要求提交前检查、代码写完验证、代码审查 / code review、修复扫描告警、 质量门禁、静态扫描、安全扫描（SQL 注入 / 弱加密 / 路径穿越 / XXE / SSRF / 硬编码密钥）时使用本技能—— 无论用户是否提到具体工具（PMD / SpotBugs / FindSecBugs / Java 规约 / lint / static analysis）。 本技能用 JVM 插件链（PMD 7 + 自带规则集、SpotBugs + FindSecBugs）实

Java 质量门禁

面向 Java 代码交付前验证的工具门禁助手。用 JVM 插件链（PMD 7 + 自带规则集、SpotBugs + FindSecBugs）实跑扫描并按严重级修复，直到 Blocker/Critical 清零才算交付。

三条铁律

1. 工具兜底，不再造规范：约束靠实跑的静态扫描（PMD 7 + SpotBugs），不重复堆砌编码规则；发现的告警若属编码手法问题，用本技能 references 速查表修复。
2. 零侵入优先：默认在项目根建 .qualitygate/ 包装工程扫描，项目自身 pom 零改动；通过一次后才询问一次是否持久化进项目 pom，拒绝则不再问。
3. 安全告警不自行豁免：误报抑制必须附注释理由并经用户确认；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 一次性探测（读不到则一次问全，勿分多轮）：

1. 构建工具：Maven（有 pom.xml）还是 Gradle；mvn -v / gradle -v 是否可用。
2. 目标 JDK：maven.compiler.release / <source> / sourceCompatibility——决定 PMD 的 targetJdk 与编译参数（SpotBugs 需先编译）。
3. 项目是否已配质量插件：pom/gradle 中是否已有 maven-pmd-plugin / spotbugs-maven-plugin / checkstyle / sonar——
   • 已配 → 直接复用项目自己的配置与规则集，不引入技能默认规则集（尊重团队既有基线）；仅在项目无规则集时才用技能自带的。
   • 未配 → 走「接入方式」用技能自带规则集扫描。
4. 无 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 共享）；拒绝则保持零侵入、不再问。

门禁流程与退出条件

text

编译（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→四级分级、豁免规范

使用流程

1. 第 0 步环境探测：构建工具 + JDK + 是否已配质量插件；已配则复用，未配走技能自带规则集。
2. 接入：默认建 .qualitygate/ 零侵入包装工程（读 references/01-setup.md）。
3. 实跑扫描：先编译，再跑 PMD 与 SpotBugs(FindSecBugs)，产出 XML 报告。
4. 按严重级修复：Blocker→Critical→Major 顺序（读 references/04-fix-workflow.md 做分级），修复手法查 02/03 速查表。
5. 复扫收敛：直到 Blocker/Critical 清零；同一告警 2 轮不消 → 说明并申请豁免。
6. 询问持久化：通过后问一次是否把插件写进项目 pom，拒绝则保持零侵入。