Java API设计指南（一）

　　作者： Eamonn McManus
　　原文地址： http://www.artima.com/weblogs/viewpost.jsp?thread=142428
　　译文地址： http://gocom.primeton.com/modules/newbb/forumtopic4585_4075_40.htm
　　译者： 王磊
　　电子邮件： [e-mail]

 

Java API设计指南（二）

　　前言

　　市场上关于如何设计和编写优秀Java代码的书如此之多，可能要用汗牛充椟来形容，但是想找到一本如何设计API的书，却是难之又难。这里我将把自己一些关于API设计的经验与大家分享。

　　分享这些经验是源于最近我参加了JavaPolis上的一个讨论，这个讨论是由Elliotte Rusty Harold发起的，是关于设计XOM时的一些原则性问题，讨论中的思想交流如此精采，令我受益颇多。虽然这次讨论主题是与XOM有关，但是大部分的时间 我们都在讨论设计XOM API时的一些原则性问题，而这些内容对于API设计而言，则是通用的。这几年，Java的应用日益广泛，开源项目也是蒸蒸日上。一本能够指导开发人员设 计和编写API的好书，可以帮助开发人员设计和编写更好的API。

　　在过去的五年中，我一直参与JMX API的修订及调整，在此过程中，同样受益颇多。特别在这次讨论会，我对Elliotte提出的一些观点高举双手赞同。

　　接下来的内容是讨论会上的一些主要观点的总结，其中包括一些个人或者是来自他人的经验，也参考一些相关的文档，希望对大家设计API有所裨益。

　　下面是个人推荐的一些阅读和参考资料。

　　下面给出的网址是Netbeans网站上的一篇关于API设计的优秀文档，

　　http://openide.netbeans.org/tutorial/api-design.html

　　Josh Bloch's 的Effective Java作为Java设计的圣经之一，从来都不会被漏下。

　　设计需要进化

　　API的价值就在于能够帮助你完成许多功能，但请不要忘记要持续的改善它，否则它的价值就会逐渐减少。而且要根据用户的反馈信息，来改善 API，或者说是对API进行演化，另外改进API时要注意的就是在不同版本间要保持兼容性，这点至关重要，它也是一个API是否成功的重要标识之一。

　　如果一个功能以API的方式公布出来，那么在发布以后，它的对外接口就已经固定，无论什么情况，都不能取消，而且一定要能够按照原有的约定功能 正确执行。如果API不能在版本间保持兼容性(译注：这里应该指的是向下兼容)，用户将会难以接受这样一个千变万化的API，最终的结果只能是让用户放弃 使用你的API。如果你的API被大量的软件或者模块所使用，又或者被大型软件使用，这个兼容问题也就愈加严重。

　　以一个Java应用程序为例，如果Module1使用了Banana1.0的API，而Module2则使用了Banana2.0的API，现 在要同时部署这两个模块到一个Web Application上，如果Banana2.0对Banana1.0保持兼容的话，整个部署就会非常简单，直接使用Banana2.0就可以了。如果 Banana2.0和Banana1.0不兼容的话，就很难同时在一个程序中同时使用Module1和Module2(可能要自定义 ClassLoader，或者是其它方式，这对于用户未免有些为难了)。最终的结果可能就是你失去一个用户，这时的API就不能为他人提供任何价值(译 注：看来它也不能带来经济价值了)。

　　分析Java SE平台所提供的API，有着严格的兼容性控制。其根本目标就在于保证用户在版本升级时，不会导致低版本的代码无法运行。这也再次说明，当一个API发布 以后，任何API公开的方法，常量等元素都不能被移出API，否则会严重降低API的价值。(译注：所以个人一向比较怀疑deprecated的价值，因 为既然所有的方法都不会被删除，即使那些被 deprecasted的方法和变量也会被仍然保留，其功能也不应该会被改变，因此从这个角度来说，其方法和变量的使用仍然是安全的。)

　　说到兼容性，必然要谈到二进制兼容性，这是指对于已经编译完成的代码，不会因为版本的变更，而致使编译后的代码不能正常运行。比如说你将一个public方法从API中移走，就会无法正常运行，会抛出NoSuchMethodException这类错误。

　　但源代码的兼容性也不可忽视，在某些特殊情况下，修改API时，会产生源代码兼容问题，导致源代码无法编译通过。例如添加一个重载的同名方法， 其参数不同，如getName(User)和getName(String)，当用户使用getName(null)时，会因为存在二义性，而产生编译错 误，用户必须给出getName((String)null)，来明确标识要调用的方法。因此必须寻找一种方式，来保持源代码的兼容性。

