2014/09/22更新,加入了jacoco
2015/07/20更新,jarjar-maven-plugin换成maven-shade-plugin
mybatis的文档挺不错的,最近有兴趣看了一下mybatis的工程,发现它的文档(站点)是通过maven的插件自动生成的。所以我们借巨人的肩膀,不妨分析一下他是如何做到自动生成站点的。
首先要注意的是,要在本地编译mybatis的话,需要2个工程
parent
mybatis-3
本文写作时,最新版本为3.3.0-SNAPSHOT。本文就针对这个版本来分析一下如何生成站点。
1. 运行效果
先不说理论,最好的学习方法就是先运行,然后看效果。
2个工程分别git clone下来以后执行mvn clean install即可。然后会发现target目录下有个site目录,里面就是生成的站点了。浏览一下,有自己写的文档,还有各种报表。
2.
maven-site-plugin
这个便是做到生成站点的maven插件了。要注意的是插件的版本是定义在parent中的。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.4</version> <!-- 3.3 works wrong with fluido skin 1.3.x -->
<configuration>
<locales>en,es,ja,fr,zh_CN,ko</locales>
</configuration>
<executions>
<execution>
<id>attach-descriptor</id>
<goals>
<goal>attach-descriptor</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.github.stephenc.wagon</groupId>
<artifactId>wagon-gitsite</artifactId>
<version>0.4.1</version>
</dependency>
<!-- Fluido here only for version update checks on site page -->
<dependency>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
<version>1.3.1</version>
</dependency>
</dependencies>
</plugin>
2.1 支持多国语言,执行mvn site后target/site目录下多种语言的站点都生成了。
2.2 采用了maven-site-plugin3.4,说3.3对fluido皮肤有bug
2.3 attach-descriptor 将站点描述符(site.xml)加入到要安装和部署的文件列表中。
2.3.1
站点描述符
是用来自定义站点index页面的方法,需要写src/site/site.xml
2.4
wagon-gitsite
wagon的一个实现,用来将文档部署到github上
2.4.1
wagon
wagon是maven用来处理artifact和repository的抽象传输层,支持以下方式的代码传输:
- File
- HTTP -->http client
- HTTP lightweight
- FTP -->commons net
- SSH/SCP -->jsch
- WebDAV -->jackrabbit
- SCM -->maven scm api
2.5
皮肤
该站点列举了目前可用的5种皮肤
2.5.1
maven-fluido-skin
采用了Twitter Bootstrap的css作为皮肤,使得站点看上去非常的新潮漂亮。
有一点令我不解的是文档上写了要在site.xml中定义skin元素才能运用皮肤,但是mybatis没有这样做,只是如前面的xml里定义了dependency,就可以用这个皮肤了。
2.5.2 其他皮肤资料
http://docs.codehaus.org/display/MAVENUSER/Maven+Skins
这个网址列举了一些皮肤实现,可用来参考激发创作灵感。
2.6 站点文档采用了xdoc格式书写,通过maven-site-plugin可以文档自动转为网站,而maven-pdf-plugin则将文档生成为pdf格式
3.
maven-pdf-plugin
执行mvn pdf:pdf以后会在target/pdf目录下生成文档的pdf版本。
这个插件默认是使用fop来生成pdf的,同时也支持itext来生成pdf。
可以定义src/site/pdf.xml,指定要包含哪些文件。
4.
doxia
doxia是一个内容生成框架,可以将各种格式的文档生成为另一种格式
比如mybatis里文档时用xdoc格式写的,结果可以输出为html或pdf格式。
目前doxia支持的文档写作格式见如下网址,大概有10来种。
http://maven.apache.org/doxia/references/index.html
APT, Confluence, Simplified DocBook, Markdown, FML, FO, iText, LaTeX, RTF, TWiki, XDoc, XHTML
另外还有一个eclipse插件,可以可视化的书写文档
http://maven.apache.org/doxia/doxia-ide/eclipse/
5. 打包插件
功能是打包成uber-jar。所谓的uber-jar,就是一个fat jar,包含了所有的第三方类库的class文件。之所以需要这样做,是用来将第三方的jar包(javaassist, ognl)一同打入到mybatis里用的。其中一个考虑点是避免不同版本的javassist出现jar包冲突问题。(这里打个比方,比如mybatis用了javassist 1,而客户用了javassist 2,那就jar包冲突了。)mybatis将javassist等重新换个包名打包就可以避免jar包冲突问题了。
mybatis3.3之前采用jarjar-maven-plugin,而之后换成了maven-shade-plugin
5.1 jarjar-maven-plugin
http://sonatype.github.io/jarjar-maven-plugin/
https://github.com/sonatype/jarjar-maven-plugin
https://code.google.com/p/jarjar/
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>jarjar-maven-plugin</artifactId>
<configuration>
<input>{classes}</input>
<input>{test-classes}</input>
<includes>
<include>ognl:ognl</include>
<include>org.javassist:javassist</include>
</includes>
<rules>
<rule>
<pattern>ognl.**</pattern>
<result>org.apache.ibatis.ognl.@1</result>
</rule>
<rule>
<pattern>javassist.**</pattern>
<result>org.apache.ibatis.javassist.@1</result>
</rule>
<keep>
<pattern>org.apache.ibatis.**</pattern>
</keep>
</rules>
<overwrite>true</overwrite>
</configuration>
<executions>
<execution>
<id>jarjar-classes</id>
<phase>process-test-classes</phase>
<goals>
<goal>jarjar</goal>
</goals>
<configuration>
<input>{classes}</input>
</configuration>
</execution>
<execution>
<id>jarjar-test-classes</id>
<phase>process-test-classes</phase>
<goals>
<goal>jarjar</goal>
</goals>
<configuration>
<input>{test-classes}</input>
</configuration>
</execution>
</executions>
</plugin>
mvn jarjar:jarjar
执行 mvn site以后在target/jarjar目录下有
hull-classes
hull-test-classes
uber-classes --> 可以用压缩软件打开,其中打包了javaassist, ognl
uber-test-classes
5.2
maven-shade-plugin
这个是新版的mybatis采用的插件,配置如下
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<createDependencyReducedPom>false</createDependencyReducedPom>
<artifactSet>
<includes>
<include>org.mybatis:mybatis</include>
<include>ognl:ognl</include>
<include>org.javassist:javassist</include>
</includes>
</artifactSet>
<relocations>
<relocation>
<pattern>ognl</pattern>
<shadedPattern>org.apache.ibatis.ognl</shadedPattern>
</relocation>
<relocation>
<pattern>javassist</pattern>
<shadedPattern>org.apache.ibatis.javassist</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
6. 项目信息
如果浏览生成的站点的话,会发现左侧边栏有一栏叫“项目信息”
6.1 Project Dependencies
maven-project-info-reports-plugin
可以查看项目依赖的jar包,license。
Dependency Tree可以清晰的查看各个jar包之间的依赖关系
Project Plugins可以查看用到的plugin
7.项目报表
一堆报表啊,牛叉~~~
7.1 JavaDocs
很简单,用来生成javadoc的
7.1.1
maven-javadoc-plugin/
javadoc插件,没杀好说的。
7.1.2
doclava
一个新的javadoc的皮肤,使得报表看起来新颖,漂亮。
使用范例如下
<doclet>com.google.doclava.Doclava</doclet>
<docletArtifact>
<groupId>com.google.doclava</groupId>
<artifactId>doclava</artifactId>
<version>1.0.6</version>
</docletArtifact>
7.1.3 关于doclet
http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html
http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/doclet/spec/index.html
7.1.4 另一个doclet是
umlgraph
可用来自动生成类图和序列图。
另外要生成图片,还需要
Graphviz
生成类图的步骤:
1).
下载
2). 环境变量加入 GRAPHVIZ_HOME=F:\down\graphviz-2.38\release
3).将%GRAPHVIZ_HOME%/bin加入到path
4).修改pom.xml,以使用新的doclet
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
<docletPath>%GRAPHVIZ_HOME%/bin</docletPath>
<docletArtifact>
<groupId>org.umlgraph</groupId>
<artifactId>doclet</artifactId>
<version>5.1</version>
</docletArtifact>
<additionalparam>-views</additionalparam>
<useStandardDocletOptions>true</useStandardDocletOptions>
</configuration>
</plugin>
5).执行mvn javadoc:javadoc
可以看到
target\site\apidocs\org\apache\ibatis\builder下面多出了一些png图片,这些就是类图了。
下图是生成的一个效果图。
7.2 Source Xref/Test Source Xref
主要方便别人,不用下载源码,可以直接在你的网站上查看源代码和测试代码的。
只要定义如下的
maven-jxr-plugin,这样生成的站点报表里就含有它了。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jxr-plugin</artifactId>
<version>2.4</version>
</plugin>
7.3 JDepend
JDepend
jdepend-maven-plugin
用来查看各个包之间的依赖程度,可以作为衡量类的层次结构的设计质量的一个参考。
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>jdepend-maven-plugin</artifactId>
<version>2.0</version>
</plugin>
7.4 FindBugs Report
用来分析代码是否有潜藏bug的工具
FindBugs
findbugs-maven-plugin
新的插件已经是3.0了。
随便提一下,FindBugs用BCEL来解析java字节码,用dom4j来处理xml
7.5 Surefire Report
单元测试的统计报表
maven-surefire-report-plugin
主要做的工作是解析surefire-reports下的TEST-*.xml文件,然后将他们渲染成DOXIA格式,进而用来生成站点。
7.6 PMD
PMD
和findbugs一样也是用来查找代码缺陷的。
maven-pmd-plugin
加上这句话以后
<linkXref>true</linkXref>
可以发现点击缺陷可以链接到Xref源码那里。
7.7 CPD
查重复代码的。Copy/Paste Detector (CPD)
http://pmd.sourceforge.net/pmd-5.1.3/cpd.html
7.8 Tag List Report
可以生成TODO,FIXME等信息的报表
taglist-maven-plugin
7.9 Clirr Results
7.9.1
clirr
软件不同版本之间的兼容性我们可能一般会忽略,其实这个也是要考虑的。不然如果你的API频繁改动的话,别人写的老的代码在新的版本下就编译不过了。
Clirr 是用来检查2个版本之间的兼容性的,只要给他2个jar,它就可以dump出变化的API。
7.9.2
clirr-maven-plugin
<clirr.comparisonVersion>3.2.5</clirr.comparisonVersion>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>clirr-maven-plugin</artifactId>
<version>2.6.1</version>
<configuration>
<comparisonVersion>${clirr.comparisonVersion}</comparisonVersion>
<failOnError>false</failOnError>
<failOnWarning>false</failOnWarning>
</configuration>
</plugin>
如上例可看到,比较的是mybatis3.2.5和3.3.0-SNAPSHOT之间的差异
编译的时候,如果本地没有mybatis3.2.5的话,插件会自动去maven仓库去下载3.2.5到本地仓库,然后比较。
7.10
versions-maven-plugin
- Property Updates Report
生成property的变化报表
- Plugin Updates Report
列举了项目用到的plugin,同时提示plugin是否有最新版本
- Dependency Updates Report
列举了项目用到的的dependency,同时提示dependency是否有最新版本
注意点:使用这个插件,pom.xml不能保存为UTF-8 带BOM, 需要存为不带BOM的,否则会出以下错
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.4:site (default-site) on project mybatis: Error generating versions-maven-plugin:2.1:property-updates-report: only whitespace content allowed before start tag and not \u9518 (position: START_DOCUMENT seen \u9518... @1:1) -> [Help 1]
7.11 Cobertura Test Coverage
单元测试覆盖率报告
7.11.1
cobertura
是基于jcoverage的单元测试覆盖率报告工具
7.11.2
cobertura-maven-plugin
7.12 Jacoco Coverage
单元测试覆盖率报告,貌似这个现在更高端流行
jacoco
jacoco-maven-plugin
<!-- Introducing jacoco for sonarqube usage initially -->
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.7.2.201409121644</version>
<executions>
<execution>
<id>prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>report</id>
<goals>
<goal>report</goal>
</goals>
</execution>
</executions>
</plugin>
8.其他插件
8.1
maven-enforcer-plugin
用来定义一些必须遵守的配置,校验开发环境。比如JDK的版本,Maven的版本,开发环境(Linux,Windows等),依赖jar包的版本等等。
8.2
animal-sniffer-maven-plugin
animal-sniffer
用来检查打包出来的jar包是否兼容老的JDK版本(如JDK5)
名字的由来:动物嗅探器,因为JDK的版本都是用动物名字命名的(tiger等等),所以这个工具就是用来嗅出JDK版本的
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>animal-sniffer-maven-plugin</artifactId>
<version>1.11</version>
<configuration>
<signature>
<groupId>org.codehaus.mojo.signature</groupId>
<artifactId>java16</artifactId>
<version>1.1</version>
</signature>
</configuration>
<executions>
<execution>
<id>check-java-1.6-compat</id>
<phase>process-classes</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
其中的java16表示要兼容JDK6,更多的签名可以参考
http://mojo.codehaus.org/signatures/
8.3 maven-bundle-plugin
maven-bundle-plugin
Bnd
是和OSGI打包有关的
8.4
maven-changes-plugin
用来展示这个版本有哪些变化
<issueManagement>
<system>GitHub Issue Management</system>
<url>https://github.com/mybatis/mybatis-3/issues</url>
</issueManagement>
<configuration>
<issueLinkTemplate>%URL%/issues/%ISSUE%</issueLinkTemplate>
</configuration>
8.5
maven-source-plugin
用来将代码打包到一个jar中
8.6
maven-gpg-plugin
用
GnuPG来给包签名
9. 总结
我们平时做项目一般把代码写完就结束了,但是mybatis不然,非常重视文档。
mybatis用到了很多maven插件来生成文档(站点),是一个可以供大家学习模仿的好sample。
一些常用插件的列表可以参考
http://maven.apache.org/plugins/index.html
- 大小: 12.5 KB
分享到:
相关推荐
总结来说,Mybatis+Maven插件的使用可以大大提高Java开发的效率,让开发者更专注于业务逻辑,而不是繁琐的基础框架搭建。在实际开发中,熟练掌握这两个工具及其插件的使用,将极大提升开发质量和速度。
通过配置 `maven-site-plugin` 和 `maven-project-info-reports-plugin`,可以在 Maven 站点中生成 PDF。 ```xml <groupId>org.apache.maven.plugins <artifactId>maven-site-plugin <version>3.9.1 ...
- 在Eclipse中安装Maven插件,可以通过`Help > Install New Software`,添加Sonatype的M2Eclipse站点:`http://m2eclipse.sonatype.org/sites/m2e/`,完成安装后重启Eclipse。 - 推荐使用独立安装的Maven而非Eclipse...
Maven的生命周期包括了clean、default和site三个阶段,分别对应清理、构建和生成站点文档的操作。插件如maven-compiler-plugin用于编译源代码,maven-surefire-plugin用于执行单元测试,maven-jar-plugin则负责打包...
2. **Maven生命周期**:Maven有多个生命周期阶段,如clean(清理)、default(构建)和site(生成站点文档)。例如,`mvn clean compile`会清理目标目录,然后编译源代码。 3. **Maven仓库**:Maven使用本地仓库...
【Apache Maven 3.3.9】是Java开发中的一款重要构建工具,它极大地简化了项目的构建...在学习和使用过程中,了解和掌握Maven的工作原理、POM的编写、生命周期和插件的应用,对于提升JavaEE项目开发的专业水平至关重要。
"SSM_handbook_site"可能是一个包含SSM框架相关文档或教程的站点,提供关于如何使用SSM,以及如何结合maven archetype进行项目初始化的详细指南。访问博文链接(https://huangmin001.iteye.com/blog/1185781)可以...
- `mvn site`:生成项目站点文档。 ### 实际应用场景 根据提供的部分内容,可以看出该文件描述了一个具体项目的构建与架构设计,涉及到的技术栈包括Spring MVC、MyBatis、Shiro、REST、WebService、JMS、Lucene、...
1. **插件安装**:用户可以通过Eclipse的内置更新站点或者从官方网站下载插件安装包,然后按照Eclipse的插件安装向导进行安装。 2. **创建项目**:在Eclipse中选择“File” > “New” > “Project”,找到Jfinal相关...
Maven是一个项目管理和综合工具,它管理项目的构建、依赖关系和文档生成。在Eclipse 3.7中,我们不能直接通过Install New Software安装m2e(Maven Integration for Eclipse)的稳定版本,因为它可能与新版本的...
- 通过Maven插件可以在构建过程中执行这些检查,确保代码质量。 总之,“mavenIntelij-master.zip”中的内容可能涵盖了以上所有知识点,详细说明了如何在IntelliJ IDEA中有效地利用Maven进行Java项目的开发、构建...
9. **文档生成**:Maven可以生成项目文档,包括API文档(通过javadoc插件)和项目信息报告(通过site插件)。 10. **质量保证**:Maven可以配合SonarQube等工具进行静态代码分析,确保代码质量。 总结,"mavenproj...
- **安装方法**:通过Eclipse Marketplace搜索并安装Koala4插件,或手动下载插件包进行安装。 #### 插件使用 **创建项目** - **选择模板**:根据需求选择合适的项目模板。 - **配置信息**:设置项目名称、选择项目...
Apache Maven Repository是一个广泛使用的JAR包下载站点,提供了大量的开源库和框架的JAR包。通过Maven Repository,开发者可以方便地下载和引用所需的库文件,避免了手动搜索和下载的麻烦。 ### 27. Java与Spring...