数据交互格式标准

前后端数据交互标准格式详细说明

数据格式样例

{
  /**
   * 请求结果
   * -1: 业务检查不通过
   *  0: 请求成功，数据正常返回
   *  2: token 失效，主要用于用户登录超时、特定情况下主动清除用户登录状态
   *     例如用户权限发生变化等场景
   */
  "code": number,
  /**
   * 请求异常的提示信息
   * 当数据请求结果为 0 时，本节点仅需固定输出 "ok" 即可
   * 当数据请求结果为 -1 时，必须输出错误相关的描述内容
   * 
   * 业务检查不通过示例：
   * {
   *   "code": -1,
   *   "msg": "姓名不能超过 20 个字符"
   * }
   * 
   * 请求成功的示例：
   * {
   *   "code": 0,
   *   "msg": "ok",
   *   "data": {
   *     业务数据
   *   }
   * }
   */
  "msg": string,
  /**
   * 请求后返回的数据内容都应在 data 节点下输出
   */
  "data": {
    /**
     * 常规单一数据节点
     */
    "attr": value,
    /**
     * 对象数据节点
     */
    "user": {
      "name": "zhangsan",
      "age": 18
    }, 
    /** 
     * 列表型数据节点
     */
    "users": [{ object }, ...],
    /**
     * 数据表格查询结果输出的专用数据节点
     */
    "grid": {
      // 总记录数
      "total": number,
      // 数据列表内容
      "list": [
        {
          object // 数据模型
        },
        { ... }
      ]
    },
    /**
     * 用户登录、更新/刷新 token 等登录授权操作后输出的专用数据节点
     */
    "access": {
      "accessToken": string,
      "expiresIn": number
    }
  }
}

API 交互规则

RESTful API 是 API 设计风格而非标准，在团队应用中仅按需使用相应内容即可，目前团队执行以下规范

1. 开发与测试环境使用 http 协议，生产环境下使用 https 协议
2. 描述性 api 地址（Endpoint），例如：https://aa.com/v1/system/user/profile/{id}
3. HTTP 动词统一使用 POST

更多 RESTful API 内容：

• RESTful API 设计指南 (opens new window)
• RESTful API 最佳实践 (opens new window)

跨域与重复请求

除少数历史遗留项目外，公司现有项目均使用前后端分离模式，即前端、服务端各自独立开发、运行和部署。

跨域（CORS）

示例网址： https://abc.com:8080/

构成网址的三个基本元素

• 协议（https://）
• 网址（abc.com）
• 端口（8080）

两个网址之间，只要有上述三个元素中其中一项不一致，即为跨域访问。前后端项目在各自独立运行部署后，则天然处于跨域模式下

更多跨域资料：跨域资源共享 CORS 详解 (opens new window)

跨域请求模式

浏览器将 CORS 请求分成两类：

• 简单请求（simple request）
• 非简单请求（not-so-simple request）

简单请求

只要同时满足以下两大条件，就属于简单请求

1. 请求方法是以下三种方法之一：HEAD、GET、POST
2. HTTP的头信息不超出以下几种字段
   • Accept
   • Accept-Language
   • Content-Language
   • Last-Event-ID
   • Content-Type：只限于三个值 application/x-www-form-urlencoded、multipart/form-data、text/plain

非简单请求

非简单请求是那种对服务器有特殊要求的请求，比如请求方法是 PUT 或 DELETE，或者 Content-Type 字段的类型是 application/json

跨域应用

根据以上描述的内容，结合公司使用的规则

• 跨域
• HTTP 动词为 POST
• Content-Type 为 application/json

那么在发起 HTTP 数据请求时，HTTP Client 插件将会增加一次 HTTP 查询请求，称为 “预检” 请求（preflight），特点就是该请求的 General 段中的 Request Method 值为 OPTIONS，没有请求参数，该请求的功能仅在向服务器询问当前的 非简单请求 是否允许访问

应用服务器 / 静态网页服务器处理

项目开发之初，服务端应优先开发调试跨域支持，以免影响后续工作

另外，无论是具体的应用服务，如 nodejs、PHP 、GO 或 Java 等，还是静态网页服务器 nginx，在检测到请求方法是 OPTIONS 时，请直接返回 204 状态，该状态意为请求成功，但无返回内容（NO CONTENT），该处理可避免预检请求执行业务内容，浪费资源

数据表格

数据表格的标准数据交换格式

// 入参
{
  // 表格自动根据当前分页情况发送
  "pageNumber": number,
  "pageSize": number,
  // 自定义业务/查询参数
  ...
}

// 返回数据
{
  "data": {
    "grid": {
      // 总记录数
      "total": 53,
      // 数据列表内容
      "list": [
        {
          object // 数据模型
        },
        { ... }
      ]
    }
  }
}

原表格输出数据格式，此处仅作为 归档记录

// 入参
{
  // 表格自动根据当前分页情况发送
  "pageNumber": number,
  "pageSize": number,
  // 自定义业务/查询参数
  ...
}

// 返回数据
{
  "data": {
    "gridResult": {
      // 总记录数
      "totalRow": 53,
      // 数据列表内容
      "lists": [
        {
          object // 数据模型
        },
        { ... }
      ]
    }
  }
}

登录授权

访问类似用户登录、切换用户/公司/企业、交换/刷新 token 等接口时，在请求成功后，应输出 access 标准节点，用于输出登录授权相关的访问令牌及有效期限等内容

{
  "data": {
    "access": {
      "accessToken": string,
      "expiresIn": number
    }
  }
}

处理逻辑

用于数据请求的 http client 会在每一次数据请求成功后（"code": 0），检查数据内容中是否包含 access 节点，若有，则当前用户访问令牌等内容会被新数据所更新，并在下一次数据请求时，于 Request Headers 数据段中增加

"Authorization": "Bearer ${token}"

属性，上述 ${token} 内容为登录授权接口返回的 access.accessToken 数据，用于服务端进行用户身份验证