第十五章 生成项目站点

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 发布站点。