112-java-maven-plugins

Maven 插件：pom.xml 配置最佳实践

使用结构化、以问题为导向的流程，在 pom.xml 中配置 Maven 插件和配置文件，同时保留现有配置。这是一个交互式 SKILL。

此 Skill 涵盖哪些内容？

Maven 插件：

• Maven Compiler
• Maven Enforcer
• Maven Surefire
• Maven Failsafe
• HTML 测试报告（Surefire Report、JXR）
• Maven Spotless
• Maven Flatten
• Maven Versions
• Maven Git Commit ID
• Maven Jib

Maven 配置文件：

• JaCoCo（代码覆盖率）
• PiTest（变异测试）
• 安全（OWASP 依赖项检查）
• 静态分析（SpotBugs、PMD）
• SonarQube/SonarCloud
• JMH（Java 微基准测试工具）
• 圈复杂度

约束

应用插件建议之前，确保项目处于有效状态。使用结构化、以问题为导向的流程，保留现有配置，并且只添加用户选择的内容。

• 必须：应用任何插件建议之前，运行 ./mvnw validate 或 mvn validate
• 安全：如果验证失败，停止并请用户修复问题；问题解决之前不得继续
• 范围：任何更改之前，从步骤 1（分析现有配置）开始。绝不移除或替换现有插件；只添加不会冲突的新插件
• 读取插件参考之前：先运行此 SKILL.md 中嵌入的问题流程。严格按顺序逐个提问，收集所有选定的插件/配置文件及条件值，然后只读取用户答案所选定的实现参考

何时使用此 Skill

• 在 pom.xml 中添加 Maven 插件
• 改进 pom.xml 中的 Maven 插件
• 在 pom.xml 中配置 Maven 质量插件
• 添加用于 Java 验证的 Maven 构建生命周期插件
• 检查 Maven 插件版本和执行配置

工作流

1. 更改插件前验证项目

运行 ./mvnw validate 或 mvn validate，如果验证失败则停止。

2. 分析当前插件和配置文件配置

对 pom.xml 进行任何更改之前：

1. 扫描 <build><plugins>、<build><pluginManagement> 和 <reporting><plugins> 中的现有插件。

2. 扫描 <properties> 中的现有属性。

3. 扫描 <profiles> 中的现有配置文件。

4. 确定现有配置与可能添加的内容之间是否存在冲突。

5. 保留所有现有插件、属性和配置文件。

6. 增强任何现有插件、属性、报告条目、支持文件或配置文件之前，先询问用户。

7. 除非用户明确要求增强，否则跳过重复添加。

8. 更改插件前检查 Maven Wrapper

检查项目根目录中是否存在 Maven Wrapper 文件：

• mvnw 和 mvnw.cmd
• .mvn/wrapper/maven-wrapper.properties

如果不存在 Maven Wrapper，则停止并询问：

"我注意到此项目尚未配置 Maven Wrapper。Maven Wrapper 可确保所有人使用相同的 Maven 版本，从而提高不同环境中的构建一致性。您希望我安装它吗？（y/n）"

等待用户回复后再提出其他问题。如果用户回答“y”，则安装它：

mvn wrapper:wrapper

4. 读取参考资料前询问 Maven 插件评估问题

读取任何插件/配置文件实现参考之前，先运行此 XML 内嵌的问题流程。每次只问一个问题，等待用户回答，并在继续之前记录所选插件、配置文件和条件值。

问题 1：这是什么类型的 Java 项目？

选项：

• Java 库（用于发布到 Maven Central/Nexus）
• Java CLI 应用（命令行工具）
• Java 微服务（Web 服务/REST API/模块化单体）
• 无服务器（AWS Lambdas、Azure Functions）
• Java 概念验证（Proof of Concept）
• 其他（请说明）

---

问题 2：您的项目目标 Java 版本是什么？

选项：

• Java 17（LTS——新项目推荐）
• Java 21（LTS——最新 LTS 版本）
• Java 25（LTS——最新 LTS 版本）
• 其他（请注明版本）

---

问题 3：对于你的项目，哪些构建和质量方面很重要？

选项：

• 格式化源代码（Spotless）
• Maven Enforcer
• 单元测试（Surefire）
• 单元测试报告（Surefire Reports）
• 集成测试（Failsafe）
• 代码覆盖率报告（JaCoCo）
• 变异测试（PiTest）
• 安全漏洞扫描（OWASP）
• 安全静态代码分析（SpotBugs、PMD）
• Sonar
• 依赖项分析（maven-dependency-plugin）
• 版本管理
• 容器映像构建（Jib）
• JMH（Java 微基准测试工具）
• Maven Compiler
• 圈复杂度

注意：选择“圈复杂度”后，步骤 20 将创建 PMD 规则集文件和配置文件。规则集位置取决于项目结构：src/main/pmd/pmd-cyclomatic-complexity.xml（单模块）或 pmd/pmd-cyclomatic-complexity.xml（多模块）。

---

问题 3.1（条件问题）：Jib 的目标容器映像是什么？

注意：仅当在问题 3 中选择了“容器映像构建（Jib）”时，才会询问此问题。

• 示例格式：gcr.io/my-project/my-app、docker.io/username/myimage，或用于本地 Docker 的 myimage
• 映像名称将用于 Jib 插件的 <to><image> 配置

---

问题 4：你的目标覆盖率阈值是多少？

选项：

• 70%（中等）
• 80%（推荐）
• 90%（高）
• 自定义百分比（请指定）

注意：仅当在问题 3 中选择了“代码覆盖率报告（JaCoCo）”时，才会询问此问题。

---

