构建与依赖 / 系统课时

生成源码包与文档包

生成源码包与文档包

发布 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 及以上。

xml
<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。

执行打包并检查文件名

在项目根目录执行完整打包:

bash
mvn clean package

预期输出的关键结尾

text
[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,可以直接检查归档目录:

bash
jar tf target/demo-lib-1.0.0-sources.jar

预期输出应包含

text
META-INF/MANIFEST.MF
com/example/Greeter.java

Javadoc 包应包含 HTML 首页和对应类型页面:

bash
jar tf target/demo-lib-1.0.0-javadoc.jar

预期输出应包含

text
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 一起写入本地仓库。先用本地安装验证,比直接对远程仓库执行发布更安全。

bash
mvn clean install

预期输出的关键结尾

text
[INFO] BUILD SUCCESS

默认本地仓库中可在 <PATH>/.m2/repository/com/example/demo-lib/1.0.0/ 找到三个 JAR;如果 settings.xml 配置了自定义 localRepository,实际路径会不同。确认本地安装无误后,后续执行项目既有的 mvn deploy 流程时,这两个附加制品会与主制品一起交给部署阶段处理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成源码包与文档包

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通