How to Design a Good API and Why it Matters

近日设计RMI到Infiniband网络的接口,发现如何设计一个好的API是个很有挑战的问题。看了Joshua Bloch的ppt,做了一个总结

API可以成为一个公司很大的资产,因为好的API是可以赢得客户的。而且一旦API被public就很难改变,这也是在Java的包中有很多Deprecated的类和方法,却不能直接被删除。

好的代码应该是模块化的,每个模块都有自己的API;

有用的模块往往是很容易重用的;

对API的设计仔细考虑可以提高代码质量;

好的API的特点:

• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience

 API设计的流程

收集需求-带有一定程度的怀疑
    一个简短的规范,这时不要求完备,但是要敏捷;
    让尽量多的人参与讨论,听取别人的看法
    充实这个规范,一遍coding,一边完善规范
基本规则
    功能应该容易解释,设计好的命名,使得可以很容易地进行模块的划分和合并
    API应该尽量小,但是不能太小;API只能添加不能删除,合理大小的API要比bulk的API要好,所以应该尝试找到好的 功能体积的比率
    实现不能影响API,区分出什么是实现的细节,不要太详细指定方法的行为,一些调优的参数都是应该怀疑的;不要让实现的细节困扰用户,同时也要现在能够改变实现的自由
    使任何事情的可访问度都尽量的小,尽量让class和member是private的,public的类不能有public的field,编译时常量除外;这样可以使信息隐藏达到最大,同时允许模块可以独立地被使用,修改,调试和测试。
    命名;名字要尽量可以自解释;要有一致性,同样的名字意味着同样的东西,包括整个API,甚至API直接都要保持。尽量保持对称,代码看起来如同散文一样
    写好文档。好的API设计和好的文档是实现代码重用的重要技术。
    为每个类、接口、方法、构造函数、参数和异常加注释。类要表明一个实例代表什么;方法要描述清楚方法和客户之间的契约,包括前验条件、后验条件和副作用,参数要指明单位、表单和所有权;仔细的对状态空间写好文档。
    不好的设计会影响性能:尽量多使用不可变对象;使用静态的工厂方法而不使用构造函数;使用接口而不是具体实现的类
    不要歪曲了API来获得好的性能,性能提高了,可能以后会很痛苦,性能应该与设计良好的API保持一致。
    Component.getSize()返回一个可变的Dimension对象,这样每个getSize方法都要分配一个Dimension对象,造成了大量无用的Dimension对象分配。在1.2中引入了新的方案(which?)
    • Do what is customary
 Obey standard naming conventions
 Avoid obsolete parameter and return
 Mimic patterns in core APIs and language
    • Take advantage of API-friendly features
 Generics, varargs, enums, default arguments
    • Know and avoid API traps and pitfalls
 Finalizers, public static final arrays
类设计
    最小化可变类的使用。类应该都是不可变的,除非有足够的理由让他可变,这样实现是简单的、线程安全并可重用
    如果是可变类,就应该严格限制状态空间的大小,并预先定义好。Date和Calender设计的问题和TimerTask的成功经验
    只有在很讲的通的情况下才子类化,因为子类化(继承)意味着可以代换(里氏代换原则),public类不应该为了实现的容易而去继承其他的public类。反面例子Properties、Stack正面例子Set
    如果一定要继承,就要做好设计和文档,否则就不准继承,继承后,子类可以看到超类的实现细节,破坏了封装。保守的观点说,所有的类都应该是final的。正面例子AbstractSet, AbstractMap
方法设计
    不要让客户做模块应该完成的事情
    尽量减少令人惊奇的事情。API使用者不能对API的行为有惊讶,即使减少性能也是可以接受的。
    快速失败的API,应该在发生时尽量快的报告错误。最好能在编译的时候报告错误。在运行时,第一个不好的方法调用是最好的。

    让程序能够对所有可用数据以String的形式可以访问,不然,客户就要对很长的字符串进行解析。
    在重载时要特别留意,多个重载函数不应应用同样的参数,保守派认为尽量不要有同样个数个参数的重载函数
    使用合适的参数和返回类型。使用接口而不是使用类可以提高灵活性和性能;使用最具体的可能输入参数类型,将错误从运行时转移到编译时;如果有其他的类型就不要使用String类型,String很麻烦,容易出错而且很慢(?),不要使用浮点数标识Monetary,会造成差错;使用double而不是float,可以保证精确度。
    在方法中使用一致的参数调用顺序。
    避免使用过长的参数列表,小于等于3个参数是很好的,多了会让用户不得不去参考doc,可以把函数拆小或者将所有的参数放在一个类中,作为参数传递;
    避免返回需要参数处理的值,比如,可以返回长度为0的数组或者collection,而不要返回null。
异常设计
    不要强迫用户使用异常作为控制流的一部分,但是,也不能在fail时不报告异常;要注意用好checked Exception,避免unchecked Exception的过度使用(不可能发生异常的地方不要catch,也不要throw);
    在异常中包含可以用于捕获异常的信息,可以用来诊断、修复或者恢复,对于unchecked Exception可以附加信息,对checked Exception,应该提供访问接口。
重构API设计       

参考资料:How to Design a Good API and Why it Matters, Joshua Bloch

你可能感兴趣的:(exception,generics,String,api,documentation,deprecated)