问题 5：是否要配置 Sonar/SonarCloud 集成？**（y/n）

注意：仅当在问题 3 中选择了“静态代码分析（SpotBugs、Sonar）”时，才会询问此问题。

如果是，请提供以下信息：

---

问题 5.1：你的 Sonar 组织标识符是什么？

• 对于 SonarCloud：通常是你的 GitHub 用户名或组织名称
• 对于 SonarQube：这是在 SonarQube 中配置的组织密钥
• 示例：my-github-user 或 my-company-org

---

问题 5.2：你的 Sonar 项目密钥是什么？

• 对于 SonarCloud：通常采用 GITHUB_USER_REPOSITORY_NAME 格式（例如，john-doe_my-java-project）
• 对于 SonarQube：在你的 SonarQube 实例中定义的自定义项目密钥
• 在你的 Sonar 组织内必须唯一
• 示例：john-doe_awesome-java-lib

---

问题 5.3：你的 Sonar 项目显示名称是什么？

• 项目在 Sonar 仪表板中显示的易读名称
• 可以包含空格和特殊字符
• 示例：Awesome Java Library 或 My Microservice API

---

问题 5.4：你使用的是哪种 Sonar 服务？（条件问题）

注意：仅当在问题 5 中启用了 Sonar 配置时，才会询问此问题。

选项：

• SonarCloud（https://sonarcloud.io）——推荐用于开源项目
• SonarQube Server（请指定服务器 URL）

如果使用 SonarQube Server：请提供你的 SonarQube 服务器 URL（例如，https://sonar.mycompany.com）

---

回答完所有适用的问题后，请确认所选项并将其映射到相应参考项：

• 如果选择了 Maven Compiler，请阅读 references/112-java-maven-plugins-maven-compiler-plugin.md。
• 如果选择了 Maven Enforcer，请阅读 references/112-java-maven-plugins-maven-enforcer-plugin.md。
• 如果选择了单元测试（Surefire），请阅读 references/112-java-maven-plugins-maven-surefire-plugin.md。
• 如果选择了集成测试（Failsafe），请阅读 references/112-java-maven-plugins-maven-failsafe-plugin.md。
• 如果选择了单元测试报告（Surefire Reports），请阅读 references/112-java-maven-plugins-maven-surefire-report-plugin.md 和 references/112-java-maven-plugins-maven-jxr-plugin.md。
• 如果选择了格式化源代码（Spotless），请阅读 references/112-java-maven-plugins-spotless-maven-plugin.md。
• 如果选择了版本管理，请阅读 references/112-java-maven-plugins-versions-maven-plugin.md。
• 如果选择了构建信息跟踪，请阅读 references/112-java-maven-plugins-git-commit-id-maven-plugin.md。
• 如果项目是 Java 库，请阅读 references/112-java-maven-plugins-flatten-maven-plugin.md。
• 如果选择了容器镜像构建（Jib），请阅读 references/112-java-maven-plugins-jib-maven-plugin.md。
• 如果选择了依赖项分析，请阅读 references/112-java-maven-plugins-maven-dependency-plugin.md。
• 如果选择了代码覆盖率报告（JaCoCo），请阅读 references/112-java-maven-plugins-profile-jacoco.md。
• 如果选择了变异测试（PiTest），请阅读 references/112-java-maven-plugins-profile-pitest.md。
• 如果选择了安全漏洞扫描（OWASP），请阅读 references/112-java-maven-plugins-profile-security.md。
• 如果选择了静态代码安全分析（SpotBugs、PMD），请阅读 references/112-java-maven-plugins-profile-static-analysis.md。
• 如果选择了 Sonar，请阅读 references/112-java-maven-plugins-profile-sonar.md。
• 如果选择了 JMH，请阅读 references/112-java-maven-plugins-profile-jmh.md。
• 如果选择了圈复杂度，请阅读 references/112-java-maven-plugins-profile-cyclomatic-complexity.md。
• 不要读取或应用未选中的插件/配置文件参考文档。

5. 读取已选参考文档并仅添加已选配置

添加已选插件和配置文件，不要移除现有内容，并保留项目结构和兼容性。仅添加已选参考文档所要求的 Maven 属性、插件配置、配置文件配置、报告插件和支持文件。

6. 总结已应用的插件设置

说明添加的插件/配置文件及其原因，并推荐后续执行的命令或检查。

参考

如需详细指南、示例和约束，请参阅：

• references/112-java-maven-plugins-maven-compiler-plugin.md
• references/112-java-maven-plugins-maven-enforcer-plugin.md
• references/112-java-maven-plugins-maven-surefire-plugin.md
• references/112-java-maven-plugins-maven-failsafe-plugin.md
• references/112-java-maven-plugins-maven-surefire-report-plugin.md
• references/112-java-maven-plugins-maven-jxr-plugin.md
• references/112-java-maven-plugins-spotless-maven-plugin.md
• references/112-java-maven-plugins-flatten-maven-plugin.md
• references/112-java-maven-plugins-versions-maven-plugin.md
• references/112-java-maven-plugins-git-commit-id-maven-plugin.md
• references/112-java-maven-plugins-jib-maven-plugin.md
• references/112-java-maven-plugins-maven-dependency-plugin.md
• references/112-java-maven-plugins-profile-jacoco.md
• references/112-java-maven-plugins-profile-pitest.md
• references/112-java-maven-plugins-profile-security.md
• references/112-java-maven-plugins-profile-static-analysis.md
• references/112-java-maven-plugins-profile-sonar.md
• references/112-java-maven-plugins-profile-jmh.md
• references/112-java-maven-plugins-profile-cyclomatic-complexity.md