《Java+API+设计指南》.pdf

JavaAPI设计指南 作者： EamonnMcManus 原文地址： /weblogs/viewpost.jsp?thread=142428 译者： 王磊 电子邮件： wl_95421@ （该译文可以随便转载，但请保留前面的声明，谢谢） 前言： 市场上关于如何设计和编写优秀Java 代码的书如此之多，可能要用汗牛充椟来形容， 但是想找到一本如何设计API的书，却是难之又难。这里我将把自己一些关于API设计的 经验与大家分享。 分享这些经验是源于最近我参加了JavaPolis上的一个讨论，这个讨论是由Elliotte Rusty Harold发起的，是关于设计XOM时的一些原则性问题，讨论中的思想交流如此精采，令我 受益颇多。虽然这次讨论主题是与XOM有关，但是大部分的时间我们都在讨论设计XOM API时的一些原则性问题，而这些内容对于API设计而言，则是通用的。这几年，Java的应 用日益广泛，开源项目也是蒸蒸日上。一本能够指导开发人员设计和编写 API的好书，可 以帮助开发人员设计和编写更好的API。 在过去的五年中，我一直参与JMX API的修订及调整，在此过程中，同样受益颇多。 特别在这次讨论会，我对Elliotte 提出的一些观点高举双手赞同。 接下来的内容是讨论会上的一些主要观点的总结，其中包括一些个人或者是来自他人的 经验，也参考一些相关的文档，希望对大家设计API有所裨益。 下面是个人推荐的一些阅读和参考资料。 下面给出的网址是Netbeans网站上的一篇关于API设计的优秀文档， /tutorial/api­design.html JoshBlochs 的EffectiveJava作为Java设计的圣经之一，从来都不会被漏下。 设计需要进化 API的价值就在于能够帮助你完成许多功能，但请不要忘记要持续的改善它，否则它的 价值就会逐渐减少。而且要根据用户的反馈信息，来改善API，或者说是对API进行演化， 另外改进API时要注意的就是在不同版本间要保持兼容性，这点至关重要，它也是一个API 是否成功的重要标识之一。 如果一个功能以API 的方式公布出来，那么在发布以后，它的对外接口就已经固定， 无论什么情况，都不能取消，而且一定要能够按照原有的约定功能正确执行。如果 API不 能在版本间保持兼容性（译注：这里应该指的是向下兼容），用户将会难以接受这样一个千 变万化的API，最终的结果只能是让用户放弃使用你的API。如果你的API被大量的软件或 者模块所使用，又或者被大型软件使用，这个兼容问题也就愈加严重。 以一个Java 应用程序为例，如果Module1使用了Banana1.0的API，而Module2则使 用了Banana2.0的API，现在要同时部署这两个模块到一个WebApplication上，如果Banana2.0 对Banana1.0保持兼容的话，整个部署就会非常简单，直接使用Banana2.0就可以了。如果 Banana2.0和Banana1.0不兼容的话，就很难同时在一个程序中同时使用Module1和Module2 （可能要自定义ClassLoader，或者是其它方式，这对于用户未免有些为难了）。最终的结果 可能就是你失去一个用户，这时的API就不能为他人提供任何价值（译注：看来它也不能 带来经济价值了）。 分析JavaSE平台所提供的API，有着严格的兼容性控制。其根本目标就在于保证用户 在版本升级时，不会导致低版本的代码无法运行。这也再次说明，当一个API 发布以后， 任何API公开的方法，常量等元素都不能被移出API，否则会严重降低API的价值。（译注： 所以个人一向比较怀疑deprecated的价值，因为既然所有的方法都不会被删除，即使那些被 deprecasted的方法和变量也会被仍然保留，其功能也不应该会被改变，因此从这个角度来说， 其方法和变量的使用仍然是安全的。） 说到兼容性，必然要谈到二进制兼容性，这是指对于已经编译完成的代码，不会因为版 本的变更，而致使编译后的代码不能正常运行。比如说你将一个public方法从API中移走， 就会无法正常运行，会抛出NoSuchMethodException这类错误。 但源代码的兼容性也不可忽视，在某些特殊情况下，修改 API时，会产生源代码兼容 问题，导致源代码无法编译通过。例如添加一个重载的同名方法，其参数不同，如 getName(User