Java API设计指南2

就象业界游行的经验之谈--“不要使用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的设计原则是很通用的，如尽量使用接口的方式来表达所有的API(不要使用类来描述API)。接口自有它的价值，但是将所有的API都通过接口来表示并不见得总是一个好的设计方案。在使用一个接口来描述API时，必须有一个足够的理由。下面给出了一些理由：

　　1、接口可以被任何人所实现。假设String是一个接口而非类，永远都无法确认用户提供的String实现能够遵循你希望的规则：字符串类是一个不变量;它的hashCode是按照一定的算法规则来返回数字;而length永远都不会是一个负数等。如果真的由用户来提供一个String的实现，可以想象代码中要加入多少异常处理代码和相关的判断语句才能保证程序的健壮性。

　　实践告诉我们，如果API完全是由接口来定义，用户在使用这些API时会发现不得不进行大量的强制转型(译注：个人认为，强制转型并不是因为API是通过接口来定义引起的，而是不好的API定义引起的，而且强制转型从程序的设计角度几乎是无法避免的，除非所有的子类都不添加任何新的功能，而这一点与前面的抽象类演化又是矛盾的)。

　　2、接口不可能拥有构造函数或者是static方法。如果需要接口的实例，不可能直接实例化接口，只能通过某种方式，可能是new也可能是通过参数传递的方式来获得一个接口的具体实现对象。当然，这个对象可能是由你来实现的，也可能是由第三方供应商开发的。如果Integer是一个接口而非一个类，则无法通过new Integer(int)来构造一个Integer对象，可能会通过一个IntegerFactory.newInteger(int)来获得一个Integer对象实例，天啊，API变得更加复杂和难以理解了。

　　(译注：个人认为原文作者有些过于极端化了，因为Java不是一个纯粹的API，它同时是一种语言，一个平台，所以提供的String和Integer，都是作为基础类型来提供。虽然同意作者的观点，但是作者使用的上述例子，个人认为不是很有说服力。)

　　3、接口无法进行演化。假设在2.0版本的API中为一个接口添加一个方法，多米诺骨牌倒了，大量直接实现了这个接口的类，根本就无法通过编译，直到实现了这个方法为止。 当然可以在调用这个新方法的时候，通过捕捉AbstractMethodError这个异常来保证二进制的兼容性，但是如此笨重的方法，实在不是智者所为。除非告诉用户说千万不要直接实现这个接口，请先继承所提供的那个抽象类，这样做就不会有问题了，不过用户会尖锐的责问：那为什么要提供这样一个接口，不如直接提供一个抽象类算了。

　　4、接口是不可以被序列化的，虽然Java的序列化存在许多问题，但是仍然不可避免的要用到它。象JMX的API就严重依赖于序列化接口。序列化是针对序列化接口的子类来处理的，当一个可序列化的对象被反序列化时，就有会一个相同的新对象被重新创建出来。如果这个子类没有提供一个public构造函数，那么可能很难在程序中使用这个功能，因为只能反序列化而不能进行序列化。而且在反序列化时，只能使用接口进行强制转型。如果要序列化的内容是一个类，那就不需要提供这样的序列化接口。

　　当然，对于下列情况，接口还是非常有用的：

　　1、回调：如果功能完全由用户来实现，在这种情况下，接口显然比抽象类更加合适。例如Runnable接口。特别是那些通常只含有一个方法的，往往是接口，而非类(译注：最常用的就是各种Listener)。如果一个接口中包含有大量的抽象方法，用户在实现这个接口的时候，就不得不必须实现一些空方法。所以对于有多个方法的接口，建议提供一个抽象类，这样在接口中添加新的方法，而不需要强迫用户实现新的方法。(译注：看来作者很推荐使用接口+基类的方式来编写API，不过Java SE本身就是这样做的，例如MouseAdapter,KeyAdapter等。个人认为，如果是规范，当然最好是接口，象J2EE规范;如果是框架，或者是功能包，还是建议使用接口+基类的方式。所谓的回调其实是SPI(Service Provider Interface)的一种)。

　　2、多重继承：在一个继承体系比较深的结构里，可以通过接口来实现多重继承。Comparable是一个最好的例子，比如Integer实现了Comparable接口，因为Integer的父类是Number，所以通过接口的方式实现了多重继承。但是在Java的核心类库中，这样的经典例子并不多。通常一个类实现了多个接口并不一定是一个好的设计，因为这往往将许多责任强加在一个类上，有违基本的设计原则，而且很容易产生重复代码。如果真的需要这样一个功能，使用一个匿名类或者是一个内部类来实现这些接口，或者使用一个抽象类作为基类也是不错的方案。

　　3、动态代理：价值不可估量的动态代理类java.lang.reflect.Proxy class 可以在运行的时候根据接口生成实现的内容。它将对一个接口的调用转换成对某一个对象具体方法的调用，非常的灵活，可以有效的减少代码重复。但是对于一个抽象类，就不可能动态生成一个代理对象了。如果喜欢使用动态代理技术，那么使用接口对软件开发是非常有效的。(CGLIB有时可以有效地对抽象类实现动态代理，但是有许多限制，而且其文档也较少。)