1. Maven 社区提供了大量插件,能让用户生成各种各样的项目审查报告,包括测试覆盖率、静态代码分析、代码变更等。 Maven Site Plugin 可以让用户生成项目的 Maven 站点,以展示这些报告。
2. 站点 生成的逻辑是 Maven 2 核心的一部分,但鉴于灵活性和可扩展性考虑, Maven 3 已经从核心中移除这部分逻辑。所以 Maven 2 应该使用最新的 2.x 版本的 maven-site-plugin ,而 Maven 3 应该使用最新的 3.x 版本的 maven-site-plugin 。
3. site 生命周期中 pre-site 与 post-site 默认没有绑定任何插件目标。 site 绑定了 maven-site-plugin 的 site 目标,该目标负责生成项目站点。 site-deploy 绑定了 maven-site-plugin 的 deploy 目标,该目标负责将站点部署至远程服务器。
4. 使用 mvn site 可以在项目的 target/site 目录下生成站点文件。但多模块的站点页面上子模块的链接无法跳转到子模块项目页面,这是由于多模块 Maven 项目本身的目录结构导致的。可以使用 mvn site:stage –DstagingDirectory=D:\tmp 将站点预发布到某个本地临时目录下。
5. 项目站点包含了很多项目信息链接,这其实是由 maven-project-info-reports-plugin 的插件生成的。 Maven 3 中,该插件的配置是在 maven-site-plugin 中的,而在 Maven 2 中,该插件的配置内置在核心源码中,因此不需要任何配置就能帮你生成项目信息。
6. maven-project-info-reports-plugin 会基于 POM 配置生成以下项目信息:
1) 关于 (about) :项目描述( <description> 元素)
2) 持续集成 (Continuous Integration) :项目持续集成服务器信息( <ciManagement> 元素)
3) 依赖 (Dependencies) :项目依赖信息
4) 依赖收敛 (Dependency Convergence) :只针对多模块项目生成,提供一些依赖健康状况分析,如各模块使用的依赖版本是否一致、项目中是否有 SNAPSHOT 依赖
5) 依赖管理 (Dependency Management) :基于 <dependencyManagement> 配置生成报告。
6) 问题追踪 (Issue Tracking) :项目的问题追踪系统信息。( <issueManagement> 元素)
7) 邮件列表 (Mailing Lists) :项目的邮件列表信息
8) 插件管理 (Plugin Management) :项目所使用插件的列表
9) 项目许可证 (Project License) :项目许可证信息( <licenses> 元素)
10) 项目概述 (Project Summary) :项目概述包括坐标、名称、描述等
11) 项目团队 (Project Team) :项目团队信息( <developers> 元素)
12) 源码仓库 (Source Repository) :项目的源码仓库信息( <scm> 元素)
7. 可以配置 maven-project-info-reports-plugin 选择性地生成项目信息项:
<project> … <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <version>2.1.2</version> <reportSets> <reportSet> <reports> <report>dependencies</report> <report>project-team</report> <report>issue-tracking</report> <report>license</report> <reports> </reportSet> </reportSets> </plugin> </plugins> </reporting> </project>
注意,对于 Maven 2 项目报告插件的配置是在 <reporting> 元素下的 <plugins> 元素中,但对 Maven 3 ,报告插件配置应该在 Maven Site Plugin 的插件配置 <configuration> 元素下的 <reportPlugins> 元素中。具体可以参考
http://maven.apache.org/plugins/maven-site-plugin/maven-3.html 。
8. maven-javadoc-plugin 使用 JDK 的 javadoc 工具生成项目主源码和测试源码的 JavaDocs 文档,在 <reporting> 元素中 (Maven 2) 或 maven-site-plugin 的 <configuration> 元素中 (Maven 3) 配置该插件,会在生成站点的左边导航栏的 Project Reports 下生成 JavaDocs 和 Test JavaDocs 链接。该插件的最新版本能在聚合项目的站点中得到所有模块的 JavaDocs 。
9. 在 <reporting> 元素中 (Maven 2) 或 maven-site-plugin 的 <configuration> 元素中 (Maven 3) 配置 maven-jxr-plugin(Maven Source Xref) 插件,能够在站点导航栏下的 Project Reports 下生成 Source Xref 链接,以 Web 页面形式在 Maven 站点展示 Java 源代码。若想在聚合模块整合所有源码,需要对该插件添加如下配置:
<configuration><aggregate>true</aggregate></configuration>
10. C heckStyle 能根据一套规则自动检查 Java 代码是否符合编码规范。在 <reporting> 元素中 (Maven 2) 或 maven-site-plugin 的 <configuration> 元素中 (Maven 3) 配置 maven-checkstyle-plugin 插件,能够在站点导航栏下的 Project Reports 下生成 Checkstyle 链接,来展示 CheckStyle 报告。可以添加如下配置选择编码规范:
<configuration><configLocation>config/maven_checks.xml</configLocation></configuration>
CheckStyle 内置了四种规则:
1) c onfig/sun_checks.xml : Sun 定义的编码规范 ( 默认值 )
2) config/maven_checks.xml : Maven 定义的编码规范
3) config/turbine_checks.xml : Turbine 定义的编码规范
4) config/avalon_checks.xml : Avalon 定义的编码规范
maven-checkstyle-plugin 其实是从 ClassPath 中载入规则文件,用户可以在资源目录下(默认为 src/main/resources )定义一个自己的规则文件 checkstyle/my_checks.xml 。再在 <configLocation> 元素中配置该文件。
关于规则文件的具体定义,可以参考 http://checkstyle.sourceforge.net/ 。
11. maven-checkstyle-plugin 还不支持从聚合项目的报告中得到所有模块的 CheckStyle 报告。但我们可以用如下方法配置一个所有模块共享的规则文件:
1) 定义一个 CheckStyle 规则文件模块 com.juvenxu.mvnbook:checkstyle:1.0 。在资源目录下定义一个自己的规则文件 checkstyle/my_checks.xml 。
2) 在聚合模块配置 maven-checkstyle-plugin 依赖该模块:
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-checkstyle-plugin</artifactId> <version>2.5</version> <dependencies> <dependency> <groupId>com.juvenxu.mvnbook</groupId> <artifactId>checkstyle</artifactId> <version>1.0</version> </dependency> </dependencies> </plugin> </plugins> </build>
这样 checkstyle/my_checks.xml 就始终在 maven-checkstyle-plugin 的 ClassPath 中了。
3) 在 <reporting> 元素中 (Maven 2) 或 maven-site-plugin 的 <configuration> 元素中 (Maven 3) 配置 maven-checkstyle-plugin 插件使用 checkstyle/my_checks.xml 规则文件。
12. PMD 可以分析 Java 源代码,寻找代码中的问题,包括潜在的 bug 、无用的代码、可优化的代码、重复代码以及过于复杂的表达式等。具体可以访问 http://pmd.sourceforge.net/ 。
13. 配置了 maven-pmd-plugin 报告生成插件后(配置方法同上),可以在站点导航栏中生成 PMD Report 链接显示分析结果以及 CPD Report 链接显示代码拷贝粘贴的分析结果。 PMD 包含了大量的规则(参见 http://pmd.sourceforge.net/rules/index.html ),默认会使用 rulesets/basic.xml 、 rulesets/unusedcode.xml 和 rulesets/importss.xml. 要使用其他规则可以在插件的 <configuration> 元素下配置 :
<rulesets> <ruleset>rulesets/braces.xml</ruleset> <ruleset>rulesets/naming.xml</ruleset> <ruleset>rulesets/strings.xml</ruleset> </rulesets>
在插件的 <configuration> 元素下配置:
<aggregate>true</aggregate>
可以支持聚合报告。
14. maven-changelog-plugin 能够基于版本控制系统生成三分变更报告:
1) Change Log :基于提交的变更报告,包括每次提交的日期、文件、作者、注释等。
2)D eveloper Activity :基于作者的变更报告,包括作者列表以及每个作者相关的提交次数和涉及文件数目。
3) File Activity :基于文件夹的变更报告,包括变更的文件列表及每个文件的变更次数。
默认可以生成最近 30 天的变更记录,可以配置:
<configuration> <type>range</type> <range>60</range> </configuration>
改变变更记录的天数。
15. cobertura-maven-plugin 可以在站点中生成测试覆盖率报告,但不支持聚合报告。
16. 用户可以在 src/site 目录下定义一个 site.xml 的站点描述符文件来自定义站点外观。该文件由 XML Schema 约束定义,相关 xsd 文件位于:
http://maven.apache.org/xsd/decoration-1.0.0.xsd 。
描述符文件以 <project> 元素为根,可以定义:
1 ) <bannerLeft> 和 <bannerRight> 站点头部左右两边的图片 (<src> 元素 ) 和连接地址( <href> 元素),站点的全用的本地 web 资源必须位于 src/site/resources 目录下
2 ) <version> 项目版本号, position 属性定义了版本号显示的位置, none 、 left( 头部左边 ) 、 right (头部右边)、 navigation-top 、 navigation-bottom 和 bottom 。
3 )< publishDate> 项目最近发布时间,其显示位置配置同上。
4 ) 可以定义站点的面包屑导航:
<body> <breadcrumbs> <item name=”Maven” href=”http://maven.apache.org” /> <item name=”Juven Xu” href=”http://www.juvenxu.com” /> </breadcrumbs> </body>
5 ) <skin> 可以定义站点使用的皮肤插件。 Maven 定义了三种皮肤插件:
a ) maven-classic-skin
b ) maven-default-skin (默认的皮肤)
c ) maven-stylus-skin
groupId 都是 org.apache.maven.skins 。另外在 GoogleCode 上托管了 com.googlecode.fluido-skin:fluido-skin 插件非常清爽简洁。( http://code.google.com/p/fluido-skin/ )
6 ) 可以定义站点左边的导航栏:
<body> <menu name=”${project.name}”> <item name=”Introduction” href=”introduction.html”/> <item name=”Usage” href=”usage.html” /> <item name=”FAQ” href=”faq.html”/> </menu> <menu ref=”reports”/> </body>
Ref 中引用的是 Maven 站点默认生成的页面。 Report 表示引用项目报告菜单, parent 表示包含父模块链接的菜单, modules 表示包含所有子模块链接的菜单。
17. 可以在 src/site/apt/ 目录下创建 site 的 APT 文档( Almost Plain Text ,参见 http://maven.apache.org/doxia/references/apt-format.html ),或在 src/site/apt 目录下创建 site 的 FML 文档( FAQ Markup Language ,参见 http://maven.apache.org/doxia/references/fml-format.html )。
18. 可以配置如下属性,让 Maven 用指定编码读取源码及文档以及呈现站点的 html 文档。
<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties>
可以为 maven-site-plugin 配置
<configuration><locales>zh_CN</locales>
来设置用什么语言呈现站点。
19. 在 POM 中配置站点服务器信息:
<distributionManagment> <site> <id>app-site</id> <url>dav:https://www.juvenxu.com/sites/app</url> </site> </distributionManagement>
同样可以在 settings.xml 的 <servers> 元素中配置站点服务器的用户名和密码。
Maven 支持 FTP 、 SCP 和 DAV 协议部署站点。对 FTP 需要在 <build> 元素下配置 FTP 扩展组件:
<extensions> <extension> <groupId>org.apache.maven.wagon</gorupId> <artifactId>wagon-ftp</artifactId> <version>1.0-beta-6</version> </extension> </extensions>
SCP 协议是通过密钥进行认证的,需要在 settings.xml 中配置认证信息:
<server> <id>app-site</id> <passphrase>password</passphrase> <privateKey>C:/sshkeys/id_rsa</privateKey> </server>
privateKey 表示私钥地址, passphrase 表示私钥口令。
可以用 mvn clean site-deploy 发布站点。