前谷歌首席Java架构师谈如何设优秀的API

    随着近来软件规模的日益庞大，API 编程接口的设计变的越来越重要。良好的接口设计可以降低系统各部分之间的相互依赖，提高组成单元的内聚性，降低组成单元间的耦合度，从而提高系统的维护性和稳定性。

Joshua Bloch 是美国著名程序式设计师。他为 Java 平台设计并实现了许多的功能，是 Google 的首席 Java 架构师（Chief Java Architect）。他也是《Effective Java Programming Language Guide》一书的作者，就是人们常说的 Effective Java。本文翻译自 Joshua Bloch 所发表的一个 PPT：How to Design a Good API and Why it Matters。

随着大数据、公共平台等互联网技术的日益成熟，API 接口的重要性日益凸显，从公司的角度来看，API 可以算作是公司一笔巨大的资产，公共 API 可以捕获用户、为公司做出许多贡献。对于个人来说，只要你编程，你就是一个 API 设计者，因为好的代码即是模块——每个模块便是一个 API，而好的模块会被多次使用。此外，编写 API 还有利于开发者提高代码质量，提高自身的编码水平。

优秀 API 所具备的特征：

• 简单易学；
• 易于使用，即使没有文档；
• 很难误用；
• 易于阅读，代码易于维护；
• 足够强大，可以满足需求；
• 易于扩展；
• 适合用户。

了解了一款优秀 API 所具备的特征后，一起再来看看如何设计优秀的 API，有哪些流程和规则可循，开发者在设计时需要注意哪些事项。

API 设计流程中的注意事项

征集需求

在开始之前，你可能会收到一些解决方案，它们不一定会比现有的方案好，而你的任务是以用例的形式提取真实需求，并制定真正合适的解决方案，这样构建出来的东西就会更加有价值。

从简短的说明开始

这时，编写简短的说明最为合适，编写时需要考虑的因素有：

• 灵活性要远胜于完整性；
• 跳出规则：听取意见并严阵以待；
• 精炼短小才易修改；
• 获得信任之后将其具体化，在此之中，编程很重要。

尽早编写 API

• 对每一个实现进行保存，以防丢失；
• 在开始之前，列出一些合理的规定，保存所写说明，以防丢失；
• 继续编写和充实 API。

编写 SPI 尤为重要

• Service Provider Interface 即服务提供商接口，插件服务支持多种实现，例如 Java Cryptography Extension (JCE)；
• 发布之前编写多个插件；
• “三次原则”（“The Rule of Threes”）：指的是当某个功能第三次出现时，才进行”抽象化”。

维护切实可行的期望

• 大多数 API 设计都过于约束；
• 对可能会犯的错误进行预计，要用发展的思维来编写 API。

API 设计原则

每个 API 接口应该只专注一件事，并做好：如果它很难命名，那么这或许是个不好的征兆，好的名称可以驱动开发、并且只需拆分与合并模块即可

• API 应尽可能地轻小：满足需求、对有疑问的地方可以暂时不使用（函数、类、方法、参数等，你可以不添加，但千万不要删除）、概念性的东西比体积重要、寻找一个良好的动力体积比；
• 实现不要影响 API：关注实现细节（不要迷惑用户、不要随便改变实现方式）、意识到具体的实现细节（不要有越权的方法行为，例如不要制订哈希函数、所有的调优参数都是可疑的）；
• 不要让实现细节“泄露”到 API（例如 on-disk 和 on-the-wire 格式等异常情况）；
• 最小化可访问：设计人员应尽量把类及成员设为私有，公共类不应该有公共字段（包括异常实例），最大限度地提高信息隐藏，允许模块可以被使用、理解、构建、测试和独立调试；
• 命名问题：应该见名知意，避免含糊的缩写、对同一样东西的命名应该有个一致性的前缀（遍及整个平台 API）、讲究对称、代码应该易读。如下所示：

if (car.speed () > 2 * SPEED_LIMIT)   generateAlert ("Watch out for cops!");

重视文档

开发 API 时要意识到文档的重要性。组件重用不是纸上谈兵的东西，既需要好的设计，也需要优秀的文档，这二者缺一不可，即使我们看到了良好的设计而未见文档，那么组件重用也是不妥的。

——摘自 D. L. Parnas 在 1994 年第 16 届国际软件开发大会上的演讲内容

文档应包含每个类、接口、方法、构造函数、参数和异常，此外，还要小心对待文档的状态空间。

API 设计决策对性能的影响

• API 设计决策对性能的影响是真实永久的；
• 不好的决策会限制性能（类型易变、构造函数替代静态工厂、实现类型替代接口）；
• 不得打包 API 来提升性能（潜在的性能问题可能会得到修复，但救的了一时，救不了一世）；
• 良好的设计通常与好的性能是一致的。

API 与平台和平共处

• 养成良好的习惯：遵守标准的命名约定、避免陈旧的参数和返回类型、核心 API 和语言的模仿模式；
• 利用 API 的友好功能：泛型、可变参数、枚举、默认参数；
• 了解和避免 API 陷阱和缺陷：Finalizers、公共静态 Final 数组。

API 中类的设计

最小化可变性

• 最好不要随便改变类，除非有一个非常合理的理由；
• 如果是可变类，最好保持很小的状态空间、定义良好的结构，因时制宜地去调用方法。

子类只存在有意义的地方

• 子类具备可替代性（Liskov）；
• 公共类不应该继承其它公共类。

用于继承的设计和文档或者直接禁止继承（Design and Document for Inheritance or Else Prohibit it）

• 继承破坏封装
• 如果你允许子类和文档自用，那么要考虑彼此该如何互相调用方法
• 保守策略：把所有类都设置成 Final

