【译】如何设计一个好的API

好的API，应该是易于学习、易于使用即使没有文档、很难被误用、易于阅读并且使用它的代码容易维护、足够强大来满足需求、易于扩展。

 

API设计流程

 

收集需求-》一个简单的设计说明-》尽早和经常写API-》写服务提供接口比较重要-》维护现实需求

1.一般原则

 

• API应该只做一件事，并且把它做好

功能应该很容易解释，如果很难命名，一般都是一个坏的信号。一个好的名字驱动开发。容易切分和合并模块。

 

 

• API应该设计的尽可能的小，但是也不要太过于小

API应该满足它的需求

• 实现不应该影响API
• 保持最小的可访问性

使类和成员变量尽可能的私有化。公共类不应该有公共字段。最大化信息隐藏。允许模块被独立的使用、理解、构建、测试及调试。

• 命名问题-API是一门小语言

名字应该尽可能的自解释。保持连续性-同一个单词保持同一个含义。尽可能的保持对称。代码应该读起来像散文。

• 虔诚的书写文档

对每一个类、接口、方法、构造方法、参数和异常书写注释文档。

 

• 考虑API设计的性能

坏的设计会时性能变差。以下几种都是不好的实践：使类型容易变化、提供构造方法而不是静态工厂、使用实现而不是接口。 Do not warp API to gain performance（不太理解这句话）

• API必须在任何平台都可用，保持同样的行为功能。

2.类设计

• 最小化可变性

好的设计范例：TimerTask;坏的设计范例：Date Calendar;

• 为继承进行设计并且书写文档，否则禁止继承

继承违反了封装。保守策略：所有的具体类都定义为final的。

坏的设计范例：J2SE库中很多具体的类；好的设计范例：AbstractSet,AbstractMap

3.方法设计

• 使用合适的参数和返回类型

对于输入，参数优先使用接口而不是类（提供灵活性和性能的好处）；

使用尽可能具体的输入参数类型，为的是尽早发现错误。（从运行时转移到编译时）；

如果存在更好的类型，就不要使用String。String笨重、易于出错、缓慢。

不要使用浮点类型在货币值上，因为会导致不精确的结果。

使用double（64bits），不适用float（32bits）。可以提高精度。

• 在方法中使用一致的参数顺序

java.util.Collections-第一个参数经常是被修改或者查询的collection。

java.util.concurrent-时间一般会被定义为 long delay,TimeUnit unit。

• 避免长参数列表

理想情况是三个或者更少。相同类型的长参数列表是有害的，编程人员容易错误的传递参数。有两种技术可以减少参数列表长度：分解方法，创建辅助类来保存方法。

• 返回零长度的数组或者空集合类，而不是null

4.异常设计

• 抛出异常表明异常发生的条件

不要强迫客户端使用异常来控制条件流向，不要安静的失败。

• 非受检异常优先

受检异常-客户端必须采取恢复动作，非受检异常-程序错误。

• 异常中包含错误捕获信息。

5.重构API设计