　　通常情况下，如果源代码不兼容，代码编译就无法通过，用户必须修改源代码才能保证程序正常运行，但这并不是一个好的解决方案。以J2SE6中的 javax.management.StandardMBean为例，这个类的构造函数已经采用泛型了。这样会使得一些类在创建这个Bean的时候，会出 现编译不能通过的问题，但是解决方案有时却是非常简单，往往只需要添加一个cast进行强类型转换就可以解决这样的一个编译问题了。但是更多的时候，需要 更复杂的方案才能解决这些编译问题，例如在一个方法中调用第三方的API方法，如果有一天这个API方法的参数被修改了，在修改源代码时候，可能会发现你 的方法中不含有API方法需要的参数，这时就需要修改方法参数。以下是这种情况的示范代码。

　　public void callApi(Parameter1 p1,Parameter2 p2)
　　{
　　//do some operations
　　new ThirdClass().doCallThirdApi(p1);
　　}

　　现在第三方的API现在变成了doCallThirdApi(Parameter1 p1,Parameter3 p3)

　　这时可能需要将方法改成：

　　public void callApi(Parameter1 p1,Parameter2 p2,Parameter3 p3)
　　{
　　//do some operations
　　new ThirdClass().doCallThirdApi(p1,p3);
　　}

　　这样一个API的改变，很可能引发一个多米诺骨牌事件。

　　通常情况下，你不知道用户如何使用API来完成工作。除非能够确认API的修改对用户的代码不会造成破坏，才可以考虑修改API。，反之如果 API的改变会影响用户现在的代码，就必须有一个足够的理由。只有意识到对API的修改，会严重的破坏用户现有的代码，在修改API时才会谨慎地，尽量地 保证API兼容性。修改API的时候要尽量避免以下几种情况，以免对用户的代码产生破坏：

　　降低方法的可见性，如将public变成package或者proteced，又或者将protected变成private。

　　修改方法的参数，如删除一个参数、添加一个参数、或者是改变参数的类型，尤以后两者更为严重。

　　就象业界游行的经验之谈--“不要使用3.0版本以下的软件”(译注：所以我总想把自己的软件直接发布为9.9。)，同样的情况对API也是一 样的，前几个版本的API往往包含有大量的错误，这些错误不应该被隐藏起来，因为纵然是冰山的底部，也终有浮出水面的一天。因此在正式发布API 1.0以前，请不要忘记提供若干个0.x版本。对于使用0.x版本的用户，会有一个比较明确的说明，用户会清楚的知道当前版本所公布的API还不稳定，有 可能在正式发布的时候有所更改，0.x版本也不保证兼容性。(译注：以Visual Studio2000 beta2为例，与正式版的差别就非常大，所以0.x版本通常只是用来学习，或者进行技术预言，而不能在产品中使用)。但是一旦1.0版本正式发布，请记 住，就是对API的兼容性就做出一个正式的承诺。象JCP组织在对某一个规范推出正式版本以前，通常都会发布若干个草稿版本(如意向草稿，公共预览草稿， 最终建议版本等)。如果方便的话，对于规范性的内容，在发布API时，提供一个API的实现可能会更有效的推行规范(译注：因为规范性的内容更多的是以 Interface的方式来发布API，大家可以参考一下Interface和Abstract Class，所以提供一个实现往往更好，象sun发布J2EE规范时，就提供了一个默认的实现。)。

　　当API的设计和开发到了一定阶段以后，可能会发现以前的版本已经出现了一些问题，又或者需要添加新的功能，此时设计人员完全可以重新创建新的 API，并放到新的包中，这样就可以保证那些使用老版本的用户可以很轻松的移植到新版本上，而不会产生问题。请牢记一点：添加新的功能，请不要修改原有的 内容。

　　API的设计目标

　　设计一个API要达到哪位目标呢?除了兼容性以外，也从Elliotte的讨论中提出一些目标。

　　API的正确性必须保证：

　　以XOM为例，无论用户如何调用API，都不应该产生错误的XML文档。再如JMX，不管是注册一个错误的MBean还是并发执行一些操作，又 或者MBeans使用了一些特殊的名称，MBean Server都必须保持状态的一致性，不能在某个错误的MBeans进行了操作以后，整个系统就无法提供服务。

　　API的易用性：

　　API必须易于使用。通常易用性一向难以评价。但是有一个办法可以有效的提高易用性，就是编写大量范例代码，并将其很好的组织在一起，从而为用户提供API参考。(译注：个人认为一个好的FAQ可以提供各种API使用的范例。)

　　另外下列原则也可以用来判断API的易用性：

　　是不是总是经常出现一组操作代码?(译注：这里是指如果有多行代码重复被调用，说明它们应该被放到一个方法中，避免用户重复编写一组代码。)

　　在使用API时，是否需要经常参考JavaDoc或者是源代码，才能知道应该调用哪个方法呢?(译注：比较理想的情况就是，大部分操作只需要通过类名和方法的名称就可以明白)。

