如何写出完美的接口:接口规范定义、接口管理工具推荐

无规矩不成方圆,为了开发人员间更好的配合,我特意整理了这么一篇文档供大家参考学习,如有意见、见解,请在评论区留言探讨。

 接口规范说起来大,其实也就那么几个部分,接口规范、接口管理工具、接口文档编写、开发文档编写。

接口规范定义

一、协议规范

为了确保不同系统/模块间的数据交互,需要事先约定好通讯协议,如:TCP、HTTP、HTTPS协议。为了确保数据交互安全,建议使用HTTPS协议。

二、接口路径规范

作为接口路径,为了方便清晰的区分来自不同的系统,可以采用不同系统/模块名作为接口路径前缀。

格式规范如下:

支付模块   /pay/xx

订单模块  /order/xx

三、版本控制规范

为了便于后期接口的升级和维护,建议在接口路径中加入版本号,便于管理,实现接口多版本的可维护性。如果你细心留意过的话,你会发现好多框架对外提供的API接口中(如:Eureka),都带有版本号的。如:接口路径中添加类似"v1"、"v2"等版本号。

格式规范如下:

  /xx/v1/xx

更新版本后可以使用v2、v3等、依次递加。

四、接口命名规范

和Java命名规范一样,好的、统一的接口命名规范,不仅可以增强其可读性,而且还会减少很多不必要的口头/书面上的解释。

可结合【接口路径规范】、【版本控制规范】,外加具体接口命名(路径中可包含请求数据,如:id等),建议具体接口命名也要规范些,可使用"驼峰命名法"按照实现接口的业务类型、业务场景等命名,有必要时可采取多级目录命名,但目录不宜过长,两级目录较为适宜。

格式规范如下:

/user/v1/sys/login     用户服务/模块的系统登录接口

/zoo/v1/zoos/{ID} 动物园服务/模块中,获取id为ID的动物

具体接口命名,通常有以下两种方式:

接口名称动词前/后缀化

接口名称以接口数据操作的动词为前/后缀,常见动词有:add、delete、update、query、get、send、save、detail、list等,如:新建用户addUser、查询订单详情queryOrderDetail。

接口名称动词+请求方式

 接口路径中包含具体接口名称的名词,接口数据操作动作以HTTP请求方式来区分。常用的HTTP请求方式有:

GET:从服务器取出资源(一项或多项)。

POST:在服务器新建一个资源。

PUT:在服务器更新资源(客户端提供改变后的完整资源)。

PATCH:在服务器更新资源(客户端提供改变的属性)。

DELETE:从服务器删除资源。

如:

GET /zoo/v1/zoos:列出所有动物园

POST /zoo/v1/zoos:新建一个动物园

GET /zoo/v1/zoos/{ID}:获取某个指定动物园的信息

PUT /zoo/v1/zoos/{ID}:更新某个指定动物园的信息(提供该动物园的全部信息)

PATCH /zoo/v1/zoos/{ID}:更新某个指定动物园的信息(提供该动物园的部分信息)

DELETE /zoo/v1/zoos/{ID}:删除某个动物园

GET /zoo/v1/zoos/{ID}/animals:列出某个指定动物园的所有动物

DELETE /zoo/v1/zoos/ID/animals/ID:删除某个指定动物园的指定动物

五、请求参数规范

请求方式:

按照GET、POST、PUT等含义定义,避免出现不一致现象,对人造成误解、歧义。

请求头:

请求头根据项目需求添加配置参数。如:请求数据格式,accept=‘application/json’等。如有需要,请求头可根据项目需求要求传入用户token、唯一验签码等加密数据。

请求参数/请求体:

    请求参数字段,尽可能与数据库表字段、对象属性名等保持一致,因为保持一致最省事,最舒服的一件事。

六、返回数据规范

统一规范返回数据的格式,对己对彼都有好处,此处以json格式为例。返回数据应包含:返回状态码、返回状态信息、具体数据。

格式规范如下:

{
 
    "status":"000000",
 
    "msg":"success",
 
    "data": {
 
        //json格式的具体数据
 
    }
 
}

    返回数据中的状态码、状态信息,常指具体的业务状态,不建议和HTTP状态码混在一起。HTTP状态,是用来体现 HTTP链路状态情况,如:404-Not Found。HTTP状态码和json结果中的状态码,并存尚可,用于体现不同维度的状态。

接口管理工具推荐

接口开发完后,最终的目的是提供给其他系统/模块来使用的,因此,接口的管理是必不可少的。

接口管理的痛点

接口的管理常常面临很多的痛苦,这里就列举几个常见的,看看你是否也遇到过。

系统/模块太多、接口太多,没有系统统一管理所有接口。
代码修改后,接口文档没有及时更新,造成接口文档和实际接口不一致的现象。
接口管理系统自主研开发成本高。
接口管理缺少接口mock功能。

更多请见:http://www.mark-to-win.com/tutorial/50493.html 

  • 0
    点赞
  • 2
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值