Practical API Design

Cluelessness 无绪

• 即使对事物的内在本质并不清楚，也可以很好的使用它。
• 例子：电视机、汽车、手机……
• 例子：软件、高级语言、数据库、算法……
• 不同层次的理解：用户、维修人员、开发人员、架构师、设计师……

选择性无绪

• 编程不是火箭科技，程序员不是科学家
• 软件工程中的无绪是指：程序员无需深入了解很多内容，也可写出好的代码
• 找到一种编程实践方法，让开发人员不用深入了解所有事情，即选择他们所需的知识
• API是对所需知识的抽象，它将系统的复杂性隐藏起来

评价API好坏的标准

• 可理解性
• 一致性
• 可见性
• 简单性
• 保护投资（兼容性）

评价API好坏的标准：jQuery

• 可理解性：Selector
• 一致性：链式调用
• 可见性：$
• 简单性：write less, do more.
• 保护投资：对比Dojo、YUI……

评价API好坏的标准：URL route

• 参考：偶对某框架的rant
• URL route用正则匹配？
• 例子：一个blog系统中，特定格式的URL映射到存档页面

评价API好坏的标准：某python Web框架

urlpatterns = patterns('',    
  (r'^articles/(?P<year>\d{4})/$', views.year_archive),    
  (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', views.month_archive),    
)	
	

评价API好坏的标准：Grails

static mappings = {  
  "/articles/$year/" (view:'year_archive') {  
	constraints { year(matches:/\d{4}/) }  
  }  
  "/articles/$year/$month" (view:'month_archive') {  
	constraints {  
	  year(matches:/\d{4}/)  
	  month(matches:/\d{2}/)  
	}  
  }  
}  	
	

评价API好坏的标准

• URL“/articles/2009/”返回的页面为2009年的存档
• URL“/articles/2009/06/”返回的页面为2009年6月的存档

(r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', views.month_archive)

"/articles/$year/$month" (view:'month_archive') {  
  constraints {  
    year(matches:/\d{4}/)  
    month(matches:/\d{2}/)  
  }
}

评价API好坏的标准：
正则表达式 vs 内嵌变量的字符串

• 可理解性
• 一致性
• 可见性
• 简单性
• 保护投资（兼容性）

评价API好坏的标准：
正则表达式 vs 内嵌变量的字符串

• 可理解性
• 一致性
• 可见性
• 简单性
• 保护投资（兼容性）

API演进过程中的兼容性问题

• 反面教材：Dojo
• Prototype之坑爹的getElementsByClassName
• Prototype之坑爹的Object.prototype
• 在Shim中应该抛异常还是静默失败？

坑爹的getElementsByClassName

• Prototype 1.6开始被deprecated，因为：

  native implementations return a NodeList rather than an Array.

• 问题出在哪里？
• 如果回到当初？

坑爹的Object.prototype

• prototype的修改是全局性的，和global变量一样，甚至更糟糕……
• ES5加入一些方法：用Object.xxx而不是Object.prototype.xxx
• 修改其他built-in对象的prototype如何？
• 与未来API的冲突？
• 解决之道：Wrapper、支持prototype隔离的Module系统

对于不支持的功能应该抛异常还是静默失败？

• ES5 Shim：shim是应该抛异常还是应该fail silently？

风格

• 短命名
• 占位符
• 重载形式的Accessor

Prototype开创的短名字

• $
• $$
• _

Prototype的短名

• $A
• $H
• $R
• $F
• $w

更多的短名字

• $d$
• $h$
• $ID$
• $SC$
• $CLASS$
• $thread$
• $E$
• $DD$

更多更多的短名字

• _.A
• _.B
• _.D
• _.F
• _.H
• _.N
• _.S

还有……

• _.isA
• _.isB
• _.isF
• _.isH
• _.isN
• _.isS

“_”作为占位符

• function f(a,b,c) {...}; var f1 = f.curry(x);
/* f1(b,c) -> f(x,b,c) */
• var f2 = f.partial(_, x);
/* f2(a, c) -> f(a, x, c) */
• var f2 = f.partial(_, _, x);
/* f2(a, b) -> f(a, b, x) */

用undefined作为占位符而不是“_”如何？

用undefined作为占位符而不是“_”如何？

• 参数本身是 undefined 怎么办？
• 在调用f.partial(x, undefined, y)时，x或y的值发生错误导致传入了undefined怎么办？

重载形式的Accessor

论KISSY中一则API的设计

具体实现对API的影响

• Lazy function definition pattern
• 改写函数实际上违背了FP的无副作用的精神

具体实现对API的影响

• 防御性编程习惯不是借口，文档不是借口
• 开发者不会预期函数引用会变化
• 就算API作者写了文档，开发者也不会看
• 就算开发者看了文档，也未必注意和理解这对代码的影响

总结

• API的目的是让开发者可以选择性无绪
• 评价API的好坏就是从“选择性无绪”出发，以此衍生出可理解性、一致性、可见性、简单性、保护投资（兼容性）等标准
• 即使是看似主观的风格问题，也是可能按照标准结合情境进行分析的
• 注意JavaScript的一些特点导致的特殊问题，如prototype，如动态语言特征，如ES5、Harmony新特性带来的API设计的进化等
• 只是一个初步尝试，需要更多的探讨……