　　根据名称调用一个方法，但是该方法所做的事并不是用户所想要的。(译注：例如调用一个command方法，以为是执行一个操作，但是结果这个方法是做备份用。)

　　API必须易学：

　　很大程度上，API的易学和易用性是相似的，一般来说，易用也就易学。如果要使API易学，下列基本原则要遵循的：

• 　　API越小就容易学习;
• 　　文档应该有范例;
• 　　如果方便的话，尽可能将API与一些常用的API保持一致。例如如果要做一个资源访问的API，尽可能与J2SE中的IO使用一致，自然很容易学习。

　　(译注：如果你要关闭一个资源，就象Java的File,Connection一样，使用close，而不是destroy。)

　　API的运行速度必须够快：

　　Elliotte也是考虑了很久，才给出这一条。但是要在保证API简单而且正确的前提下，再来考虑API的性能问题。在设计API时，你可能 会先使用一种能够快速实现但是性能不好的方式来实现API，然后再根据实际情况再修改API的实现，以调整性能。至于如何调整性能，绝对不要通过直觉来判 断何种方式能获得高性能。只能通过正确，严格的测试以后，再对性能瓶颈进行优化从而提高性能。(译注：过早的优化是所有的错误根源，这已经是一个普遍认同 的观点，特别是对于Java程序，因为它的JVM越来越快，越来越聪明。)

　　API必须足够的小：

　　这里所说的小不仅是指编译后代码的文件比较小，而且更重要的是运行时占用的内存要小。之所以提出最小化的概念，还有一个原因：就是因为很容易为 API添加新的内容，但是要将一个内容从API中移出就很困难，所以不要随便向API中添加内容，如果不确定一项内容，就不要将它加入到API中。通过这 样一个建议或者说是限制，可以提醒一个API设计人员更加关注API中最重要的功能，而非一些枝节的问题。

　　(译注：许多时候这个最小化原则是很难遵守的，如不变类通常比可变类更好一些，但是它会占用更多的内存，而可变类占用的内存会少些，但要处理线程，并发等问题，所以更多时候是一个权衡，大固然不好，小也必就好)。

　　有一种设计API的方法很常见，但是结果却令人头痛，这种方法就是在设计API前，会详细的考虑每一个用户的需求，并设计出相应的方法，可能在实现中还要设计一堆的Protected方法，这样使得用户可以通过继承来调整默认实现。为什么这种方法不好呢?

　　因为考虑的过于详细，功能边界也就越大，所面对的需求也就越多，因此要提供的功能和可供用户调整的功能也就更加庞大，也就是说这种方法会使得API包含很多的功能，最终就是API膨胀性的增长。

　　事实上API中包含的功能越多，也就更加难以学习和使用，而且其学习难度往往是以几何级数进行增长，而不是线性增长。想像一下，理解并学习使用 10个类，100个方法的API对于一个程序员并不困难，大概一天就可以完成，但是对于一个100个类，1000个方法的API，即使对于一个非常优秀的 程序员，估计10天的时间是不足以完全理解。

　　另外在一个庞大的API中，如何才能尽快的找到最重要的内容，如何找到完成所需功能的方案，一直都是API中设计中的一个难题。

　　JavaDoc工具给用户带来了许多的方便，但一直以来它都没有解决如何学习和使用一个庞大API库的方法。JavaDoc将指定包中的所有类 都放置在一起，并且将一个类中的所有方法放置在一起(译注：这里指的是allclasses-frame.html，index-all.html)，纵 然是天才，看到成千上万的方法和类也只能抱头而泣了。现在看来，只能寄希望于JSR260标准，希望它能够有效地增强JavaDoc工具，从而可以获得 API的完整视图，能够更加宏观地表示API，如果这样，即使是很庞大的API包，也不会显得拥挤，从而也就更加容易理解和使用。

　　另外API越大，出现的错误可能性也就越多，与前面使用的难度一样，错误的数量也是呈几何级数增长而不是线性增长。对于小的API，投入相同的人力进行编码和测试时，可以获得更好的产出。

　　如果设计的API过于庞大，必然会包含了许多不必要的方法，至少有许多public的类和方法，对于大部分用户是用不到，也会占用更多的内存，并降低运行效率。这违反了通常的一个设计原则：“不要让用户为他使用不到的功能付出代价”。

　　正确的解决方案是在现在的例子上来设计API(译注：更象原型演化的方式)。先来想像一下：一个用户要使用API来解决何种问题呢，并为解决这 些问题添加足够的类和方法。然后将与之无关的内容全部移除，这样可以自己来检查这些API的有用性，这种方法还会带来一个有用的附加功能，它可以更加有效 测试代码。同时也可以将这些例子与同伴分享。(译注，这个概念与测试先行是非常相似的)。

Java API设计指南（二）