本文翻译源于Apache Maven Project 官网
控制哪些jar包应该包含在项目jar中,哪些不包含
[原文] The POM snippet below shows how to control which project dependencies should be included/excluded in the uber JAR:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
package
shade
classworlds:classworlds
junit:junit
jmock:*
*:xml-apis
org.apache.maven:lib:tests
log4j:log4j:jar:
...
使用设置“白名单”
[原文] Of course,
can be used as well to specify a white list of artifacts. Artifacts are denoted by a composite idenitifer of the form groupId:artifactId[[:type]:classifier]. Since plugin version 1.3, the wildcard characters '*' and '?' can be used to do glob-like pattern matching.
For fine-grained control of which classes from the selected dependencies are included, artifact filters can be used:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
package
shade
junit:junit
junit/framework/**
org/junit/**
org/junit/experimental/**
org/junit/runners/**
*:*
META-INF/*.SF
META-INF/*.DSA
META-INF/*.RSA
...
最小包
除了使用filters,还可以配置插件自动的去掉项目没有用到的classes,使用关键字
[原文] Besides user-specified filters, the plugin can also be configured to automatically remove all classes of dependencies that are not used by the project, thereby minimizing the resulting uber JAR
maven-shade-plugin插件可以配置自动精简那些项目没有用到的依赖的artifact,或者显式的配置精简项目用到的依赖的artifact下面没有用到的classes。
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
package
shade
true
log4j:log4j
**
commons-logging:commons-logging
**
...
配置后执行mvn package
打包,日志会出现以下提示:
...
[INFO] Minimizing jar com.hello:TCP-client:jar:1.0-SNAPSHOT
[INFO] Minimized 1266 -> 755 (59%)
...
重定位classes
Java 工程经常会遇到第三方 Jar 包冲突,使用 maven shade plugin 解决 jar 或类的多版本冲突。 maven-shade-plugin 在打包时,可以将项目中依赖的 jar 包中的一些类文件打包到项目构建生成的 jar 包中,在打包的时候把类重命名。下面的配置将 org.codehaus.plexus.util jar 包重命名为 org.shaded.plexus.util。
原文
If the uber JAR is reused as a dependency of some other project, directly including classes from the artifact's dependencies in the uber JAR can cause class loading conflicts due to duplicate classes on the class path. To address this issue, one can relocate the classes which get included in the shaded artifact in order to create a private copy of their bytecode:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
package
shade
org.codehaus.plexus.util
org.shaded.plexus.util
org.codehaus.plexus.util.xml.Xpp3Dom
org.codehaus.plexus.util.xml.pull.*
...
我们同样可以使用
...
org.codehaus.plexus.util
org.shaded.plexus.util
org.codehaud.plexus.util.io.*
...
为uber jar增加后缀
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
package
shade
true
jackofall
...
打包可执行的 uber jar
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
package
shade
org.sonatype.haven.HavenCli
...
shade Resource Transformers 资源转换器
上面我们用到了
以下是资源转换器的列表:
Transformers in org.apache.maven.plugins.shade.resource
Transformer | 作用 |
---|---|
ApacheLicenseResourceTransformer | Prevents license duplication |
ApacheNoticeResourceTransformer | Prepares merged NOTICE |
AppendingTransformer | Adds content to a resource |
ComponentsXmlResourceTransformer | Aggregates Plexus components.xml |
DontIncludeResourceTransformer | Prevents inclusion of matching resources |
GroovyResourceTransformer | Merges Apache Groovy extends modules |
IncludeResourceTransformer | Adds files from the project |
ManifestResourceTransformer | Sets entries in the MANIFEST |
PluginXmlResourceTransformer | Aggregates Mavens plugin.xml |
ResourceBundleAppendingTransformer | Merges ResourceBundles |
ServicesResourceTransformer | Relocated class names in META-INF/services resources and merges them. |
XmlAppendingTransformer | Adds XML content to an XML resource |
下面一一介绍作用
ManifestResourceTransformer
The ManifestResourceTransformer allows existing entries in the MANIFEST to be replaced and new entries added.
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
${app.main.class}
${maven.compile.source}
${maven.compile.target}
...
AppendingTransformer、XmlAppendingTransformer和ResourceBundleAppendingTransformer
使用AppendingTransformer、XmlAppendingTransformer和ResourceBundleAppendingTransformer合并特定文件的内容
有些jar包含具有相同文件名的额外资源(例如*.properties)。为了避免覆盖,您可以选择通过将它们的内容附加到一个文件中来合并它们。一个很好的例子是同时聚合spring-context 和 plexus-spring jars.。它们都有META-INF/spring.handlers 文件,Spring使用该文件处理XML模式名称空间。您可以使用如下所示的AppendingTransformer合并所有具有该特定名称的文件的内容:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
META-INF/spring.handlers
META-INF/spring.schemas
...
对于xml文件,你可以使用 XmlAppendingTransformer
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
META-INF/magic.xml
...
由于插件版本1.3.1,XmlAppendingTransformer默认情况下不加载dtd,因此避免了网络访问。这种模式的潜在缺点是无法解析外部实体,从而导致转换失败,例如,当使用某些JRE 1.4中使用的Crimson XML解析器时。如果转换后的资源使用外部实体,则可以重新启用DTD分辨率,或者将对xerces:xercesImpl:2.9.1的插件依赖项添加到POM中。
对于resourcebundle属性文件,您可以使用ResourceBundleAppendingTransformer,它也会考虑所有可用的地区:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
path/to/Messages
...
DontIncludeResourceTransformer
排除掉指定后缀的资源
如下可以排除掉以.txt
结尾的资源
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
.txt
...
3.0以后的版本,也可以排除一个列表
.txt
READ.me
IncludeResourceTransformer
和以上转换器相反,可以添加一个资源到包中的项目目录
以下例子,指定了README.txt
添加到 META-INF 目录下
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
META-INF/README
README.txt
...
ComponentsXmlResourceTransformer
针对Plexus IoC容器的组件的jar包含一个META-INF/plexus /components.xml,该xml文件声明组件及其需求。如果uber JAR聚合了多个 Plexus 组件,则需要使用ComponentsXmlResourceTransformer合并XML描述符:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
...
PluginXmlResourceTransformer
使用插件工具3.0引入了注释。现在对类的引用不再是字符串形式的类名,而是实际的类引用。当您想要重新定位类时,您必须手工维护META-INF/maven/plugin.xml,但是现在这可以通过PluginXmlResourceTransformer来完成。
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
...
ServicesResourceTransformer
提供某些接口实现的AR文件通常附带一个META-INF/services/目录,该目录将接口映射到它们的实现类,以便服务定位器进行查找。要重新定位这些实现类的类名,并将同一个接口的多个实现合并到一个服务条目中,可以使用ServicesResourceTransformer:
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
...
ApacheLicenseResourceTransformer
防止License重复。
一些开源的产品(包括 apache 基金会)包含一个他们的License在 META-INF 目录下。
他们一般命名为LICENSE
或者LICENSE.txt
。当合并这个依赖的时候,添加这些资源会照成混乱。ApacheLicenseResourceTransformer 保证复制这些 License 的时候不回合并。
如下的代码可以防止 License 被合并到一个公共集合依赖项中。
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
...
ApacheNoticeResourceTransformer
一些许可证(包括Apache许可证,版本2)要求通知由下游分销商保存。ApacheNoticeResourceTransformer自动组装适当的通知。
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
false
...
GroovyResourceTransformer
Apache Groovy语言提供了位于META-INF/services/org.codehaus.groovy.runtime.ExtensionModule的扩展模块,这些模块使用属性文件格式。GroovyResourceTransformer自动装配Groovy扩展模块的通知。
...
org.apache.maven.plugins
maven-shade-plugin
3.2.1
shade
the-aggregated-module
1.0.0
...
定义自己的shade实现
------ the end -----