开源实践联盟通信 2022年 09月23日

取名的艺术:为什么说API命名约定很重要?

对API的命名绝非易事,好的名称往往是简单和明确之间的均衡产物。面对这个问题,《API设计模式》一书的作者JJ Geewax为开发者带来了几条建议。

如今,能帮助开发人员设计API的工具、技术和平台可谓种类繁多。尽管资源丰富,但API设计中仍然存在着一大难题:如何为API命名。这事听起来简单,但命名本身也需要一整套可持续且稳定可靠的设计流程,用以定义API的识别、分类与命名原则。总之,这事可绝不像很多人想象中那么轻松。

在《API设计模式》一书中,作者兼谷歌软件工程师JJ Geewax把命名称为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命名为API Preferences,那么用户其实很难结合上下文理解这个API到底是什么作用。在这种情况下,UserPreferences之类的名称明显更合适,能保证用户准确理解自己要处理的是什么。

另一方面,名称太过具体并不是好事。假设开发者把这个用户偏好项API命名成了SingleUserAccountPreferences,那使用者可能会怀疑该API到底是存储着很多用户的个人偏好、还是只存储单一个人用户的偏好。如果碰巧认定为后一种解释,开发团队甚至有可能为每个单独的账户分别构建API。所以说,UserPreferences才是最佳选择,详略得当而且清晰易懂。

API名称特征

在命名API的时候,开发者其实也可以灵活发挥,毕竟命名约定并不像程序代码那样具有严格的语法和结构要求。但是,灵活性可不代表什么东西都能拿来当名称。

如果同样有多种方式来表达同一事物,我们往往倾向于把这些表达混合使用,而这最终会导致命名规则变得复杂莫测,也让使用者难以区分不同API之间的联系和不同。为此,我们必须控制住灵活表达的“诱惑”,强加给自己一些命名规则,避免破坏API名称的良好可预测性。

当然,什么是清晰、什么是简单、如何寻求二者的平衡,具体还是要取决于项目特性。想找到百试百灵的通行办法几乎不太可能。作为指导,Geewax结合API设计原则,提出了API名称中所应体现的三大特征:

表达力:意味着API名称应该清晰传达它所代表的功能、资源、消息、字段、属性或值的类型;

简单性:要求名称除表达力之外,还应在每个具体部分都提供合理价值;

可预测性:意味着API名称应该易于理解,且遵循明确的命名模式。

那么,开发者该如何确保API名称满足这三大条件呢?Geewax的答案,是为API命名确定四条通行的执行原则。

第一,优先使用美式英语。虽然肯定会有例外,但API名称最好使用美式英语,这也是编程世界中最具全球认可度的语言。如果必要,最好能始终提供本地化说明文档。

第二,注意使用正确的语法。虽然简略化的语法干练诱人,但在API名称中最好坚持使用正确的语法规则。比如,使用正确的拼写方式,关注名词单复数的适当使用。这样既有助于准确表达API作用,也能降低用户混淆的风险。

第三,句法同样重要。句法规定的是API名称中的单词排列顺序。在大多数开发场景下,句法应遵循三大标准格式之一:camel、snake和kabab。

最后,确保包含上下文。理想条件下,API名称应该提供一些与框架或程序类型相关的提示。如果API名称在不同场景下可能代表不同含义,最好能添加上下文以消除产生误解的可能性。

《数字化转型方略》杂志 《数字化转型方略》杂志