JMOD格式详解与jmod工具使用指南

JMOD格式概述

Java平台提供了一种名为JMOD的模块打包格式，作为对传统JAR格式的功能扩展。与JAR文件相比，JMOD格式具有更强大的内容包容性，能够打包包括以下类型的资源：

• 编译后的Java类文件（与JAR相同）
• 原生代码库（native libraries）
• 可执行的原生命令文件
• 用户可编辑的配置文件
• 头文件（header files）
• 法律声明文档
• 手册页（man pages）

技术特性

JMOD文件采用ZIP格式作为容器格式，这意味着开发者可以使用标准ZIP工具（如unzip命令）直接查看其内容结构。典型的JMOD文件内部采用目录分类存储机制：

classes/        # 存放编译后的类文件
conf/           # 配置文件
native/         # 原生代码库
bin/            # 可执行命令

使用限制

需要特别注意的运行时限制：

1. 编译/链接阶段专用：JDK模块（如java.base.jmod）以JMOD格式提供，仅用于javac编译和jlink链接阶段
2. 运行时禁用：若尝试通过--module-path加载JMOD文件运行，JVM会抛出明确错误：

   Error occurred during initialization of VM
   java.lang.module.ResolutionException: 
       JMOD files not supported: jmods/jdojo.javafx.jmod
   

文件定位

JDK内置的JMOD文件存储在安装目录的特定位置：

JDK_HOME/
  └── jmods/
       ├── java.base.jmod
       ├── java.compiler.jmod
       └── ...（其他模块）

开发者也可以创建自定义JMOD文件，其文件扩展名统一为.jmod。例如平台基础模块对应的文件名为java.base.jmod。

典型应用场景

1. 模块开发阶段：打包包含混合资源（如Java类+原生库）的模块
2. 定制运行时镜像：通过jlink工具将JMOD文件链接为可执行镜像
3. 跨平台交付：统一管理不同平台的本地依赖项

技术说明：由于JMOD包含的原生代码需要在运行时动态提取和链接，这个过程的复杂性导致了运行时支持的缺失，这也是设计上故意为之的限制。

jmod工具基础用法

JDK提供了专门的jmod工具来处理JMOD格式文件，该工具位于JDK安装目录的bin子目录下（JDK_HOME/bin）。作为模块化系统的重要组成部分，jmod支持五个核心子命令：create（创建）、extract（提取）、list（列表）、describe（描述）和hash（哈希记录）。

创建JMOD文件

使用create子命令时，必须通过--class-path参数指定类文件来源路径，该路径可以是包含编译后类文件的目录，也可以是已有的JAR文件。基本语法结构为：

jmod create --class-path <路径> <输出.jmod文件>

通过--module-version可设置模块版本信息，该版本号会写入模块描述文件（module-info.class）。以下是两个典型示例：

1. 基于现有JAR文件创建：

jmod create \
    --class-path dist/jdojo.javafx.jar \
    jmods/jdojo.javafx.jmod

2. 基于编译输出目录创建（带版本号）：

jmod create --module-version 1.0 \
    --class-path build/modules/jdojo.javafx \
    jmods/jdojo.javafx.jmod

提取文件内容

extract子命令可将JMOD文件内容解压到指定目录，使用--dir参数指定目标位置。若不指定该参数，则默认解压到当前工作目录：

jmod extract --dir extracted_contents \
    jmods/jdojo.javafx.jmod

查看文件结构

list子命令能显示JMOD文件内部的层次化目录结构。JMOD采用分类存储机制，不同类型资源存放在特定目录下：

jmod list jmods/jdojo.javafx.jmod

典型输出示例：

classes/module-info.class
classes/com/jdojo/javafx/BindingTest.class
bin/java.exe
native/amd64/jvm.cfg
conf/net.properties

对于平台模块（如java.base），其内容更为丰富：

jmod list $JDK_HOME/jmods/java.base.jmod

模块描述信息

describe子命令可显示模块的元数据信息，包括模块名称、版本、导出包、依赖关系等：

jmod describe jmods/jdojo.javafx.jmod

输出示例：

