概述
当开发者将自己的java库发布到maven central时，有时会遇到一个常见问题：尽管项目成功部署，但在ide（如intellij idea）中导入该库后，却无法看到其javadoc。这不仅影响了库的可维护性和用户体验，也表明部署过程可能存在不完整或不符合maven central规范的地方。通常，此类问题源于缺少源码jar、javadoc jar或未对工件进行gpg签名。
Maven Central部署要求
Maven Central（通过Sonatype OSSRH）对所有上传的工件都有严格的规定，以确保库的质量和可追溯性。其中最关键的几点包括：
- 所有工件必须签名： 使用GPG密钥对POM文件、主JAR包、源码JAR包和Javadoc JAR包进行数字签名。
- 必须包含源码JAR： 部署的每个项目都必须包含一个附带源码的JAR包（artifactId-version-sources.jar）。
- 必须包含Javadoc JAR： 部署的每个项目都必须包含一个附带Javadoc的JAR包（artifactId-version-javadoc.jar）。
- POM文件完整： POM文件中应包含项目描述、许可证信息、开发者信息等。
如果缺少上述任何一项，部署到Sonatype OSSRH的暂存（staging）阶段可能会失败，或者即使成功，下游用户也无法获取完整的工件信息，例如Javadoc。
解决方案：配置Maven插件与GPG签名
解决Javadoc缺失问题的核心在于正确配置Maven的pom.xml，确保在部署时生成并附加源码和Javadoc JAR，并对所有工件进行GPG签名。
1. GPG密钥生成与配置
首先，你需要一个GPG密钥对。这是Maven Central强制要求用于签名所有部署工件的。
立即学习“Java免费学习笔记（深入）”；
生成GPG密钥：
- Windows用户： 可以使用Gpg4win工具。安装后，通过Kleopatra界面生成一个新的密钥对。
- Linux/macOS用户： 可以使用命令行工具gpg --full-generate-key来生成。
在生成密钥时，请确保记住你设置的密码（passphrase），因为Maven在签名时需要它。
配置Maven的settings.xml：
为了让Maven能够访问你的GPG密钥，你需要在用户目录下的.m2/settings.xml文件中添加GPG配置。如果你的GPG密钥有密码，Maven需要知道如何访问它。一种常见做法是在settings.xml中配置gpg.passphrase，但这通常不推荐直接存储明文密码。更安全的做法是使用Maven的密码加密功能，或者在执行部署命令时手动输入。
一个简单的settings.xml配置示例（假设你已配置Sonatype OSSRH的snapshotRepository和repository）：
ossrh true
重要提示： 直接在settings.xml中存储GPG密码存在安全风险。在生产环境中，通常建议通过环境变量、Maven Toolchains或在部署脚本中动态提供密码。
2. Maven pom.xml配置
在项目的pom.xml文件中，你需要添加或修改以下插件配置，确保源码、Javadoc的生成和GPG签名：
maven-source-plugin attach-sources jar-no-fork maven-javadoc-plugin attach-javadocs jar 16 none org.apache.maven.plugins maven-gpg-plugin 1.6 sign-artifacts verify sign org.apache.maven.plugins maven-compiler-plugin 3.8.1 16 16 ossrh https://s01.oss.sonatype.org/content/repositories/snapshots ossrh https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/
配置说明：
- maven-source-plugin: 配置attach-sources执行，目标是jar-no-fork，这会在构建过程中生成并附加一个包含项目源码的JAR包。
- maven-javadoc-plugin: 配置attach-javadocs执行，目标是jar，这会在构建过程中生成并附加一个包含项目Javadoc的JAR包。configuration部分可以指定source版本和doclint选项以避免在某些JDK版本下因Javadoc格式问题导致构建失败。
- maven-gpg-plugin: 这是解决问题的关键。它配置在verify阶段执行sign目标，这意味着在所有工件（主JAR、源码JAR、Javadoc JAR、POM）生成后，它们都会被GPG密钥签名。请确保使用最新的稳定版本。
- maven-compiler-plugin: 尽管不是直接解决Javadoc问题，但确保编译器插件正确配置了source和target版本，与javadoc-plugin的source配置保持一致，有助于避免潜在的编译或Javadoc生成问题。
- distributionManagement: 确保此部分正确配置了Sonatype OSSRH的快照和发布仓库ID和URL。id必须与settings.xml中配置的服务器认证ID匹配。
3. 执行部署
在完成GPG密钥生成和pom.xml配置后，可以通过Maven命令进行部署：
mvn clean deploy
执行此命令后：
- Maven将执行clean，然后install，最后deploy。
- 在install阶段，maven-source-plugin和maven-javadoc-plugin将生成相应的JAR包。
- 在verify阶段（deploy之前），maven-gpg-plugin将提示你输入GPG密钥的密码（如果未在settings.xml中配置），然后对所有生成的工件进行签名。
- 最后，deploy阶段会将所有已签名的工件（主JAR、源码JAR、Javadoc JAR、POM及其对应的.asc签名文件）上传到Sonatype OSSRH的暂存仓库。
4. Sonatype OSSRH暂存仓库操作
部署成功后，你需要登录到Sonatype OSSRH的Web界面（通常是https://s01.oss.sonatype.org/#stagingRepositories）进行后续操作：
- 查找暂存仓库： 在“Staging Repositories”列表中找到你的暂存仓库。
- 关闭暂存仓库（Close）： 检查所有工件是否完整，特别是是否有.asc签名文件、sources.jar和javadoc.jar。如果一切正常，点击“Close”按钮。此步骤会执行一系列验证，包括GPG签名验证。如果GPG签名或工件不完整，关闭操作会失败并显示错误信息。
- 发布仓库（Release）： 关闭成功后，点击“Release”按钮，将你的项目正式发布到Maven Central。
完成这些步骤后，你的库将在短时间内同步到Maven Central，并且当其他开发者导入你的库时，他们的IDE（如IntelliJ IDEA）将能够自动下载并显示完整的Javadoc和源码。
注意事项与总结
- GPG密钥密码： 确保在部署时能够提供GPG密钥的密码。如果使用CI/CD环境，需要考虑如何安全地管理和注入此密码。
- 插件版本： 始终使用Maven插件的最新稳定版本，以获得最佳兼容性和功能。
- 错误排查： 如果部署失败，仔细检查Maven的控制台输出，特别是GPG签名和Sonatype OSSRH暂存仓库的错误信息。这些信息通常会明确指出问题所在。
- 网络连接： 确保在部署过程中有稳定的网络连接，以便上传所有工件。
- Sonatype OSSRH账户： 在开始部署之前，确保已在Sonatype OSSRH创建了账户并成功提交了域名所有权验证。
通过遵循上述详细步骤，并正确配置Maven项目，开发者可以确保其Java库在Maven Central上拥有完整的Javadoc和源码，从而极大地提升库的可用性和用户体验。
