前后端接口设计规范_前后端接口如何规范设计

设计规范原则

1. 前端应只关注渲染逻辑，而不应该关注数据的处理逻辑。接口返回的数据应该是能够直接展示在界面上的。
2. 一个功能应避免多个接口嵌套调用获取数据，后台应该处理好一次性返回。
3. 响应格式应该是JSON，而且应避免多级JSON的出现；
4. 后端如果需要界面实时刷新数据，不应该要求前端定时器轮询，而要提供类似webSocket之类的功能。

根据这个原则，后端返回的数据应该是所见即所得的数据，而不应该是一层包一层的复杂的JSON，需要前端额外来处理很复杂的去重，排序、深浅拷贝，变形等处理。前端在渲染每一个div，每一个table的cell时，不用担心数据结构会频繁更改从而导致页面崩溃。

接口制定的全流程

前端请求一般是HTTP协议，这里以HTTP为例。

HTTP请求的协议类型

应使用下面罗列的HTTP方法（使用的SQL关键字）:

GET（SELECT）：从服务器取出资源，一项或多项。
1

POST（CREATE）：在服务器新建一个资源。
1

PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
1

PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性），使用比较少
1

DELETE（DELETE）：从服务器删除资源。
1

下面是一些例子:

GET /schools：列出所有的学校列表
1

POST /school：新建一个学校
1

GET /school/{id}：获取某个指定学校的信息
1

PUT /school/{id}：更新某个指定学校的信息（提供该学校的全部信息，而不是让前端再通过别的接口获取）

1
2

PATCH /school/{id}：更新某个指定学校的信息（提供该学校的部分信息）
1

DELETE /school/{id}：删除某个学校
1

HTTP请求的参数定义

不同HTTP方法对应不同的参数传递方式，如下：

query指路径传参，body指requestBody请求体

• GET：path & query
• POST：path & body
• PUT：path & query & body
• PATCH：path & query & body
• DELETE：path & query

注意：

1. 未出现在上表中的位置不可放置参数，如GET方法不可在body中放置参数。
2. 参数命名均遵循小驼峰命名法。
3. path和query中传递的参数需确保长度可控，超过2000字符（因浏览器而异）的参数可导致请求失败。当请求无法保证参数长度可控，则不能将参数放在path或query中，必须使用支持body参数的HTTP方法，如POST。
4. path和query中传递的参数需是基本类型，亦不可传递序列化之后的JSON对象！不然前端就要try/catch一下来parse了。
5. body中的参数需是合法JSON对象或者formData，即使参数仅包含单字段或单数组，也需包含在对象中，如：

{
    name: string;
}
1
2
3

HTTP响应结果定义

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collections：返回资源对象的列表（数组）

{
  RetCode: 0,
    Message: 'ok',
    Action: 'collections',
    Data: [
    {
      Id: 1,
      name: 'collection1',
      ...
        },
    ...
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

GET /collection/resource：返回单个资源对象

{
  RetCode: 0,
    Message: 'ok',
    Action: 'collectionResource',
    Data: {
    Id: 1,
      name: 'collection1',
      ...
      }
}
1
2
3
4
5
6
7
8
9
10

POST /collection：返回新生成的资源对象

{
  RetCode: 0,
    Message: 'ok',
    Action: 'collection',
    Data: {
    Id: 1,
      name: 'collection1',
      ...
      }
}
1
2
3
4
5
6
7
8
9
10

PUT /collection/resource：返回完整的资源对象， 返回结果同上。
PATCH /collection/resource：返回完整的资源对象，返回结果同上。
DELETE /collection/resource：返回一个空文档

{
  RetCode: 0,
    Message: 'ok',
    Action: 'collectionResource',
    Data: {}
}
1
2
3
4
5
6

注意：

1. 所有返回数据需是合法JSON，尽量返回object或者array (二进制文件下载除外)。如果数据中包含类型为array的属性，当数据为空时，尽量返回空数组[]，避免返回null。
2. 返回数据避免使用map的<‘key’, ‘value’>形式！如有相关格式的返回数据，请转换为array。
3. 如果没有数据需要返回，或系统报错时，可统一返回固定字段：
4. 返回值中应尽量避免包含无用信息，或者额外的数据结构，仅包含必要数据即可。必要数据指前端需要渲染的数据。
5. 后端异常报错均以’500’状态码的形式返回，也可适当添加额外信息，非特殊情况无需在返回的数据体中返回HTTP code。

{
  RetCode: number; // 后端状态码
  Message: string; // 请求返回消息
  Action: string; // 请求的响应关键字
  Data: Object | Array; // 响应数据
}
1
2
3
4
5
6

URL规范

可参照下面的范例：

GET [http | https]://host:port/studio/api/组件名/v1/模块名/菜单名/接口名/:param
1

注意：

1. 不用大写字母，建议用中杠 - 不用下杠 _. 比如邀请码写成invitation-code而不是invitation_code
2. 使用名词表示资源集合，使用复数形式（为确保所有API URIs保持一致），不能使用动词；
3. 每个资源都至少有一个标识它的URI，同时应该遵循一个可预测的层次结构来提高可理解性，从而提高可用性；
4. 宾语必须是名词。网址中不能有动词，只能有名词，API中的名词也应该使用复数，宾语就是API的URL，是HTTP动词作用的对象。它应该是名词，不能是动词

正