`
xpenxpen
  • 浏览: 725016 次
  • 性别: Icon_minigender_1
  • 来自: 上海
社区版块
存档分类
最新评论

通过mybatis工程学习用maven插件生成站点文档

阅读更多
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插件

    总结来说,Mybatis+Maven插件的使用可以大大提高Java开发的效率,让开发者更专注于业务逻辑,而不是繁琐的基础框架搭建。在实际开发中,熟练掌握这两个工具及其插件的使用,将极大提升开发质量和速度。

    maven pdf

    通过配置 `maven-site-plugin` 和 `maven-project-info-reports-plugin`,可以在 Maven 站点中生成 PDF。 ```xml &lt;groupId&gt;org.apache.maven.plugins &lt;artifactId&gt;maven-site-plugin &lt;version&gt;3.9.1 ...

    基于Maven的Spring+SpringMVC+Mybatis的环境搭建

    - 在Eclipse中安装Maven插件,可以通过`Help &gt; Install New Software`,添加Sonatype的M2Eclipse站点:`http://m2eclipse.sonatype.org/sites/m2e/`,完成安装后重启Eclipse。 - 推荐使用独立安装的Maven而非Eclipse...

    Maven3.3.9.zip

    Maven的生命周期包括了clean、default和site三个阶段,分别对应清理、构建和生成站点文档的操作。插件如maven-compiler-plugin用于编译源代码,maven-surefire-plugin用于执行单元测试,maven-jar-plugin则负责打包...

    简单的maven+SSM小项目

    2. **Maven生命周期**:Maven有多个生命周期阶段,如clean(清理)、default(构建)和site(生成站点文档)。例如,`mvn clean compile`会清理目标目录,然后编译源代码。 3. **Maven仓库**:Maven使用本地仓库...

    apache-maven-3.3.9.zip

    【Apache Maven 3.3.9】是Java开发中的一款重要构建工具,它极大地简化了项目的构建...在学习和使用过程中,了解和掌握Maven的工作原理、POM的编写、生命周期和插件的应用,对于提升JavaEE项目开发的专业水平至关重要。

    一个SSM框架的maven archetype

    "SSM_handbook_site"可能是一个包含SSM框架相关文档或教程的站点,提供关于如何使用SSM,以及如何结合maven archetype进行项目初始化的详细指南。访问博文链接(https://huangmin001.iteye.com/blog/1185781)可以...

    maven构建工具

    - `mvn site`:生成项目站点文档。 ### 实际应用场景 根据提供的部分内容,可以看出该文件描述了一个具体项目的构建与架构设计,涉及到的技术栈包括Spring MVC、MyBatis、Shiro、REST、WebService、JMS、Lucene、...

    Jfinal3.x eclipse插件

    1. **插件安装**:用户可以通过Eclipse的内置更新站点或者从官方网站下载插件安装包,然后按照Eclipse的插件安装向导进行安装。 2. **创建项目**:在Eclipse中选择“File” &gt; “New” &gt; “Project”,找到Jfinal相关...

    eclipse开发环境搭建

    Maven是一个项目管理和综合工具,它管理项目的构建、依赖关系和文档生成。在Eclipse 3.7中,我们不能直接通过Install New Software安装m2e(Maven Integration for Eclipse)的稳定版本,因为它可能与新版本的...

    专家

    - 通过Maven插件可以在构建过程中执行这些检查,确保代码质量。 总之,“mavenIntelij-master.zip”中的内容可能涵盖了以上所有知识点,详细说明了如何在IntelliJ IDEA中有效地利用Maven进行Java项目的开发、构建...

    mavenproj

    9. **文档生成**:Maven可以生成项目文档,包括API文档(通过javadoc插件)和项目信息报告(通过site插件)。 10. **质量保证**:Maven可以配合SonarQube等工具进行静态代码分析,确保代码质量。 总结,"mavenproj...

    考拉开发指南

    - **安装方法**:通过Eclipse Marketplace搜索并安装Koala4插件,或手动下载插件包进行安装。 #### 插件使用 **创建项目** - **选择模板**:根据需求选择合适的项目模板。 - **配置信息**:设置项目名称、选择项目...

    IT技术文章示例

    Apache Maven Repository是一个广泛使用的JAR包下载站点,提供了大量的开源库和框架的JAR包。通过Maven Repository,开发者可以方便地下载和引用所需的库文件,避免了手动搜索和下载的麻烦。 ### 27. Java与Spring...

Global site tag (gtag.js) - Google Analytics