20190722 优雅的接口设计

哪些能够落实到自己的代码里面？

接口设计应该考虑哪些问题或者说考虑到哪些方面？

 

你设计的接口，够优雅吗？在设计接口时，有很多因素要考虑：

• 接口的业务定位
• 接口的安全性
• 接口的可扩展性
• 接口的稳定性
• 接口的跨域性
• 接口的协议规则
• 接口的路径规则
• 接口单一原则
• 接口过滤及接口组合

 

一 规范性建议

1.职责原则

在设计接口时，必须明确接口的职责，即接口类型，接口应解决什么业务问题等，当前接口是解决什么业务问题的?

2.单一性原则（单一职责原则）

在明确接口职责的条件下，尽量做到接口单一，即一个接口只做一件事，而非两件以上。

很多非资深接口设计者，在设计接口时，总认为接口所做的事越多，越牛叉，这是非常严重的错误认识。

单一职责原则和接口复用会冲突么？

3.协议规范

在设计接口时，应明确接口协议，是采用 HTTP 协议,HTTPS 协议还是 FTP 协议，要根据具体情况来定，当前接口采用的哪种协议类型？

(1)FTP 协议(File Transfer Protocol，简称 FTP)，是一套标准的文件传输协议，用于传输文件，如 .txt，.csv 等，一般文件传输，采用 FTP 协议。

(2)HTTP 协议，适用一般对安全性要求比较低或没要求的业务情景。

(3)HTTPS=HTTP+SSL，适用于对安全性要求较高的业务情景。

4.路径规则

由于api 获取的是一种资源，所以网址中尽量为名词，而非动词。

/api/v1.0/Product/2019

/api/v1.0/Users/2019

5.http请求方式

接口基本访问协议：get(获取)，post(新增)，put(修改)和 delete(删除)。

get     /users：列出所有用户

get    /users/id：根据id获取用户

post   /user：新增用户

put      /user/id：根据用户id更新用户

delete   /user/id：根据用户id删除用户

6.域名

一般的，域名分为主域名和专有域名，主域名适合 api 长期不变或变化较少的业务，专有域名是解决具体的专有业务的。

以百度举例：

(1)主域名:www.baidu.com

(2)产品服务类

百度文库：https://wenku.baidu.com/

百度知道：https://zhidao.baidu.com/

百度资讯： https://zhidao.baidu.com/

7.跨域考虑

在明确域名的情况下，一定要考虑接口是否跨域，以及跨域应采用的技术手段等。

8.api版本

对于接口的url，应加版本号 http://api.demo.com/v{d}/，其中d表示版本号,如 v1.0,v2.0。

例子：获取产品号为 2019，版本号为 v1.0 的版本号的产品信息 /api/v1.0/Pruducts/2019。

9.适度过滤信息

当记录数比较多时(如 SELECT * FROM TBName)，应适当添加一些条件对数据进行过滤，如 TOP，分页，分组，排序和 WHERE 条件等

下面是一些常见的参数。

?limit=100：返回 100 条数据

?offset=101：从第 101 条数据开始返回

?page=10：指第 10 页

?per_page=100：每页 100 条数据

?sortby=name：排序字段

?order=desc：降序

?group=groupName:分组

?producy_type=1：筛选条件

10.返回数据格式

返回数据格式，一般包括三个字段：

(1)失败情况(标识fail、错误码-1和错误描述message)

(2)成功情况(标识success，数据对象data，状态码000000)

11.安全性原则

接口暴露的考虑，接口并发量的考虑，接口防攻击的考虑，接口跨域的考虑等。

12.可扩展性原则

在设计接口时，充分考虑接口的可扩展性。

13.定义api访问权限

任何 api，从权限上，可归结为匿名api和非匿名api，前者不需要验证，后者需要验证。

14.定义api返回码

在 api 设计时，要定好 api 返回码，如

1）1 --授权过期

2）404--未找到资源

3）500--内部服务器错误

4）600--账号被锁

 

二 反规范性建议

存在这样一种业务场景：某个接口需要返回多个 api 接口组合的结果 ，在类似的业务场景下，所设计的接口，具有一定的反规范性（某个接口需要组合多个接口的数据）。

假设存在这样一个一个业务：一个ERP系统，需要提供两个接口，一个是用户访问接口(需要验证)，另一个是用户注册接口(不需要验证)。

根据本篇文章一，二部分的建议，我们来设计满足该业务需求的接口

 

接口权限类别，统一错误码的定义，统一输出参数的定义；

接口文档里面需要的这些内容，如果需要些接口文档必须按照这种规范来写；

接口定义：接口名，描述信息，请求方式，校验方式(是否匿名访问)，code示例

请求参数：参数名，数据类型，是否必须，描述信息

 

接口命名规范：

1. 拼写要准确(单词不能拼写错误)

接口函数一旦发布就不能改了，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。

2. 不仅是英文单词不要拼错，时态也不要错。

比如：返回bool的判断函数，单数要用 is,复数要用are，这样你的命名就和文档中的描述保持了一致性。表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。正确的时态可以给使用者传递更丰富的信息(ing和ed)。

3. 函数最好是动宾结构(做什么事情，方法名以动词开头)

动宾结构就是 doSomething，这样的函数命名含义明确

比如： openFile, allocBuffer, setName

如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语

4. 属性命名最好是定语+名词 （全局变量或者说局部变量，两个单词）

比如 fileName, maxSize, textColor

5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音

比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。

Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。

6. 不要自己发明缩写

除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。

坏例子: count->cnt, manager->mngr password->pw button->btn

现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。

7. 保持方法的对称性，有些方法一旦出现就应该是成对的，

比如 有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。

如果open对应clear就有点让人困惑了。

8. 站在使用者的角度去思考，API设计也要讲究用户体验。

好的API设计应该是符合直觉，能望文生义的，让使用者能用尽量简洁的代码完成调用。

 

为了性能而牺牲接口设计可维护性的误区，最终往往在性能上提升很少，甚至没有提高，程序可维护性也大大降低，这是我们都不希望看到的结果。