设计JavaScript API的五个建议

转载于：http://www.csdn.net/article/2012-11-08/2811525-Designing-APIS

 

最近在Filepicker.io上花了很多时间研究API，随着JavaScript API 1.0的发布，我们总结了API设计经验，分享给大家，希望我们在使用您的API时，也能像使用自己的API那样兴奋。

规则0：不要随意对API做出改变

API是你与产品使用者沟通合作的桥梁，好比合同，请不要轻易修改和违背。开发者会花时间和精力学习研究你的API，并且把它们融入到自己的产品中。

然而，随着时间的推移，初始版本会逐渐过时并且需要定时推出些新版本。甚至经过一些阶段后，你需要一次性地做出些重大调整。如果可以，在新版和旧版之间提供一个垫片，然后把旧版的API调用映射在上面。这样就不会打破用户在原有旧版本里面的所有接口调用。

在我们早期客户的开发过程中，产品和功能集经常性发生变化，这也就意味着API的累积会越来越多。虽然它能正常工作，但是在处理我们的API时，仍然会有许多不统一的地方。所以，在设计API时，就应该从第一版本开始，采用统一的规范和操作说明，以此来避免后期的不统一。

规则1：给API提供“木头”、“钉子”和完整的架构

提供一些高级功能，里面包含整个工作流程和“原材料”，开发者只需一行代码即可实现整个流程，而那些“原材料（raw primitives）”允许开发者自定义功能模块。

如果有人向你寻求如何构建一所房子，那么你可以提供两个有帮助的东西：第一是直接给他们一所房子，第二是提供工具、指导以及原材料。如果你给他们三块钉在一起的木板，那真是令人沮丧的：首先他们需要找到合适的方法，让木板变成他们所需要的，其次是关于如何应用它们。

规则2：名词、动词和完整的二分图

在传递对象和执行操作时需要注意哪些规则？当你能操纵每个对象时，你就可以为整个API找到很好的候选对象。

这样会让人对所设计的API多一些思考和认识。开发人员使用名词和动词组织成句，使用模型/名词/对象或者其他动词/动作为数轴，画一个网格。如果你能基于某个对象完成特定的操作，那么就把网格中相应的小正方形涂满。对于那些空白的小正方形，应该在文档中表明，给予特殊的警告，并且说明为什么？当把整个网格涂满时，就可以把它当成一个完整的“块”，作为很好的API设计候选对象。

规则3：快速高效地处理API错误

当处理API程序错误时，应该立即抛出异常。应该把用户操作和意外情形下发生的错误归为一类错误返回。提出一致的错误处理方式，下面提供了一些方案，尤其适合设计JavaScript API使用：

• 开发者不应该使用try-catch。如果在抛异常过程中开发人员又制造了错误（或者错误没有很好的记录），那么应该尽快弹出通知。
• 当一些意外事情发生或者用户做了一些“类似错误”（没有做出选择、上传内容无法阅读的情况下关闭对话框等）的时候，应该以统一的方式传回到固定类型的错误中。

当与API进行连接时，可以先看看你的开发库是否可以做些什么，这可能需要对你的代码花些额外的心思，但可以捕获一些常见的错误。例如，限制用户的图片选择，你可以设置{mimetype:“image/*”}或者{mimetypes:“image/*”}，filepicker.read()方法调用会接受FPFiles、URLs、DOM文件对象以及DOM输入类型。如果想在IE8中成功读文件，程序库会不顾一切地执行该操作（查阅post），但对于开发者来说，往往功能实现就无需考虑异常和一些错误案例。

规则4：好的API应该易使用

使用API就像是在开发API一样，在开发之前或者初期，你可以让你的客户/朋友也尝试做些同样的事情。

首先需要指明的是，API会把所有的演示方案转换成新的设计。API会用到许多模板文件去做一些简单的事情，对此，我们最好简化这些文件。然后基于用户做一些用户体验，编写指导说明并且检查具体实施情况。站在用户角度去设计，前提是你要喜欢自己的设计和使用体验，然后才能让客户喜欢。

更多精彩内容，请关注新浪微博@CSDN研发频道

来自：filepicker.io