jdojo.javafx@1.0
exports com.jdojo.javafx
requires java.base mandated
requires javafx.controls
requires javafx.fxml
contains resources.fxml

哈希记录功能

hash子命令用于建立模块间的安全验证机制，通过记录依赖模块的哈希值确保模块完整性。典型工作流程如下：

1. 准备待哈希记录的模块：

jmod create --module-version 1.0 \
    --class-path build/modules/jdojo.prime \
    jmods/jdojo.prime.jmod

2. 执行哈希记录（支持正则表达式匹配模块名）：

jmod hash \
    --module-path jmods \
    --hash-modules "jdojo.prime.?" \
    jmods/jdojo.prime.jmod

3. 验证记录结果：

jmod describe jmods/jdojo.prime.jmod

输出中将包含类似内容：

hashes jdojo.prime.client SHA-256 5950...21b
hashes jdojo.prime.faster SHA-256 5538...6a

开发提示：可使用--dry-run选项模拟哈希计算过程而不实际修改文件，这在调试阶段非常有用。jmod工具的所有命令都支持--help参数获取实时帮助信息。

高级功能与配置选项

模块描述分析

describe子命令可深入展示模块的完整元数据信息，包括以下关键元素：

1. 模块标识：名称+版本号（如jdojo.javafx@1.0）
2. 导出关系：通过exports列出所有公开包
3. 依赖声明：
   • requires显示直接依赖
   • mandated标记强制依赖（如java.base）
   • transitive表示传递性依赖
4. 服务绑定：provides...with...显示服务提供关系
5. 资源包含：contains列出未导出的资源路径

平台模块示例（java.sql）：

jmod describe $JDK_HOME/jmods/java.sql.jmod

输出包含平台标识：

java.sql@9.0.1
platform windows-amd64  # 目标平台信息

哈希绑定机制

hash子命令实现模块间的密码学绑定，主要应用于：

1. 依赖验证：确保运行时加载的模块与编译时一致
2. 供应链安全：防止模块被篡改
3. 版本固化：锁定特定版本的依赖模块

实现步骤：

# 1. 准备待哈希模块集合
jmod create --module-version 1.0 \
    --class-path build/modules/jdojo.prime \
    jmods/jdojo.prime.jmod

# 2. 执行哈希记录（使用正则匹配模块名）
jmod hash \
    --module-path jmods \
    --hash-modules "jdojo.prime.?" \
    jmods/jdojo.prime.jmod

哈希记录效果示例：

hashes jdojo.prime.client SHA-256 5950...21b
hashes jdojo.prime.faster SHA-256 5538...6a

高级参数详解

模块路径指定

--module-path支持三种路径格式：

--module-path dir1:dir2         # Unix分隔符
--module-path dir1;dir2         # Windows分隔符
--module-path @modulepathfile   # 从文件读取

正则表达式匹配

--hash-modules支持标准正则语法：

--hash-modules "jdojo.*"        # 匹配所有jdojo前缀模块
--hash-modules ".*test"         # 匹配所有test后缀模块

预执行验证

--dry-run选项可在不修改文件的情况下预览哈希计算结果：

jmod hash --dry-run \
    --module-path jmods \
    --hash-modules "jdojo.prime.?" \
    jmods/jdojo.prime.jmod

输出结果包含Dry run:标记，且不会写入实际文件。

典型错误处理

1. 哈希不匹配：

   java.lang.module.InvalidModuleDescriptorException: 
       Hash mismatch for module jdojo.prime.client
   

   解决方案：重新生成依赖模块或检查模块路径

2. 正则表达式错误：

   PatternSyntaxException: Unclosed character class
   

   解决方案：检查--hash-modules参数的正则语法

3. 模块路径缺失：

   jmod: Module jdojo.prime.faster not found
   

   解决方案：确保--module-path包含所有依赖模块路径

集成应用场景

1. 持续集成流程：

   # 在构建服务器上验证模块哈希
   jmod hash --dry-run \
       --module-path $BUILD_ARTIFACTS \
       --hash-modules "com.company.*" \
       target/modules/main.jmod
   

