内容: 在你的代码中自动实现设计规范
在你的工具箱中增加Hammurapi—一个遵循设计的解决方案
作者:Sidharth Sankar
翻译:xMatrix

版权声明：可以任意转载，转载时请务必以超链接形式标明文章原始出处和作者信息及本声明
作者:
Sidharth Sankar;xMatrix
原文地址:http://www.javaworld.com/javaworld/jw-04-2005/jw-0418-hammurapi.html
中文地址:http://www.matrix.org.cn/resource/article/43/43890_design_guidelines.html
关键词： design guidelines


摘要
设计规范只表示纯粹的想法；但项目的成功来说，实现这些规范是必须的。传统的实现方式是代码评审。Hammurapi是一个遵循设计的工具，提供了自动而且一致的方式来实现设计规范，因此使代码评审更加有效而轻松。在这篇文章中，作者介绍了Hammurapi的使用，并与其他类似工具进行比较，最后还给出演示如何使用的例子。

作为一个J2EE架构师，我需要分发详细设计给项目团队。通过UML模型，我也会分发那些捕获最佳实践的设计规范。例如，在Struts应用中，我推荐避免在Action类中使用实例变量，因为Action类是单例的，而且多个线程同时访问一个Action类实例是很平常的。其他例子如在任何DAO应用中，一个重要的设计方针是关闭所有打开的数据库资源，如果没有这么做通常将导致灾难，尤其是在一个产品环境中。

想法是很好的，但是实现才是关键。现在最常用的实现设计规范的方法是做代码评审，通常是有经验的成员检查代码来找出不符合规范的地方。这些代码可能是没有遵守编码规范或者设计规范。

这是一种非常低效的方法，主要表现在两方面：1、这需要两种资源（开发人员和评审人员）。2、质量变成评审人员的职责。此外，在我的经历中，由于评审人员过于重视规范，使得他们与开发人员对立起来，而这对一个团队来说是不好的。

许多年前，我接触过Checkstyle，这是一个自动强制代码规范的工具。他与Ant无缝集成并且由基于XML配置文件来驱动。

Hammurapi是一个与Checkstyle类似的工具，只是他用来强制设计规范。Hammurapi是一个由Pavel Vlasov开发的开源软件，他可以基于一套设计规范来分析代码库。当他遇到违反规范的地方，会在报告中标识。就像Checkstyle一样，他与Ant无缝集成并且由基于XML配置文件来驱动。

运行Hammurapi
你可以直接从命令行运行Hammurapi或者作为Eclipse的插件来使用。在这篇幅文章中，我主要讨论如何通过Ant任务来运行Hammurapi。

注意：你可以从资源中下载与本文对应的源程序。
与Ant集成非常容易，如下面代码所示：

1 
2  
3   
4   
5    
6   
7   
8  
9  
10   
11   

12   
13   
14   
15   
16  
17 

第一行定义了一个design_review的目标。他依赖于init目标—初始化构建的属性（如第四行的${hammurapi.home}）。第二行定义了一个“hammurapi新任务。这个Ant任务由org.hammurap.HammurapiTask类实现。内嵌的classpath元素定义了定义这个任务所需要的类库。

第九行声明了一个先前定义的hammurapi任务。运行这个任务相当简单：只要定义内嵌的src元素就可以了，他会告诉任务上哪儿查找源程序；然后定义另一个元素output，这告诉任务在哪儿输出报告。第十行告诉任务在项目任务目录下的src目录下查找需要评审的源程序。第十一行告诉任务输出报告到项目目录下的docsreview中。

第十二行的classpath元素是可选的，他定义了源程序依赖的类库位置。
Hammurapi带有100多个内建的检查器。每一个对应一个设计规范。

先前列出的Ant代码片断将在log4j源程序上运行Hammurapi。代码将被解压到项目目录下的src目录。图1显示了生成的报告的打开页面。Hammurapi最令人激动的特性就是他生成的全面的报告。



