Google首席软件工程师Joshua Bloch谈如何设计一款优秀的API

jc213 贡献于2014-03-12

作者 guopeng  创建于2014-03-07 03:47:00   修改者guopeng  修改于2014-03-07 07:00:00字数6395

文档摘要:Google首席软件工程师Joshua Bloch谈:如何设计一款优秀的API随着大数据、公共平台等互联网技术的日益成熟,API接口的重要性日益凸显,从公司的角度来看,API可以算作是公司一笔巨大的资产,公共API可以捕获用户、为公司做出许多贡献。对于个人来说,只要你编程,你就是一个API设计者,因为好的代码即是模块——每个模块便是一个API,而好的模块会被多次使用。此外,编写API还有利于开发者提高代码质量,提高自身的编码水平。优秀API所具备的特征简单易学;易于使用,即使没有文档;很难误用;易于阅读,代码易于维护;足够强大,可以满足需求;
关键词:

Google首席软件工程师Joshua Bloch 谈:如何设计一款优秀的API 随着大数据、公共平台等互联网技术的日益成熟,API接口的重要性日益凸显,从公司的角度来看,API可以算作是公司一笔巨大的资产,公共API可以捕获用户、为公司做出许多贡献。对于个人来说,只要你编程,你就是一个API设计者,因为好的代码即是模块——每个模块便是一个API,而好的模块会被多次使用。此外,编写API还有利于开发者提高代码质量,提高自身的编码水平。 优秀API所具备的特征 l 简单易学; l 易于使用,即使没有文档; l 很难误用; l 易于阅读,代码易于维护; l 足够强大,可以满足需求; l 易于扩展; l 适合用户。 了解了一款优秀API所具备的特征后,一起再来看看如何设计优秀的API,有哪些流程和规则可循,开发者在设计时需要注意哪些事项。 API设计流程中的注意事项 征集需求  在开始之前,你可能会收到一些解决方案,它们不一定会比现有的方案好,而你的任务是以用例的形式提取真实需求,并制定真正合适的解决方案,这样构建出来的东西就会更加有价值。 从简短的说明开始 这时,编写简短的说明最为合适,编写时需要考虑的因素有: l 灵活性要远胜于完整性; l 跳出规则:听取意见并严阵以待; l 精炼短小才易修改; l 获得信任之后将其具体化,在此之中,编程很重要。 尽早编写API l 对每一个实现进行保存,以防丢失; l 在开始之前,列出一些合理的规定,保存所写说明,以防丢失; l 继续编写和充实API。 编写SPI尤为重要 l Service Provider Interface即服务提供商接口,插件服务支持多种实现,例如Java Cryptography Extension (JCE); l 发布之前编写多个插件; l “三次原则”(“The Rule of Threes”):指的是当某个功能第三次出现时,才进行"抽象化"。 维护切实可行的期望 l 大多数API设计都过于约束; l 对可能会犯的错误进行预计,要用发展的思维来编写API。 API设计原则 每个API接口应该只专注一件事,并做好:如果它很难命名,那么这或许是个不好的征兆,好的名称可以驱动开发、并且只需拆分与合并模块即可; l API应尽可能地轻小:满足需求、对有疑问的地方可以暂时不使用(函数、类、方法、参数等,你可以不添加,但千万不要删除)、概念性的东西比体积重要、寻找一个良好的动力体积比; l 实现不要影响API:关注实现细节(不要迷惑用户、不要随便改变实现方式)、意识到具体的实现细节(不要有越权的方法行为,例如不要制订哈希函数、所有的调优参数都是可疑的); l 不要让实现细节“泄露”到API(例如on-disk和on-the-wire格式等异常情况); l 最小化可访问:设计人员应尽量把类及成员设为私有,公共类不应该有公共字段(包括异常实例),最大限度地提高信息隐藏,允许模块可以被使用、理解、构建、测试和独立调试; l 命名问题:应该见名知意,避免含糊的缩写、对同一样东西的命名应该有个一致性的前缀(遍及整个平台API)、讲究对称、代码应该易读。如下所示: if (car.speed() > 2 * SPEED_LIMIT)    generateAlert("Watch out for cops!");   重视文档 开发API时要意识到文档的重要性。组件重用不是纸上谈兵的东西,既需要好的设计,也需要优秀的文档,这二者缺一不可,即使我们看到了良好的设计而未见文档,那么组件重用也是不妥的。 ——摘自 D. L. Parnas 在1994年第16届国际软件开发大会上的演讲内容 文档应包含每个类、接口、方法、构造函数、参数和异常,此外,还要小心对待文档的状态空间。 API设计决策对性能的影响 l API设计决策对性能的影响是真实永久的; l 不好的决策会限制性能(类型易变、构造函数替代静态工厂、实现类型替代接口); l 不得打包API来提升性能(潜在的性能问题可能会得到修复,但救的了一时,救不了一世); l 良好的设计通常与好的性能是一致的。 API与平台和平共处 l 养成良好的习惯:遵守标准的命名约定、避免陈旧的参数和返回类型、核心API和语言的模仿模式; l 利用API的友好功能:泛型、可变参数、枚举、默认参数; l 了解和避免API陷阱和缺陷:Finalizers、公共静态Final数组。 API中类的设计 最小化可变性 l 最好不要随便改变类,除非有一个非常合理的理由; l 如果是可变类,最好保持很小的状态空间、定义良好的结构,因时制宜地去调用方法。 子类只存在有意义的地方 l 子类具备可替代性(Liskov); l 公共类不应该继承其它公共类。 用于继承的设计和文档或者直接禁止继承(Design and Document for Inheritance or Else Prohibit it) l 继承破坏封装 l 如果你允许子类和文档自用,那么要考虑彼此该如何互相调用方法 l 保守策略:把所有类都设置成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();    }   故障快速报告应尽快生成 l 编译时最好是静态类型、泛型; l 方法里应该包含错误自动提交机制。 // 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);    }   以String形式对所有可用数据提供编程式访问 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();   }   方法重载要细心 l 避免模棱两可的重载,例如多个重载适用于同一个实物 l 即使你能分清,也最好不要这样做,最好起个不同的名字 l 如果非要定义这种重载,相同的参数确保相同的行为 public TreeSet(Collection c); // Ignores order   public TreeSet(SortedSet s); // Respects order   使用合适的参数和返回类型 l 通过类来支持接口类型输入 l 尽可能地使用最特定的输入参数类型 l 如果已经有一个更好的类型存在,就不要使用string类型 l 不要用浮点型来修饰货币值 l 使用Double(64位)而不要使用Float(32位) l 在方法上参数顺序要一致,尤其是参数类型相同时,则尤为重要  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 避免使用长参数列表 l 三个或三个以内的参数是最完美的 l 长参数列表是有害的,程序员容易出错,并且程序在编译、运行时会表现不好 l 缩短参数的两种方法: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();    }   API中的异常设计 抛出异常来说明异常状况;不要强迫客户端使用异常来控制流。 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);    }    }   Conversely, don’t fail silently  ThreadGroup.enumerate(Thread[] list)   支持Unchecked Exceptions l Checked——客户端肯定会做一些恢复措施 l Unchecked——编程错误 l 过度使用Checked异常会产生一些模板代码 try {    Foo f = (Foo) super.clone();    ....   } catch (CloneNotSupportedException e) {    // This can't happen, since we’re Cloneable    throw new AssertionError();   }   异常中应该包含捕获错误的(Failure-Capture)信息 l 允许诊断和修复或恢复 l 对于Unchecked异常,有异常消息就行了 l 对于Checked异常,提供访问器 重构API设计 在Vector中进行Sublist操作  public class Vector {    public int indexOf(Object elem, int index);    public int lastIndexOf(Object elem, int index);    ...   }   分析: l 在搜索上不强大 l 没有文档很难使用 重构Sublist操作  public interface List {    List subList(int fromIndex, int toIndex);    ...   }   分析: l 非常强大——支持所有操作 l 使用接口来减少概念权重:较高的动力重量(power-to-weight)比 l 没有文档也易于使用 线程局部变量  // 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);   }   线程局部变量重构1 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));   线程局部变量重构2 public class ThreadLocal {    public ThreadLocal() { }    public void set(Object value);    public Object get();    }   从API和客户端代码中删除了无用代码。  static ThreadLocal serialNumber = new ThreadLocal();    serialNumber.set(nextSerialNumber());    System.out.println(serialNumber.get());   总结 API设计是一件非常高端大气上档次的工艺,对程序员、终端用户和公司都会有所提升。不要盲目地去遵守文中所提及的规则、说明等,但也不要去侵犯他们,API设计不是件简单的工艺,也不是一种可以孤立行动的活。当然完美永远无法实现,但我们要努力去追求完美。

下载文档到电脑,查找使用更方便

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 5 金币 [ 分享文档获得金币 ] 0 人已下载

下载文档