#### 1.为什么要设计API 什么是API呢？API的全称是：应用程序编程接口（Application Programming Interface），既然是接口，必然要涉及到至少两个方面：使用方、提供方。 有人的地方就有沟通，有程序的地方就有互相调用。如果说语言是人与人之间沟通的桥梁，那么API则是程序间调用的“桥梁”。 规模越大的程序中，API数量就会越多，API的质量高低决定了程序的可读性、易用性。设计一套（或多套）优秀的API能为整体带来良好的代码阅读体验以及高效的开发效率，同时这也应该是一个优秀程序员的必备条件。 ### 2.如何评价API的好坏 我们来简单的看下如何评价一个API的好与不好。 #### 2.1 名称及参数 方法名称是否可以自描述，即看到方法的名字就能知道方法的作用、看到参数名就知道需要传递什么样的数据（比如getUserById(String userId)）。 #### 2.2 协议及行为 API会涉及到协议吗？答案是肯定的。一个方法的输入、输出就是协议，什么样的输入是合法的、什么样的输入是非法的，针对合法的输入在处理后返回什么样的结果、针对非法的输入返回什么样的提示以便能快速知道问题的症结所在。 同时协议也要保证在不同版本间的兼容，新版本要兼容老版本，保证之前的调用方不会因为API的内部修改而不能得到正确的结果。 所谓行为就是API内部实现逻辑，有些时候，虽然我们提供给用户的是API，但是内部逻辑也在用户的可见范围内，这时候用户会查看内部实现并根据API内部实现编写自己的代码，因此内部行为的稳定同样很重要。 #### 2.3 可理解及一致性 API一定要便于使用者理解，这样才是广泛传播的基础。如果有些API需要用户掌握特定的概念、定义，那么就要保持这个API的一致性，不能轻易的改变API，否则会给使用者带来很大的麻烦。 ### 3. API设计的一些原则 #### 3.1 只公开必须的内容 在编写API时，肯定会有这样一种思考方式：是不是要多加一个参数呢？可能会有这种用法吧？参数要不要做到很灵活呢？接收一个Object数组吧（而且是不带泛型的）。。。有这样的想法能说明我们在设计API的时候思考了很多，那么我们应该怎么做呢？精简、明确、直接。只公开必要的内容，不要为了“以后可能会有”而大伤脑筋，考虑未来的扩展固然是好事，但过犹不及凡事总要有个度。 #### 3.2 面向接口编程 面向接口编程，在一些面向对象语言中提及的比较多（比如java）。面向接口编程，就是在参数的传递和返回使用接口而不是实现类，这样可以方便的替换实现方，从而达到程序容易扩展、实现更加灵活的目的。 比如我们在设计一个API的时候，传入参数使用接口Map就会比使用具体的类如HashMap、TreeMap更加灵活。比如JDBC，我们使用的都是Connection、ResultSet这样的一些接口，具体的实现则由数据库厂商提供，MySql、Oracle等厂商都提供了JDBC的实现。 #### 3.3 方法重载 方法重载在很多API、SDK中有着广泛的使用，之所有使用重载是因为它为程序实现带来了极大的便利。一个明显的例子是：在不同的地方做相同或类似的事情，重载这种方式的优越性就凸显出来了。我们看下面的例子： 在JDK的java.util包下的Collections类有两个个排序的静态方法： ~~~ sort(List<T> list)； sort(List<T> list, Comparator<? super T> c); ~~~ 同样的方法名不会让人疑惑，参数的丰富让人一眼就能看到重载方法的区别以及自己该调用哪个。 #### 3.4 返回值 当API具有返回值时，应该在一组（或同一种类）的API中使用同样规则的返回值。 下面提供一种参考方式：如返回的结果是单个对象，当没有找到符合条件的结果时，应返回null；如果返回值是List、Map或数组，那么应该返回空的Lisp、Map、数组，而不是null。 上面的方式不一定是适合所有场景的，也可以使用另外的一种通用规则替代，比如当查询不到符合条件的数据时抛出异常，这也是一种通用的方式，具体使用哪种，根据实际情况而定。 * * * * * 作者： moocer 链接：http://www.imooc.com/article/15611 来源：慕课网 本文原创发布于慕课网 ，转载请注明出处，谢谢合作！