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

优秀API所具备的特征

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

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

API设计流程中的注意事项

征集需求

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

从简短的说明开始

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

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

尽早编写API

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

编写SPI尤为重要

ServiceProviderInterface即服务提供商接口，插件服务支持多种实现，例如JavaCryptographyExtension(JCE)；
发布之前编写多个插件；
“三次原则”（“TheRuleofThrees”）：指的是当某个功能第三次出现时，才进行"抽象化"。

维护切实可行的期望

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

API设计原则

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

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

[java]
viewplaincopyprint?

if(car.speed()>2*SPEED_LIMIT)
generateAlert("Watchoutforcops!");

重视文档

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

——摘自D.L.Parnas在1994年第16届国际软件开发大会上的演讲内容
文档应包含每个类、接口、方法、构造函数、参数和异常，此外，还要小心对待文档的状态空间。

API设计决策对性能的影响

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

API与平台和平共处

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

API中类的设计

最小化可变性

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

子类只存在有意义的地方

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

用于继承的设计和文档或者直接禁止继承（DesignandDocumentforInheritanceorElseProhibitit）

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

API中的方法设计

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

减少模板代码的使用：

[java]
viewplaincopyprint?

importorg.w3c.dom.*;
importjava.io.*;
importjavax.xml.transform.*;
importjavax.xml.transform.dom.*;
importjavax.xml.transform.stream.*;
//DOMcodetowriteanXMLdocumenttoaspecifiedoutputstream.
privatestaticfinalvoidwriteDoc(Documentdoc,OutputStreamout)throwsIOException{
try{
Transformert=TransformerFactory.newInstance().newTransformer();
t.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,doc.getDoctype().getSystemId());
t.transform(newDOMSource(doc),newStreamResult(out));
}catch(TransformerExceptione){
thrownewAssertionError(e);//Can’thappen!
}
}

遵守最小惊讶原则

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

[java]
viewplaincopyprint?

publicclassThreadimplementsRunnable{
//Testswhethercurrentthreadhasbeeninterrupted.
//Clearstheinterruptedstatusofcurrentthread.
publicstaticbooleaninterrupted();
}

故障快速报告应尽快生成

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

//APropertiesinstancemapsstringstostrings
publicclassPropertiesextendsHashtable{
publicObjectput(Objectkey,Objectvalue);
//ThrowsClassCastExceptionifthisproperties
//containsanykeysorvaluesthatarenotstrings
publicvoidsave(OutputStreamout,Stringcomments);
}

以String形式对所有可用数据提供编程式访问

[java]
viewplaincopyprint?

publicclassThrowable{
publicvoidprintStackTrace(PrintStreams);
publicStackTraceElement[]getStackTrace();//Since1.4
}
publicfinalclassStackTraceElement{
publicStringgetFileName();
publicintgetLineNumber();
publicStringgetClassName();
publicStringgetMethodName();
publicbooleanisNativeMethod();
}

方法重载要细心

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

[java]
viewplaincopyprint?

publicTreeSet(Collectionc);//Ignoresorder
publicTreeSet(SortedSets);//Respectsorder

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

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

[cpp]
viewplaincopyprint?





#include<string.h>
char*strcpy(char*dest,char*src);
voidbcopy(void*src,void*dst,intn);

避免使用长参数列表

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

最好避免这种情况出现：

[java]
viewplaincopyprint?

HWNDCreateWindow(LPCTSTRlpClassName,LPCTSTRlpWindowName,
DWORDdwStyle,intx,inty,intnWidth,intnHeight,
HWNDhWndParent,HMENUhMenu,HINSTANCEhInstance,LPVOIDlpParam);

返回值勿需进行异常处理

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

[java]
viewplaincopyprint?

packagejava.awt.image;
publicinterfaceBufferedImageOp{
//Returnstherenderinghintsforthisoperation,
//ornullifnohintshavebeenset.
publicRenderingHintsgetRenderingHints();
}

API中的异常设计

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

[java]
viewplaincopyprint?





privatebyte[]a=newbyte[BUF_SIZE];
voidprocessBuffer(ByteBufferbuf){
try{
while(true){
buf.get(a);
processBytes(tmp,BUF_SIZE);
}
}catch(BufferUnderflowExceptione){
intremaining=buf.remaining();
buf.get(a,0,remaining);
processBytes(bufArray,remaining);
}
}

[java]
viewplaincopyprint?





ThreadGroup.enumerate(Thread[]list)

ThreadGroup.enumerate(Thread[]list)

支持UncheckedExceptions

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

[java]
viewplaincopyprint?

try{
Foof=(Foo)super.clone();
....
}catch(CloneNotSupportedExceptione){
//Thiscan'thappen,sincewe’reCloneable
thrownewAssertionError();
}

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

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

重构API设计

在Vector中进行Sublist操作

[java]
viewplaincopyprint?

publicclassVector{
publicintindexOf(Objectelem,intindex);
publicintlastIndexOf(Objectelem,intindex);
...
}

分析：

在搜索上不强大
没有文档很难使用

重构Sublist操作

[java]
viewplaincopyprint?

publicinterfaceList{
ListsubList(intfromIndex,inttoIndex);
...
}

分析：

非常强大——支持所有操作
使用接口来减少概念权重：较高的动力重量（power-to-weight）比
没有文档也易于使用

线程局部变量

[java]
viewplaincopyprint?





//Broken-inappropriateuseofStringascapability.
//Keysconstituteasharedglobalnamespace.
publicclassThreadLocal{
privateThreadLocal(){}//Non-instantiable
//Setscurrentthread’svaluefornamedvariable.
publicstaticvoidset(Stringkey,Objectvalue);
//Returnscurrentthread’svaluefornamedvariable.
publicstaticObjectget(Stringkey);
}

线程局部变量重构1

[java]
viewplaincopyprint?





publicclassThreadLocal{
privateThreadLocal(){}//Noninstantiable
publicstaticclassKey{Key(){}}
//Generatesaunique,unforgeablekey

publicstaticKeygetKey(){returnnewKey();}
publicstaticvoidset(Keykey,Objectvalue);
publicstaticObjectget(Keykey);
}

可以运行，但是需要使用模板代码。

[java]
viewplaincopyprint?





staticThreadLocal.KeyserialNumberKey=ThreadLocal.getKey();
ThreadLocal.set(serialNumberKey,nextSerialNumber());
System.out.println(ThreadLocal.get(serialNumberKey));

线程局部变量重构2

[java]
viewplaincopyprint?





publicclassThreadLocal{
publicThreadLocal(){}
publicvoidset(Objectvalue);
publicObjectget();
}

从API和客户端代码中删除了无用代码。

[java]
viewplaincopyprint?





staticThreadLocalserialNumber=newThreadLocal();
serialNumber.set(nextSerialNumber());
System.out.println(serialNumber.get());

总结

API设计是一件非常高端大气上档次的工艺，对程序员、终端用户和公司都会有所提升。不要盲目地去遵守文中所提及的规则、说明等，但也不要去侵犯他们，API设计不是件简单的工艺，也不是一种可以孤立行动的活。当然完美永远无法实现，但我们要努力去追求完美。