图1例示了报告report.html的主页，右边的框架显示了三个标题：结果、严重性小结和文件。

结果段落显示整体评审的统计。如图1中所示，26个包中的179个文件被评审了；其中包含6344违反规范的地方。

严重性小结段落以表的方式来显示违反规范的地方。每一项属于一个严重级别。预定义的级别包含1-5级。级别1是最严重的。

文件段落(图2)列出了每一个被评审的文件和他所违反的规范。


虽然严重性小结段落可以回答如多少空catch块被找到，文件段落可以回答在Appender.java中多少规范被违反。但是Hammurapi最有用的功能是他可以在报告中显示违反规范所在的代码行数。如让我们分析一下设计规范ER002：空catch块（图2）。点击数字列的超链就可以显示报告这个违反的文件，如图3所示。



在很多文件中，报告显示LogRecord.java (3)在第307行违反了这个规范。在行数下的超链直接链接到源程序，如图4的示。



虽然从整个代码库的运行Hammurapi是最常用的方式，但你也可以使用增量的评审自上一次评审后改变的代码。这在代码库非常大评审需要很长时间时非常有用。

另一个运行Hammurapi的有效方式是可以处理压缩文件和其所依赖的并生成压缩的结果文件。这种方式在开发团队分布在不同的地理位置时非常有用。在这个情况下，源程序被压缩并传送到远程的评审点。

其他设计评审工具
Hammurapi并非是仅有的代码评审工具。Metrics也是一个可以作为Eclipse的很流行的类似工具。然而他有两个主要的缺点：首先他和Eclipse紧密结合，想要与Ant结合相当麻烦。由于需要Eclipse的类库，这使得不使用Eclipse作为IDE的项目不能使用Metrics。其次，你不能用Metrics构造自定义的检查器（Hammurapi可以）--这限制了用户只能使用内建的检查器。

其他的工具还有PMD。类似于Hammurapi，他与Ant无缝集成而且允许自定义检查器。然而PMD生成的报告不如Hammurapi生成的报告全面。

Hammurapi如何工作
Hammurapi这样的代码分析工具都带有语言分析器。语言分析器是一种输入语言代码并输出抽象语法树的工具。这个树上的节点代表语言标识。例如，考虑一下简单的算术表达式：3+4. 语言分析器会解析他成为一个如图5所示的语法树。在这个树中，节点+代表操作符标识。节点3和4是操作数标识。


Hammurapi使用ANTLR（另一个语言识别工具）作为语言分析器。然而ANTLR API是相当底层的。为改善可用性，Hammurapi使用另一个API，基于ANTLR 的JSEL（Java源程序工程类库），来访问抽象语法树。

一旦树构建完成，一种树遍历算法就被用来访问树中每一个节点。每次访问到一个节点，一种回调机制（Visitor模式）被用来提示相应的检查器。在这些回调方法中，检查器收集相关的信息来确定是否有违反规范的地方存在。

构建自定义的检查器
一个自定义检查器可以更好理解Hammurapi框架。如前面所提，一种Struts的最佳实践是避免Action类中的实例变量。所以我们会构建一个自定义检查器ActionClassInspector，他扫描源程序中的Action类，如果一个Action类被发现，他就扫描是否存在实例变量。如果一个以上的实例变量被发现，他就标识出相应的违反。

图6例示了ActionClassInspector类的变量和方法。所有的检查器都继承自org.hammurapi.InspectorBase类。



图7例示了Hammurapi框架激活ActionClassInspector类的回调方法的时序图。框架解析源程序并构建一个抽象语法树，然后访问树中的每一个节点。当一个类节点被访问时，他调用visit( v:VariableDefinition )方法。因为通常一个类可能包含多个变量，这个方法可能会被调用多次。



下面的代码显示了visit( c:Class )方法：

