API设计指南(译)

API的设计在软件系统中的重要性不言而喻,在swift.org上看到一篇“API Design Guidelines”,虽然是就Swift而言,但对于其它语言也有不少可以借鉴的地方,在这里粗略翻译一二,作交流用途,比较随性,有些删改,如果需要看原文,请移步 https://swift.org/documentation/api-design-guidelines/  。

API设计指南

基本原则

  • 清晰,是第一要务。API方法和属性一处声明,到处调用,我们需要设计的使用起来简单明了。当我们评估一个设计的时候,单看其声明是基本不够的,通常需要置于具体使用场景,确保在使用时清晰明了。
  • 清晰远比简明重要。虽然代码可以写的紧凑,但是用最少的字符写最少的代码绝非我们的目标,如果说Swift代码简练,那也是强类型系统的一个副产品,可以减少样板代码。
  • 每个声明都进行文档注释。写文档可以加强对设计的深刻认知,不要拖延。如果发现自己不能简单地描述API的功能的话(bad smell),很可能存在设计问题。

(Swift代码注释建议,略去)

命名

用起来更加清晰

  • 包括所有必须的词语,以免混淆。
  • 忽略不必要的词语。命名中的每一个词语对使用者都有显著意义。
  • 对于变量名、参数名、以及参考类型名,应根据其角色命名,而不是其约束。
  • 对于弱类型参数信息进行补充,让参数角色更加清晰(比如参数名增加一个名词描述角色)。

力争使用流畅

  • 方法名或者函数名尽可能使用符合英语语法的形式。
  • 工厂方法名称以“make”开始。
  • 初始化方法和工厂方法调用时形成的短语应该不包含第一个参数。
  • 根据方法或者函数的连带结果进行命名。
    • 如果没有连带结果,应该是一个名词命名。
    • 如果有连带结果,应该是一个动词命名。
    • 可变和非可变方法成对命名时应该有一致的格式。
  • 对于不可变的布尔类型的方法或者属性,应该是断言的形式,比如 x.isEmpty 。
  • 描述事物的协议应该以名词进行命名。
  • 描述能力的协议应该以 able, ible, 或者ing作为后缀。
  • 其它的类型、变量、属性、以及常量的名词应以名词命名。

用好术语

  • 避免使用晦涩难懂的术语,尽可能使用通俗易懂的方法来描述。
  • 合理使用术语,术语应该用在恰当的地方。
  • 不要使用缩略语。

惯例

通用惯例

  • 复杂度不是O(1)的计算所得属性应该注释说明其复杂度。
  • 优先使用方法和属性,尽量减少使用函数。
  • 遵循大小写惯例,类型和协议的命名应该是首字母大写驼峰命名,其它的应该是首字母消息驼峰命名。
  • 方法名称可以共用一个基本名,如果这些方法有共同的基本含义。

参数

  • 利于文档注释,利于阅读。
  • 当隐含通常用法的时候,可以使用默认参数值。
  • 含默认参数值的参数应该置于参数列表的后面。

参数标签(Swift,略去)

特别说明

  • 闭环参数和元组成员应该设置标签(Swift)。
  • 谨慎使用无限制多态,以免重载的时候发生混淆。谨慎使用Any, All开头的名称。
时间: 2024-10-27 11:22:13

API设计指南(译)的相关文章

组件接口(API)设计指南-目录

组件接口(API)设计指南-目录 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface)  (排版中,待续) 组件接口(API)设计指南[3]-委托(delegate)和数据源协议(data-source protocols)  (排版中,待续) 组件接口(API)设计指南[4]-通知(Notifications)  (排版中,待续) 组件接口(API)设计指南[5]-最后的思考  (排版中,待续) 快速摘要: 译者注: 原文中

组件接口(API)设计指南-文件夹

组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付(delegate)和数据源协议(data-source protocols) 组件接口(API)设计指南[4]-通知(Notifications) 组件接口(API)设计指南[5]-最后的思考 高速摘要: 译者注: 原文中"delegate"译为中文"托付/代理",含义

RESTful API 设计指南

RESTful API 设计指南 本人来源于:http://www.ruanyifeng.com/blog/2014/05/restful_api.html 作者: 阮一峰 日期: 2014年5月22日 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行,甚至出现"API First"的设计思想.RESTful API是目前比

【转载】RESTful API 设计指南

作者: 阮一峰 日期: 2014年5月22日 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行,甚至出现"API First"的设计思想.RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.我以前写过一篇<理解RESTful架构>,探讨如何理解这个概念. 今天,我将介绍RESTful API

来自HeroKu的HTTP API 设计指南(中文版)

原文转自:http://get.jobdeer.com/343.get 来自HeroKu的HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国内首家互联网人才拍卖网站 JobDeer.com 的创始人.转载请保留本信息. 本指南描述了一系列 HTTP+JSON API 的设计实践, 来自并展开于 Heroku Platform API 的工作.本指南指导着Heroku内部API的开发,我们希望也能对Heroku以外的API设计者有所帮助.

HTTP API 设计指南(转)

英文原文: HTTP API Design Guide本文译者: LeoXu, Garfielt, 无若, --zxp 介绍 本指南描述了一套有关 HTTP+JSON API 的设计实践, 原始内容提取自 Heroku 平台 API 的工作. 本指南是对API的补充,也是Heroku新的内部API的指南. 我们希望引起Heroku之外的API设计者的兴趣. 这里我们的目标是一致的,专注于业务逻辑而避免脱节的设计. 我们就是要寻找一个良好的,一致的,文档优良的方式来设计API,而没必要是唯一理想的

RESTful API 设计指南(转)

网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行,甚至出现"API First"的设计思想.RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.我以前写过一篇<理解RESTful架构>,探讨如何理解这个概念. 今天,我将介绍RESTful API的设计细节,探讨如何设计一套合理.好用的API

(转) RESTful API 设计指南

原文: http://www.ruanyifeng.com/blog/2014/05/restful_api.html 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行,甚至出现"API First"的设计思想.RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.我以前写过一篇<理解RESTful

RESTful API 设计指南[转]

作者: 阮一峰 日期: 2014年5月22日 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行,甚至出现"API First"的设计思想.RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.我以前写过一篇<理解RESTful架构>,探讨如何理解这个概念. 今天,我将介绍RESTful API