1 背景

此处我不解释为什么要前后端分离、前后端分离的优缺点等问题，采用前后端分离开发模式就变成了这样，

前后端分离开发模式

前后端分离的开发模式引入的一个问题就是对接界面双方却关注甚少，没有任何接口规范情况下各自撸起袖子就是干，

干就完了
导致我们在产品项目开发过程中，前后端的接口联调对接工作量占比在30%-50%左右，甚至会更高。往往前后端接口联调对接及系统间的联调对接都是整个产品项目研发的软肋。
本文的主要初衷就是规范约定先行，尽量避免沟通联调产生的不必要的问题，让大家身心愉快地专注于各自擅长的领域。

2 接口规范

2.1 原则

前端关注交互、渲染逻辑，尽量避免业务逻辑处理；后端关注数据、逻辑等。
渲染逻辑禁止跨多个接口调用。

2.2 通信协议

使用HTTPs协议或者HTTP协议，统一用一种，建议使用HTTPs协议以确保交互数据的传输安全。

2.3 域名

尽量将API部署在专用域名之下，如https://api.xxx.com；多个项目创建API，用项目名作为文件夹，如https://api.xxx.com/project-name。

2.4 URL

建议全部使用小写，不用大写
如https://api.xxx.com/project-name/v1/users/。
用中杠-不用下杠_
如https://api.xxx.com/project-name/v1/users/。
URL中的名词表示资源集合，使用复数形式
如https://api.xxx.com/project-name/v1/users/，如users。关于复数的问题社区内争议很久了，再加上一些不规则的名次复数问题，就更不好统一了。如people、foot、hero，不是简单的加s就可以了。
避免层级过深的URL
体现API演进即携带版本信息
如https://api.xxx.com/project-name/v1/users/，v1即版本信息。
只能有名词，不能有动词
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应，正例如https://api.xxx.com/project-name/v1/students；反例如https://api.xxx.com/project-name/v1/getStudents。

2.5 正确使用HTTP动词

GET
幂等的操作，对应查询功能，响应的数据可以是单个的，也可以是多个的。所谓幂等即一个方法重复执行多次，产生的效果是一样的。如GET /api/v1/users/,GET /api/v1/users/1。
POST
非幂等的操作，用来创建一个子资源。如POST /api/v1/users，会在users下面创建一个user；多次执行，将导致多条相同的用户被创建。
PUT
幂等的操作，用来替换(新增或者更新)一个资源。如PUT /api/v1/users/1的意思是替换 /users/1，如果已经存在就替换沒有就新增。
PATCH
幂等的操作，用来对已知资源进行"局部更新"。
DELETE
幂等的操作，用来删除一个资源。如DELETE /api/v1/users/1的意思是删除id为1的用户。

2.6 响应格式

rest接口响应数据中应该包含响应状态和响应数据，数据格式为json。响应数据格式大致为

{
  code:200|500,
  msg:成功|失败|异常,
  data:响应数据
}

单一数据时格式为

{
  code:200|500,
  msg:成功|失败|异常,
  data:{
    key1:value1,
    key2:value2,
    ......
  }
}

列表数据时格式为

{
  code:200|500,
  msg:成功|失败|异常,
  data:[{
    key1:value1,
    key2:value2,
    ......
  },]
}

分页数据时格式为

{
  code:200|500,
  msg:成功|失败|异常,
  data:{
    pageNum: 1,//当前页码即第几页，从1开始
    pageSize: 10,//每页的行数
    total: 324,//符合查询条件的记录数
    pages: 33//总页数
    list: [{
      key1:value1,
      key2:value2,
      ......
    },]
  }
}

2.7 数据类型

这里特别说明Boolean类型和日期类型，其他类型正常使用即可。关于Boolean类型，JSON数据传输中建议统一使用1/0来标示即1为True0为False；日期类型JSON数据传输中建议使用数字类型即时间戳，具体日期格式可因业务而定。

2.8 异步任务

对耗时的异步任务，服务器端接受客户端传递的参数后，应返回创建成功的任务资源，其中包含了任务的执行状态。客户端可以轮训该任务获得最新的执行进度。关于长耗时任务的处理可参考我的另外一篇文章长耗时任务的善后处理。

2.9 错误处理

对于非正常情况，如未授权、没有权限、请求的资源不存在、参数错误等，都应有相应的错误提示，方便接口调用者根据提示改正错误。
正例

{
  code:400,
  msg:请求的资源不存在,
  data:{}
}

反例

0

2.10 URI失效

随着系统发展，总有一些API失效或者迁移，对失效的API，返回404 not found 或 410 gone；对迁移的API，返回 301 重定向。

3 最后

没有规矩不成方圆，有了规矩不遵守那规矩就形同虚设。希望大家在今后的开发中努力遵守规范，减少因接口不规范带来的麻烦，提高工作效率。