API 中的方法设计

模块能做到的，客户端就不要做

减少模板代码的使用：

import org.w3c.dom.*;   import java.io.*;   import javax.xml.transform.*;   import javax.xml.transform.dom.*;   import javax.xml.transform.stream.*;   // DOM code to write an XML document to a specified output stream.   private static final void writeDoc (Document doc, OutputStream out)throws IOException{   try {   Transformer t = TransformerFactory.newInstance () .newTransformer ();   t.setOutputProperty (OutputKeys.DOCTYPE_SYSTEM, doc.getDoctype () .getSystemId ());   t.transform (new DOMSource (doc), new StreamResult (out));   } catch(TransformerException e) {   throw new AssertionError (e); // Can’t happen!   }   }

用户 API 只需根据需求来设计即可，不必让客户感到惊讶，小心弄巧成拙：

public class Thread implements Runnable {   // Tests whether current thread has been interrupted.   // Clears the interrupted status of current thread.   public static boolean interrupted ();   }

故障快速报告应尽快生成

• 编译时最好是静态类型、泛型；
• 方法里应该包含错误自动提交机制。

// A Properties instance maps strings to strings   public class Properties extends Hashtable {   public Object put (Object key, Object value);   // Throws ClassCastException if this properties   // contains any keys or values that are not strings   public void save (OutputStream out, String comments);   }

public class Throwable {   public void printStackTrace (PrintStream s);   public StackTraceElement[] getStackTrace (); // Since 1.4  }  public final class StackTraceElement {   public String getFileName ();   public int getLineNumber ();   public String getClassName ();   public String getMethodName ();   public boolean isNativeMethod ();  }

• 避免模棱两可的重载，例如多个重载适用于同一个实物
• 即使你能分清，也最好不要这样做，最好起个不同的名字
• 如果非要定义这种重载，相同的参数确保相同的行为

public TreeSet (Collection c); // Ignores order  public TreeSet (SortedSet s); // Respects order

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

• 通过类来支持接口类型输入
• 尽可能地使用最特定的输入参数类型
• 如果已经有一个更好的类型存在，就不要使用 string 类型
• 不要用浮点型来修饰货币值
• 使用 Double (64 位)而不要使用 Float (32 位)
• 在方法上参数顺序要一致，尤其是参数类型相同时，则尤为重要

#include <string.h>   char *strcpy (char *dest, char *src);   void bcopy (void *src, void *dst, int n);

java.util.Collections – first parameter always collection to be modified or queried

java.util.concurrent – time always specified as long delay， TimeUnit unit

避免使用长参数列表

• 三个或三个以内的参数是最完美的
• 长参数列表是有害的，程序员容易出错，并且程序在编译、运行时会表现不好
• 缩短参数的两种方法：Break up method、创建参数助手类

最好避免这种情况出现：

// Eleven parameters including four consecutive ints  HWND CreateWindow (LPCTSTR lpClassName, LPCTSTR lpWindowName,   DWORD dwStyle, int x, int y, int nWidth, int nHeight,   HWND hWndParent, HMENU hMenu, HINSTANCE hInstance, LPVOID lpParam);

比如，返回零长度字符串或者空集合

package java.awt.image;   public interface BufferedImageOp {   // Returns the rendering hints for this operation,   // or null if no hints have been set.   public RenderingHints getRenderingHints ();   }

抛出异常来说明异常状况；不要强迫客户端使用异常来控制流。

private byte[] a = new byte[BUF_SIZE];   void processBuffer (ByteBuffer buf) {   try {   while (true) {   buf.get (a);   processBytes (tmp, BUF_SIZE);   }   } catch (BufferUnderflowException e) {   int remaining = buf.remaining ();   buf.get (a, 0, remaining);   processBytes (bufArray, remaining);   }   }

ThreadGroup.enumerate (Thread[] list)

支持 Unchecked Exceptions

• Checked——客户端肯定会做一些恢复措施
• Unchecked——编程错误
• 过度使用 Checked 异常会产生一些模板代码

try {   Foo f = (Foo) super.clone ();   ....  } catch (CloneNotSupportedException e) {   // This can't happen, since we’re Cloneable   throw new AssertionError ();  }

异常中应该包含捕获错误的（Failure-Capture）信息

• 允许诊断和修复或恢复
• 对于 Unchecked 异常，有异常消息就行了
• 对于 Checked 异常，提供访问器

重构 API 设计

在 Vector 中进行 Sublist 操作

 public class Vector {   public int indexOf (Object elem, int index);   public int lastIndexOf (Object elem, int index);   ...  } 

public interface List {   List subList (int fromIndex, int toIndex);   ...  }

 // Broken - inappropriate use of String as capability.   // Keys constitute a shared global namespace.   public class ThreadLocal {   private ThreadLocal () { } // Non-instantiable   // Sets current thread’s value for named variable.   public static void set (String key, Object value);   // Returns current thread’s value for named variable.   public static Object get (String key);   }

 public class ThreadLocal {   private ThreadLocal () { } // Noninstantiable   public static class Key { Key () { } }   // Generates a unique, unforgeable key   public static Key getKey () { return new Key (); }   public static void set (Key key, Object value);   public static Object get (Key key);   }

static ThreadLocal.Key serialNumberKey = ThreadLocal.getKey ();   ThreadLocal.set (serialNumberKey, nextSerialNumber ());   System.out.println (ThreadLocal.get (serialNumberKey));

public class ThreadLocal {   public ThreadLocal () { }   public void set (Object value);   public Object get ();   }

static ThreadLocal serialNumber = new ThreadLocal ();   serialNumber.set (nextSerialNumber ());   System.out.println (serialNumber.get ());