2. 多模块项目管理：

   # 记录跨模块哈希链
   jmod create --module-version 1.0 \
       --module-path libs \
       --hash-modules ".*utils.*" \
       --class-path out/production \
       dist/main.jmod
   

3. 安全审计准备：

   # 生成完整的哈希报告
   jmod describe security.jmod | grep hashes > hashes-audit.log
   

实际应用场景

与jlink工具集成

JMOD格式最典型的应用场景是与jlink工具配合创建自定义运行时镜像。通过将多个JMOD模块链接打包，可以生成包含最小依赖的可执行环境：

jlink --module-path $JDK_HOME/jmods:app_jmods \
      --add-modules jdojo.prime,jdojo.prime.client \
      --output custom_runtime

该命令会：

1. 合并java.base.jmod等基础模块
2. 包含应用模块jdojo.prime.jmod
3. 自动解析传递性依赖
4. 生成可独立部署的运行时镜像

多模块哈希绑定

在模块化系统中，哈希绑定可确保模块依赖关系的可靠性。以jdojo.prime系列模块为例：

1. 模块结构：

   jdojo.prime (核心接口)
   ├─ jdojo.prime.faster (快速实现)
   ├─ jdojo.prime.probable (概率算法实现)
   └─ jdojo.prime.client (客户端)
   

2. 哈希记录命令：

   jmod hash --module-path jmods \
             --hash-modules "jdojo.prime.?" \
             jmods/jdojo.prime.jmod
   

3. 验证机制：

   • 运行时自动校验依赖模块的SHA-256哈希值
   • 任何模块篡改都会导致InvalidModuleDescriptorException

平台模块分析

JDK内置的JMOD文件（如java.base.jmod）展示了高级用法：

1. 内容结构：

   jmod list $JDK_HOME/jmods/java.base.jmod
   

   输出示例：

   classes/java/lang/Object.class
   native/libnio.so
   conf/security/policy
   bin/java
   

2. 跨平台支持：

   jmod describe java.base.jmod | grep platform
   

   显示目标平台信息：

   platform windows-amd64
   

原生代码集成

通过--libs和--cmds选项实现Java与原生代码的混合打包：

jmod create --class-path build/classes \
            --libs native/lib/ \
            --cmds bin/ \
            --header-files include/ \
            app.jmod

目录结构建议：

native/
  ├─ linux/
  │   └─ libnative.so
  └─ win/
      └─ native.dll
bin/
  ├─ app.sh (Unix)
  └─ app.cmd (Windows)

配置管理实践

使用--config选项管理可编辑配置：

1. 创建时包含配置：

   jmod create --config conf/ \
               --class-path target/classes \
               config.jmod
   

2. 运行时访问：

   ModuleLayer.boot().findModule("app")
       .flatMap(m -> m.getResourceAsStream("conf/app.properties"));
   

3. 配置更新流程：

   jmod extract --dir tmp config.jmod
   vi tmp/conf/app.properties  # 编辑配置
   jmod create --config tmp/conf \
               --class-path target/classes \
               new_config.jmod
   

版本控制策略

通过组合使用模块版本与哈希绑定实现严格版本控制：

1. 创建版本化模块：

   jmod create --module-version 2.1 \
               --class-path build-v2.1 \
               app-2.1.jmod
   

2. 依赖版本锁定：

   jmod hash --module-path deps \
             --hash-modules "lib.*@2.0.*" \
             app-2.1.jmod
   

3. 版本冲突检测：

   java.lang.module.ResolutionException: 
       Version mismatch for module lib.utils
       Required: 2.0.1
       Found: 2.1.0
   

注意事项与限制

运行时支持限制

JMOD文件在设计上明确不支持运行时加载，若尝试通过--module-path参数在运行时使用JMOD文件，JVM将抛出明确错误：

Error occurred during initialization of VM
java.lang.module.ResolutionException: 
    JMOD files not supported: jmods/jdojo.javafx.jmod

此限制主要源于两个技术因素：

1. 原生代码的动态提取和链接在运行时存在安全隐患
2. 配置文件等资源的实时解压会增加启动开销

特殊选项解析

默认解析排除

--do-not-resolve-by-default选项用于控制模块可见性：

