国内最全IT社区平台 联系我们 | 收藏本站
华晨云阿里云优惠2
您当前位置：首页 > 互联网 > Google首席软件工程师Joshua Bloch谈如何设计一款优秀的API【附PPT】

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

来源：程序员人生   发布时间：2014-09-07 02:29:28 阅读次数：2090次

【编者按】随着近来软件规模的日益庞大，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中类的设计

最小化可变性

子类只存在有意义的地方

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

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);
 }以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();
}方法重载要细心

    

    

    
    

    
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      

 生活不易，码农辛苦

 如果您觉得本网站对您的学习有所帮助,可以手机扫描二维码进行捐赠

  程序员人生


     
     
          
 

            ------分隔线----------------------------

    


      

        
上一篇 小米4发布会：少了“性价”，多了“工艺” 

        
下一篇 Java自学资料――线程  

      

      

        
分享到:

       


      

    

 

            ------分隔线----------------------------

  
   




	



  
  
  

   
   
  

    

     
为码而活

     

      
为码而活

      
积分：4237

     

    
 
    

                     
                  

    

	
15粉丝

	
7关注

   

  

             



        
栏目热点

   

   

        
      

   

 

  












 
程序员人生，我编程，我富裕，记住wfuyu网，php教程，php学习，php手册，CMS模版制作

  
声明：本站大部分内容是作者原创，少部分收集于互联网供大家一起学习，原版权很多不明，如有侵权请联系本站，谢谢！



  粤ICP备14040726号-1  
  2015-2020 程序员人生 版权所有  
 
  

     平平安安   备案网站   
 

 







    
关闭

    程序员人生