如今,能帮助开发人员设计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名称在不同场景下可能代表不同含义,最好能添加上下文以消除产生误解的可能性。
好文章,需要你的鼓励
Anthropic发布了面向成本敏感用户的Claude Haiku 4.5大语言模型,定价为每百万输入令牌1美元,输出令牌5美元,比旗舰版Sonnet 4.5便宜三倍。该模型采用混合推理架构,可根据需求调整计算资源,支持多模态输入最多20万令牌。在八项基准测试中,性能仅比Sonnet 4.5低不到10%,但在编程和数学任务上超越了前代Sonnet 4。模型响应速度比Sonnet 4快两倍以上,适用于客服聊天机器人等低延迟应用场景。
字节跳动发布Seedream 4.0多模态图像生成系统,实现超10倍速度提升,1.4秒可生成2K高清图片。该系统采用创新的扩散变换器架构,统一支持文字生成图像、图像编辑和多图合成功能,在两大国际竞技场排行榜均获第一名,支持4K分辨率输出,已集成至豆包、剪映等平台,为内容创作带来革命性突破。
英国初创公司Nscale将为微软建设四个AI数据中心,总计部署约20万个GPU,合同价值高达240亿美元。首个数据中心将于明年在葡萄牙开建,配备1.26万个GPU。德州数据中心规模最大,将部署10.4万个GPU,容量从240兆瓦扩展至1.2吉瓦。所有设施将采用英伟达最新Blackwell Ultra显卡。
红帽公司研究团队提出危险感知系统卡(HASC)框架,为AI系统建立类似"体检报告"的透明度文档,记录安全风险、防护措施和问题修复历史。同时引入ASH识别码系统,为AI安全问题建立统一标识。该框架支持自动生成和持续更新,与ISO/IEC 42001标准兼容,旨在平衡透明度与商业竞争,建立更可信的AI生态系统,推动行业协作和标准化。