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

如今，能帮助开发人员设计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名称在不同场景下可能代表不同含义，最好能添加上下文以消除产生误解的可能性。