Java API 设计清单

原文地址:http://theamiableapi.com/2012/01/16/java-api-design-checklist/

 

 

在设计Java API的时候总是有很多不同的规范和考量。与任何复杂的事物一样,这项工作往往就是在考验我们思考的缜密程度。就像飞行员起飞前的检查清单,这张清单将帮助软件设计者在设计Java API的过程中回忆起那些明确的或者不明确的规范。本文也可以看作为“API设计指南”这篇文章的附录。

我们还准备了一些前后比对的例子来展示这个列表如何帮助你理清设计需求,找出错误,识别糟糕的设计实践以及如何寻找改进的时机。

这个清单使用了如下的语言规范:

要 – 表示必要的设计

建议 – 表示在几个最好的设计中选择一个

考虑 – 表示一个可能的设计上的改进

避免 – 表示一个设计上的缺陷

不要 – 表示一个设计上的错误

1. 包设计清单

1.1. 共通

  • 1.1.1.    建议把API和实现放入不同的包
  • 1.1.2.    建议把API放进上层包,而把实现放进下层包
  • 1.1.3.    考虑把一组大型的API分拆进不同的包
  • 1.1.4.    考虑把API和实现打包进不同的jar包
  • 1.1.5.    避免API的实现类之间的内部依赖
  • 1.1.6.    避免把API分拆了太细
  • 1.1.7.    避免把公共实现类放到API的包中
  • 1.1.8.    不要在调用者和实现类之间建立依赖
  • 1.1.9.    不要把没有关系的API放进同一个包
  • 1.1.10.  不要把API和SPI(service provider interface)放进一个包(注:两者不同可以查看这个页面http://stackoverflow.com/questions/2954372/difference-between-spi-and-api )
  • 1.1.11.  不要