1 public void visit( com.pavelvlasov.jsel.Class c ) throws Exception
2 {
3  isActionClass = c.isKindOf( "org.apache.struts.action.Action");
4
5  return;
6 }

这个方法负责确定是否一个特定的类是Action类。这个测试在第三行被执行。如果测试是肯定的，那么isActionClass被设置为真。这个规范仅应用于Action类。
下面的代码例示了visit( v:VariableDefinition )方法：

1 public void visit( com.pavelvlasov.jsel.VariableDefinition v ) throws Exception
2 {
3  List modifiers;
4  Scope scope;
5
6  if( this.isActionClass )
7  {
8   modifiers = v.getModifiers( );
9   scope = v.getEnclosingScope( );
10   if( scope instanceof com.pavelvlasov.jsel.impl.ClassImpl )
11   {
12   if( modifiers.contains( "static" ) )
13   {
14    ;//Do nothing; this class is compliant.
15   }
16   else
17   {
18    context.reportViolation( (SourceMarker)d, "Violation" );
19   }
20   }
21  }
22
23  return;
24 }

这个方法负责确定是否一个特定的变量是实例变量。如果是就报告一个违反。第十行确定变量的范围。这个测试过滤掉方法范围内的变量。仅有类或实例范围的变量会被继续处理。第十二行确定是否一个变量是静态的。如果不是，就报告一个违反，如18行所示：

运行自定义检查器只需要对前面所示例的Ant脚本作一点小小的修改。下面高亮的代码显示了修改的地方：

1 
10  
5  

6  
7   
8   
9   
10   
11   
12  
13  
14  
17 

第十三行，包含了可选的元素inspectors，他的file属性说明了任务会去config目录下的文件inspectors.xml中查找相应的检查器。下面列出了inspectors.xml文件的内容：

1 <?xml version="1.0" encoding="UTF-8"?>
2 
3  
4   GDL-004
5   yes
6   3
7   
8   
9   No instance variables in Action classes.
10   
11   yes
12   
13   Action classes must not have instance variables.
14   
15   Struts best practices.
16  
17 

注意在这里可以用URL来定义inspectors.xml文件的位置。在这种情况下，inspectors.xml文件可以放在远程网络服务器上。

总结
总的来说，Hammurapi是一个优秀的遵循设计的工具。因为他与Ant无缝集成，而Ant可以与任何市面上的IDE集成，所以Hammurapi可以很容易的加入已有的开发环境中。

Hammurapi的报告是非常全面的。他提供了基于规则和基于文件夹的两种不同的违反视图。此外，他在报告中结合了源程序，使得报告整体自包含的。

Hammurapi包含超过100个内建的检查器。此外，Hammurapi提供了一个简单易用的API用来构建和管理自定义检查器。

关于作者
Sidharth Sankar是印度Mohali一家专业从事J2EE技术公司（Infosys技术有限公司）的高级技术专家。他拥有华盛顿大学的计算机硕士学位，他从1996开始从事Java领域的工作，从1999年开始从事J2EE方面的工作。

资源
·下载与这篇文章对应的源程序：
http://www.javaworld.com/javaworld/jw-04-2005/hammurapi/jw-0418-hammurapi.zip
·下载Hammurapi
http://www.hammurapi.org
·关于Hammurapi的五分钟的介绍：
http://prdownloads.sourceforge.net/hammurapi/Hammurapi.pdf?download
·Hammurapi用户手册
http://prdownloads.sourceforge.net/hammurapi/UserManual.pdf?download
·更多JAVA开发工具的文章，可以游览JavaWorld的主题索引的开发工具部分:
http://www.javaworld.com/channel_content/jw-tools-index.shtml



Java, java, J2SE, j2se, J2EE, j2ee, J2ME, j2me, ejb, ejb3, JBOSS, jboss, spring, hibernate, jdo, struts, webwork, ajax, AJAX, mysql, MySQL, Oracle, Weblogic, Websphere, scjp, scjd

标签：