构建与依赖 / 系统课时
生成源码包与文档包
生成源码包与文档包
发布 Java 制品时,只有二进制 JAR 往往不够:IDE 跳转源码需要 sources JAR,开发者离线查看 API 需要 javadoc JAR。本课把这两个附加制品绑定到 Maven 生命周期,并用实际文件名和 JAR 内容验证它们确实可随主制品一起安装或发布。
学习目标
- 使用 Maven Source Plugin 生成
-sources.jar,并理解为什么生命周期绑定应选jar-no-fork。 - 使用 Maven Javadoc Plugin 生成
-javadoc.jar,让 API 文档作为附加制品参与安装和发布。 - 通过
package、jar tf和install检查三个制品的文件名、内容和附加状态。
先明确最终应该出现哪些制品
假设项目坐标为 com.example:demo-lib:1.0.0,执行打包后应至少看到下面三个 JAR。sources 和 javadoc 是 classifier,不会替换主 JAR,而是作为同一坐标下的附加制品存在。
| 文件 | 内容 | 典型用途 |
|---|---|---|
demo-lib-1.0.0.jar |
编译后的 .class 与资源 |
程序依赖和运行 |
demo-lib-1.0.0-sources.jar |
src/main/java 中的源码 |
IDE 源码跳转、调试 |
demo-lib-1.0.0-javadoc.jar |
Javadoc 生成的 HTML | API 文档浏览、仓库发布 |
如果你的 artifactId 或 version 不同,文件名前缀会随项目坐标变化,但 classifier 后缀保持 -sources 与 -javadoc。
把源码包与 Javadoc 包绑定到 package
下面是片段示例,追加到已有 pom.xml 的项目级 <build> 中。示例固定使用 Maven Source Plugin 3.4.0 和 Maven Javadoc Plugin 3.12.0;两者这组版本运行要求为 Maven 3.6.3 及以上、JDK 8 及以上。
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.4.0</version>
<executions>
<execution>
<id>attach-sources</id>
<phase>package</phase>
<goals>
<!-- 生命周期绑定优先使用 no-fork 目标,避免再次触发生命周期。 -->
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.12.0</version>
<executions>
<execution>
<id>attach-javadocs</id>
<phase>package</phase>
<goals>
<!-- jar 目标会生成并附加 classifier 为 javadoc 的制品。 -->
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>jar-no-fork 与 javadoc:jar 都适合绑定到构建生命周期。Source Plugin 的 jar-no-fork 不会额外 fork 一次生命周期;Javadoc Plugin 的 jar 会调用 JDK 的标准 Javadoc 工具并把结果打成附加 JAR。
执行打包并检查文件名
在项目根目录执行完整打包:
mvn clean package预期输出的关键结尾
[INFO] BUILD SUCCESS以 demo-lib:1.0.0 为例,target 目录应出现 demo-lib-1.0.0.jar、demo-lib-1.0.0-sources.jar 和 demo-lib-1.0.0-javadoc.jar。若只出现主 JAR,先检查两个 execution 是否位于实际生效的 POM,而不是仅放在未激活的 profile 中。
检查 sources 与 javadoc 包里的真实内容
源码包至少应包含项目 Java 源文件。假设项目有 src/main/java/com/example/Greeter.java,可以直接检查归档目录:
jar tf target/demo-lib-1.0.0-sources.jar预期输出应包含
META-INF/MANIFEST.MF
com/example/Greeter.javaJavadoc 包应包含 HTML 首页和对应类型页面:
jar tf target/demo-lib-1.0.0-javadoc.jar预期输出应包含
META-INF/MANIFEST.MF
index.html
com/example/Greeter.html如果 sources JAR 为空,先确认源码位于 Maven 默认目录 src/main/java,或检查项目是否自定义了 source root。Javadoc 构建失败时不要先把错误吞掉;默认 failOnError 为 true,应先修正无效注释、无法解析的类型或 JDK Javadoc 报错。
验证附加制品会随 install 或 deploy 传播
package 只在 target 生成文件,install 会把主制品以及已附加的 sources、javadoc 一起写入本地仓库。先用本地安装验证,比直接对远程仓库执行发布更安全。
mvn clean install预期输出的关键结尾
[INFO] BUILD SUCCESS默认本地仓库中可在 <PATH>/.m2/repository/com/example/demo-lib/1.0.0/ 找到三个 JAR;如果 settings.xml 配置了自定义 localRepository,实际路径会不同。确认本地安装无误后,后续执行项目既有的 mvn deploy 流程时,这两个附加制品会与主制品一起交给部署阶段处理。