jmod create --do-not-resolve-by-default \
    --class-path build/modules/special \
    special.jmod

效果：

• 该模块不会出现在默认根模块集合中
• 必须显式通过--add-modules指定才能使用

目标平台规范

--target-platform需严格遵循-格式：

jmod create --target-platform linux-arm64 \
    --class-path build/modules/native \
    native.jmod

常见平台标识符：

• windows-amd64
• macos-aarch64
• linux-ppc64le

文件排除策略

--exclude支持三种模式匹配语法：

jmod create --exclude "*.tmp,test/**" \       # 简写glob模式
            --exclude "glob:*.bak" \          # 标准glob语法
            --exclude "regex:.*\\.log" \      # 正则表达式
            --class-path src \
            app.jmod

排除规则优先级：

1. regex:模式优先于glob:
2. 多个规则按声明顺序应用
3. 默认采用简化的glob语法

与模块化JAR对比

典型问题排查

1. 模块哈希冲突：

   # 验证哈希一致性
   jmod describe app.jmod | grep -A 3 hashes
   

2. 平台不匹配警告：

   WARNING: Module target platform (linux-amd64) 
            does not match current system
   

3. 排除模式失效：

   # 测试模式匹配
   jmod create --dry-run --exclude "*.tmp" ...
   

建议开发流程：

1. 开发阶段使用模块化JAR
2. 发布时转换为JMOD格式
3. 通过jlink生成定制运行时镜像
4. 使用哈希绑定确保交付一致性

技术总结

JMOD格式作为Java模块化系统的重要补充，在以下几个方面展现出独特的技术价值：

原生资源整合能力

JMOD突破了传统JAR格式的限制，通过标准化目录结构（classes/native/conf等）实现了Java代码与原生资源的统一打包。这种设计特别适合需要混合部署的场景：

• 跨平台原生库（.dll/.so文件）可通过--libs参数集成
• 命令行工具可经由--cmds选项打包
• 头文件和配置文件分别存储在特定目录

# 典型混合打包示例
jmod create --class-path build \
            --libs native/ \
            --cmds scripts/ \
            --header-files include/ \
            app.jmod

全生命周期管理

jmod工具提供完整的模块管理能力链：

1. 创建阶段：支持版本控制（--module-version）、主类指定（--main-class）
2. 验证阶段：哈希绑定（hash子命令）确保模块完整性
3. 部署阶段：与jlink深度整合构建定制运行时
4. 维护阶段：内容查看（list）、元数据分析（describe）

安全增强机制

哈希绑定机制通过密码学手段强化了模块依赖关系：

• 采用SHA-256算法记录依赖模块指纹
• 支持正则表达式批量匹配模块（--hash-modules ".*utils"）
• 运行时自动验证，防止依赖篡改

hashes jdojo.security SHA-256 8932...ae45
hashes jdojo.crypto SHA-256 7f01...bc12

平台适配特性

通过--target-platform参数明确记录目标环境信息：

• 格式规范化为-（如linux-arm64）
• 在module-info.class中生成ModuleTarget属性
• jlink工具可据此筛选兼容模块

使用边界限制

需特别注意的设计约束：

1. 编译时/运行时差异：
   • 编译时：可出现在--module-path
   • 运行时：触发ResolutionException
2. 工具链依赖：
   • 必须配合javac/jlink使用
   • 不支持传统java命令直接加载
3. 平台一致性：
   • 原生代码需要匹配目标平台
   • 配置文件的路径敏感性

典型应用模式

1. SDK开发：打包包含JNI调用的开发套件
2. 嵌入式部署：通过jlink生成最小化运行时
3. 安全敏感场景：利用哈希绑定确保供应链安全
4. 跨平台交付：单包包含多架构原生实现

建议开发者在以下场景优先考虑JMOD：

• 需要统一管理Java与非Java资源
• 目标环境存在严格的依赖验证需求
• 交付物需要包含完整的工具链支持
• 构建跨平台解决方案时

对于纯Java模块且无需特殊安全要求的场景，模块化JAR仍是更轻量的选择。技术选型时应根据实际需求权衡功能完备性与部署复杂性。