前言
对于后端开发的程序员来说,开发接口可能是最日常且最普通不为过的事情。但是在开发的过程中其实是有很多因素需要考虑。比如:接口的业务定位、安全性、可扩展性、稳定性、跨域性、协议规则、路有规则、单一原则、接口过滤、接口组合等等多方面因素。
-
职责原则: 在设计接口时,必须首先明确接口的职责,接口需要解决什么类型的业务问题及具体问题是什么。
-
单一性原则: 在明确接口职责的条件下,尽量做到接口单一,一个接口只做一件事,而非两件以上。很多人则认为,一个接口所做的事情越多越强大,其实非也,这是非常严重的错误认识。
-
协议规范: 明确接口协议,采用HTTP协议还是HTTPS,还是FTP,这要根据具体情况来定。
FTP协议(File Transfer,简称FTP),是一套标准的文件传输协议,用于传输文件,如.txt,.csv等,一般文件传输,采用FTP协议
HTTP协议,适用一般对安全性要求比较低或没要求的业务情景
HTTPS=HTTP+SSL,适用于对安全性要求较高的业务情景 -
路径规则: 由于api获取的是一种资源,所以网址中尽量为名词,而非动词。比如:
/api/v1.0/pruduct/2019
/api/v1.0/users/2019 -
http请求方式: 接口基本请求类型:get(获取),post(新增),put(修改)和delete(删除)
get /users:列出所有用户
get /users/id:根据id获取用户
post /user:新增用户
put /user/id:根据用户id更新用户
delete /user/id:根据用户id删除用户 -
域名: 一般域名分为主域名和专有域名,主域名适合api长期不变或变化较少的业务,专有域名是解决具体的专有业务的。
以百度举例:
(1)主域名:www.baidu.com
(2)产品服务类
百度文库:https://wenku.baidu.com/
百度知道:https://zhidao.baidu.com/
百度资讯:https://zhidao.baidu.com/
(3)市场活动类
百度公益:http://gongyi.baidu.com
百度logo:http://logo.baidu.com/
百度世界:https://baiduworld.baidu.com -
跨域考虑: 在明确域名的情况下,一定要考虑接口是否跨域,以及跨域应采用的技术手段等。
-
api版本: 对于接口的url,应加版本号http://api.demo.com/v{d}/,如 ,其中d表示版本号,如v1.0,v2.0
例子:获取产品号为2019,版本号为v1.0的版本号的产品信息
/api/v1.0/Pruducts/2019 -
适度过滤信息: 当记录数比较多时(如 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:筛选条件 -
返回数据格式: 返回数据格式,一般包括三个字段:
code,msg,content
(1)失败情况(状态码、错误码和错误描述)
{ "code":0,//状态码 0-表示失败,1-表示成功 "error_code":"2003",//错误码,一般在设计时定义 "msg":"身份验证失败"//描述,一般在设计时定义 "content":null//返回结构体数据 }
(2) 成功情况(数据对象,状态码)
{ "content":{ "users":{ "id":"al201901111341",//用户id "name":"Alan_beijing",//用户名 "addr":"用户地址" } }, "msg": "查询成功", "code":1//状态码 0-表示失败,1-表示成功 }
-
安全性原则: 接口暴露的考虑,接口并发量的考虑,接口防攻击的考虑,接口跨域的考虑等
-
可扩展性原则: 在设计接口时,充分**考虑接口的可扩展性。
-
定义api界限: 任何api,从权限上,可归结为匿名api和非匿名api,前者不需要 验证,后者需要验证
-
定义api返回码: 在api设计时,要定好api返回码,如
1 --授权过期
404–未找到资源
500–内部服务器错误
600–账号被锁