1 / 4概念
Toolchain: Packaging and Release
打包不是把 class 塞进压缩包,而是决定运行时从哪里加载什么。产物形态一旦选定,启动参数、镜像分层、签名与回滚方式都会被它绑住;判断标准是能否说清一个 jar 里的每个条目由谁写入、java -jar 之后又由谁读取。
1 概念
1.1 一句话定义
打包把 classpath、启动入口与运行环境固定成一份可分发的文件;发布把这份文件按坐标写入仓库,让下游按版本而不是按路径依赖。两者合起来,才让同一份二进制可以被重复部署与审计。
1.2 它解决什么问题
- 入口明确:启动类与 classpath 写进产物,而不是写在运维脚本里。
- 环境自带:
jlink与 native image 把运行时一起交付,减少对目标机器的假设。 - 可校验:校验和、签名与 SBOM 让产物来源可验证。
- 可回滚:版本一旦发布就不可变,回滚只是换回旧版本。
- 可审计:每个版本对应一次可追溯的构建。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 依赖解析、BOM 与 scope | Build and Dependencies |
| 测试分层与 surefire / failsafe | Testing |
| 类加载器层次与双亲委派 | Class Loading |
| 流水线编排、制品缓存与并行 | CI/CD |
| 私有仓库、代理与凭据 | Private Registry |
| 自动配置与启动流程 | Spring Boot |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| plain jar | 只有自身 class 的普通 jar | 不含依赖 |
| fat jar | 把依赖一并打包的 jar | 与可执行 jar 不是同义词 |
| shaded jar | 依赖被重定位后的 fat jar | 重定位会改包名 |
| executable jar | 带启动器的 jar,可直接 java -jar | 依赖可以外置 |
| war | 交给 Servlet 容器的归档 | 入口由容器决定 |
| JPMS | 模块系统,module-info.java 描述 | 与 classpath 并存 |
jlink | 裁剪 JDK 并生成运行时镜像 | 不打包应用 |
jpackage | 生成自包含安装包 | 依赖 jlink 产物 |
| native image | 编译成原生可执行文件 | 不再有 JVM |
| SBOM | 软件物料清单 | 不是校验和 |
| checksum | 产物摘要,用于比对 | 不证明来源 |
| snapshot promotion | 把快照提升为正式版 | 不是改文件名 |
2 机制
2.1 心智模型
一份可运行产物由三部分组成:classpath 清单、一个入口、一份元数据。jar 只是容器,真正的差别在谁写清单、谁读清单。普通 jar 把清单交给启动命令,可执行 jar 把清单和读取它的启动器一起放进去。
2.2 机制拆解
- 普通 jar:
maven-jar-plugin只写自身 class 与资源,依赖留给使用方。 - fat jar:
maven-shade-plugin把依赖展开进同一个包,冲突类按规则取舍;assembly只是把 jar 平铺进去。 - 重打包:
spring-boot-maven-plugin的repackage在原 jar 上重写,写入启动器与分层清单,原 jar 被替换。 - war:
maven-war-plugin把依赖放进WEB-INF/lib/,入口由 Servlet 容器提供,失败信息常藏在容器日志里。 - 模块化:有
module-info.java才能jlink;jdeps --print-module-deps求出所需模块,jlink --add-modules生成裁剪后的运行时。 - 安装包:
jpackage把运行时与应用一起封装成deb、msi或dmg,安装后由系统管理升级。 - 原生编译:native image 在构建期固化 classpath 与可达代码,反射、资源与动态代理应在配置里登记,否则运行期才报错。
- 可复现:固定
outputTimestamp、禁用文件时间戳、固定条目顺序与文件权限,产物才能逐个字节比对。 - 签名与 SBOM:
jarsigner或 GPG 签名,CycloneDX 生成 SBOM,二者都随产物一起发布。 - 仓库写入:远程仓库按
groupId目录、artifactId与version定位;install只写本地,deploy才写远程,快照按时间戳生成多个文件。
2.3 完整枚举
Spring Boot 可执行 jar 的完整内部结构:
| 条目 | 作用 |
|---|---|
META-INF/MANIFEST.MF | 写入 Main-Class、Start-Class 与各项索引路径 |
org/springframework/boot/loader/ | 启动器与自定义类加载器 |
BOOT-INF/classes/ | 应用自身的 class 与资源 |
BOOT-INF/lib/ | 依赖 jar,按原文件名存放 |
BOOT-INF/classpath.idx | 启动器构建 classpath 时读取的顺序 |
BOOT-INF/layers.idx | 分层清单,供镜像按层缓存 |
META-INF/build-info.properties | 由 build-info goal 生成的构建信息 |
五种分发形态的入口与依赖归属:
| 形态 | 入口 | 依赖位置 | 适用 |
|---|---|---|---|
| 普通 jar | 启动命令指定 | 外部 classpath | 库、被其他工程引用 |
| 可执行 jar | 内置启动器 | BOOT-INF/lib/ | 服务端单文件分发 |
| war | Servlet 容器 | WEB-INF/lib/ | 传统应用服务器 |
jlink 镜像 | bin/java | 镜像内 lib/ | 自带运行时、受控环境 |
| native image | 原生可执行文件 | 编译进二进制 | 极速启动、资源受限 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 可执行 jar 体积 | 数十 MB 到上百 MB | 随依赖数量线性增长 |
| JVM 启动到可用 | 一到五秒 | 受类加载与框架初始化影响 |
| native image 启动 | 数十毫秒 | 代价是构建时间与内存 |
jlink 运行时镜像 | 四十到七十 MB | 取决于纳入的模块 |
| native image 构建 | 数分钟 | 需要额外内存与工具链 |
3 实践
3.1 最小示例
用 spring-boot-maven-plugin 重打包,并开启分层与排除:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>3.3.5</version>
<configuration>
<mainClass>com.example.order.Application</mainClass>
<excludes>
<exclude>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
</exclude>
</excludes>
<layers>
<enabled>true</enabled>
</layers>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
追踪 ./mvnw verify:package 阶段先由 jar:jar 写出普通 jar,repackage 紧接着重写它,清单里写入 Main-Class 与 Start-Class,依赖移入 BOOT-INF/lib/,layers.idx 记录分层。执行 java -jar order-service.jar 时,启动器先读 classpath.idx 建类加载器,再调用 Start-Class 的 main;启动器中不存在“扫描 classpath 找主类”的步骤,所以入口写错会立即失败。Gradle 侧对应 bootJar 任务,jar 任务通常关闭,避免两个产物混淆。
3.2 常用操作与参数
| 操作 | 命令 | 说明 |
|---|---|---|
| 跳过测试打包 | ./mvnw -DskipTests package | 只在测试已在别处跑过时使用 |
| 运行产物 | java -jar target/order-service.jar | 验证入口与 classpath |
| Gradle 打包 | ./gradlew bootJar | 产物在 build/libs/ |
| 求模块依赖 | jdeps --print-module-deps app.jar | 得到 jlink 的模块列表 |
| 生成运行时 | jlink --add-modules java.base,java.sql --output runtime | 只带必要模块 |
| 生成安装包 | jpackage --type deb --input lib --main-jar app.jar | 自包含安装 |
| 构建原生镜像 | native-image -jar app.jar | 需 GraalVM 与反射配置 |
| 校验签名 | jarsigner -verify -verbose app.jar | 确认签名完整 |
| 计算摘要 | sha256sum app.jar | 与发布页记录的摘要比对 |
| 发布到远程仓库 | ./mvnw deploy | 写入远程仓库 |
3.3 标准流程
- 先定形态:库发普通 jar,服务发可执行 jar,交付环境受控时再考虑镜像或 native。
- 固定入口与依赖归属,用
java -jar或容器启动验证一次。 - 固定插件版本与
outputTimestamp,打开可复现的文件顺序。 - 生成校验和与 SBOM,需要时对产物签名。
- 用
verify通过后再deploy,正式版与快照走不同仓库或不同路径。 - 发布前在隔离环境按发布清单装一次,确认能启动再对外。
3.4 与相邻技术的组合
- Spring Boot:
repackage负责可执行 jar,build-info写入构建信息,分层与镜像缓存配合。 - CI/CD:缓存键带上 JDK 版本、构建脚本与依赖清单的哈希,产物按 commit 归档。
- Private Registry:发布与拉取都走同一仓库,凭据从环境注入,不写进
settings.xml的明文。 - Class Loading:启动器自建类加载器,依赖顺序由
classpath.idx决定,冲突在这里暴露。 - Testing:
verify阶段的集成测试决定能否打包,测试不通过就不该产出可发布产物。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 交付形态 | jar / war / 镜像 / 原生 | 决定部署与升级方式 |
| 启动时间 | 秒级 / 毫秒级 | native 有明显优势 |
| 运行时控制 | 自带 / 依赖宿主 | 自带更容易复现环境 |
| 镜像体积 | 百 MB 级 / 十 MB 级 | 影响拉取与扩容速度 |
| 反射使用 | 少量 / 大量 | 决定 native 改造成本 |
| 排障手段 | 线程栈与堆分析 / 受限 | native 缺少部分运行时工具 |
3.6 决策规则
- 内部服务优先可执行 jar 加容器镜像,构建与排障成本最低。
- 需要固定运行时或离线交付时,用
jlink或jpackage。 - 只有在启动时间或内存是硬指标时才上 native image,并预留反射改造预算。
- 发布版本只增不改;发现缺陷时发新版本,不覆盖旧文件。
- 快照只进快照仓库,正式发布重新构建并走同一套校验。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 可执行 jar | 构建简单、排障成熟 | 需要目标机有 JVM | 绝大多数服务 |
| war 加容器 | 复用容器能力 | 入口与日志受容器控制 | 既有应用服务器 |
jlink 镜像 | 运行时可控、体积适中 | 模块化改造与跨平台构建 | 离线或受控环境 |
| native image | 启动快、内存低 | 构建慢、反射需登记 | 函数计算、CLI |
3.8 何时不该用
- 只是内部库,发普通 jar 即可,不要打成可执行包。
- 依赖大量动态代理或运行期生成字节码时,不要强行上 native image。
- 单机部署的小服务,不必为镜像分层引入完整流水线。
- 还没有回滚路径时,不要发布正式版本。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
启动时报 ClassNotFoundException | fat jar 少打了依赖,或 exclude 写错 | 解开 jar 查 BOOT-INF/lib/,核对排除规则 |
java -jar 找不到主类 | 清单里的入口写错,或启动脚本自拼 classpath | 修正 Start-Class,让启动器读索引 |
| native image 运行期反射失败 | 反射目标未登记 | 补 reflect-config.json 或注册绑定 |
| 同一版本摘要不一致 | 时间戳、条目顺序、并行打包 | 固定 outputTimestamp 与文件顺序 |
| 发布后无法回滚 | 覆盖了旧版本文件,或只发快照 | 版本不可变,回滚即切换版本 |
| 签名校验失败 | 产物在签名后被改动 | 重新构建并重签,不手工修补 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
用 SNAPSHOT 做对外发布 | 内容漂移,无法复现 | 发布正式版 |
| 手工往 jar 里补文件 | 摘要与签名失真 | 重新构建 |
| 启动脚本自拼 classpath | 与产物清单不一致 | 让启动器读清单 |
| 只发 jar 不发校验和 | 无法发现传输损坏 | 附摘要与 SBOM |
用 install 当作发布 | 只影响本机 | 用 deploy 写远程仓库 |
4.3 可观测信号
产物 SHA-256、jar 条目数、启动耗时、镜像层命中率、native image 构建时长与内存峰值、签名校验结果、仓库中的版本列表。排障顺序为:产物结构、入口与 classpath、运行环境。
4.4 安全 / 性能 / 一致性边界
- 供应链边界:签名、SBOM 与仓库凭据共同构成发布边界,缺任一项都无法证明产物来源。
- 复现边界:时间戳、文件顺序与插件版本全部固定,逐字节比对才有意义。
- 性能边界:native image 用构建时间与内存换启动时间,反射越多的工程代价越高。
- 一致性边界:发布产物应与通过测试的那份产物一致,重新构建就是另一份产物。