一、背景
无规矩不成方圆,为了开发人员间更好的配合,我特意整理了这么一篇文档供大家参考学习,如有意见、见解,请在评论区留言探讨。
二、接口规范定义
1、协议规范
为了确保不同系统/模块间的数据交互,需要事先约定好通讯协议,如:TCP、HTTP、HTTPS协议。为了确保数据交互安全,建议使用HTTPS协议。
2、接口路径规范
作为接口路径,为了方便清晰的区分来自不同的系统,可以采用不同系统/模块名作为接口路径前缀。
格式规范如下:
支付模块 /pay/xx
订单模块 /order/xx
3、版本控制规范
为了便于后期接口的升级和维护,建议在接口路径中加入版本号,便于管理,实现接口多版本的可维护性。如果你细心留意过的话,你会发现好多框架对外提供的API接口中(如:Eureka),都带有版本号的。如:接口路径中添加类似"v1"、"v2"等版本号。
格式规范如下:
/xx/v1/xx
更新版本后可以使用v2、v3等、依次递加。
4、接口命名规范
和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:删除某个指定动物园的指定动物
5、请求参数规范
请求方式:
按照GET、POST、PUT等含义定义,避免出现不一致现象,对人造成误解、歧义。
请求头:
请求头根据项目需求添加配置参数。如:请求数据格式,accept=‘application/json’等。如有需要,请求头可根据项目需求要求传入用户token、唯一验签码等加密数据。
请求参数/请求体:
请求参数字段,尽可能与数据库表字段、对象属性名等保持一致,因为保持一致最省事,最舒服的一件事。
6、返回数据规范
统一规范返回数据的格式,对己对彼都有好处,此处以json格式为例。返回数据应包含:返回状态码、返回状态信息、具体数据。
格式规范如下:
{
"status":"000000",
"msg":"success",
"data": {
//json格式的具体数据
}
}
返回数据中的状态码、状态信息,常指具体的业务状态,不建议和HTTP状态码混在一起。HTTP状态,是用来体现 HTTP链路状态情况,如:404-Not Found。HTTP状态码和json结果中的状态码,并存尚可,用于体现不同维度的状态。