一、背景

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

二、接口规范定义

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结果中的状态码，并存尚可，用于体现不同维度的状态。