如今,能帮助开发人员设计API的工具、技术和平台可谓种类繁多。尽管资源丰富,但API设计中仍然存在着一大难题:如何为API命名。这事听起来简单,但命名本身也需要一整套可持续且稳定可靠的设计流程,用以定义API的识别、分类与命名原则。总之,这事可绝不像很多人想象中那么轻松。
在《API设计模式》一书中,作者兼谷歌软件工程师JJGeewax把命名称为API开发者最需要学习和掌握的众多关键设计因素之一。合理的API命名约定不仅能改善API的可访问性和用户友好度,同时也有助于预防很多令人头痛的API可用性问题。
名称里的玄机
Geewax提到,API的名称之所以如此重要,是因为API的功能往往取决于自身跟用户的交互能力。用户经常会通过API名称来快速判断访问时将要接收、查看或操作的信息类型。此外,这些名称还能指示出技术组合当中的哪些API彼此直接相关,或者在设计上负责处理哪些请求类型。
在书中第三章部分,Geewax讨论了API命名方法的重要意义:
对于传统编译代码,我们的函数和变量名称只会影响到有权访问源代码的人。而经过编译(最小化)和部署,这些名称往往彻底消失。而在设计和构建API时,名称的选择则更加重要,因为它们负责代表并描述所有API用户将要看到并进行交互的内容。
Geewax还强调,最好能在开发早期就确定API的命名模式,甚至可以考虑把命名作为开发的第一步。开发者应该为API命名实践设定好期望,而具体名称的选择将最终影响到API组合的管理方式。例如,特定API所对应的特定名称将影响到开发者在后续版本更新、或者出现新需求时,新增API所能使用的具体名称。API组合规模越大,开发者就越难在不影响原有体系的前提下更改名称模式。
API名称:什么是好,什么是坏
Geewax在《API设计模式》中提出的命名实践,基本上围绕着同一个中心主题:API名称是分好坏的。好的API名称既要降低冗余,又应该最大限度减少用户的理解难度。而坏名称也可能误导用户,致使其理解错乱、找不到自己最需要的API。在极端案例中,差劲的名称甚至会引发冗余构建,白白浪费掉宝贵的应用程序资源、增加不必要的开发成本。
Geewax在书中以存储用户账户偏好项的API为例,提到如果开发者只是简单把该API命名为APIPreferences,那么用户其实很难结合上下文理解这个API到底是什么作用。在这种情况下,UserPreferences之类的名称明显更合适,能保证用户准确理解自己要处理的是什么。
另一方面,名称太过具体并不是好事。假设开发者把这个用户偏好项API命名成了SingleUserAccountPreferences,那使用者可能会怀疑该API到底是存储着很多用户的个人偏好、还是只存储单一个人用户的偏好。如果碰巧认定为后一种解释,开发团队甚至有可能为每个单独的账户分别构建API。所以说,UserPreferences才是最佳选择,详略得当而且清晰易懂。
API名称特征
在命名API的时候,开发者其实也可以灵活发挥,毕竟命名约定并不像程序代码那样具有严格的语法和结构要求。但是,灵活性可不代表什么东西都能拿来当名称。
如果同样有多种方式来表达同一事物,我们往往倾向于把这些表达混合使用,而这最终会导致命名规则变得复杂莫测,也让使用者难以区分不同API之间的联系和不同。为此,我们必须控制住灵活表达的“诱惑”,强加给自己一些命名规则,避免破坏API名称的良好可预测性。
当然,什么是清晰、什么是简单、如何寻求二者的平衡,具体还是要取决于项目特性。想找到百试百灵的通行办法几乎不太可能。作为指导,Geewax结合API设计原则,提出了API名称中所应体现的三大特征:
表达力:意味着API名称应该清晰传达它所代表的功能、资源、消息、字段、属性或值的类型;
简单性:要求名称除表达力之外,还应在每个具体部分都提供合理价值;
可预测性:意味着API名称应该易于理解,且遵循明确的命名模式。
那么,开发者该如何确保API名称满足这三大条件呢?Geewax的答案,是为API命名确定四条通行的执行原则。
第一,优先使用美式英语。虽然肯定会有例外,但API名称最好使用美式英语,这也是编程世界中最具全球认可度的语言。如果必要,最好能始终提供本地化说明文档。
第二,注意使用正确的语法。虽然简略化的语法干练诱人,但在API名称中最好坚持使用正确的语法规则。比如,使用正确的拼写方式,