maven-shade-plugin 使用方法

本文翻译源于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 资源转换器

上面我们用到了,transformer就是资源转换器。没有重叠的情况下,把多个 artifacts 聚合到uber jar 是非常简单的。当需要逻辑去聚合来自于多个资源的 jar,就是Resource Transformer发挥作用的地方。

以下是资源转换器的列表:

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

你可能感兴趣的:(maven-shade-plugin 使用方法)