# 数据交互格式标准

服务端与前端及手机移动端数据交互标准格式详细说明

内容目录

数据格式样例
- 数据输出的固定结构
- 状态码
跨域与重复请求
部分特定应用场景
- 数据表格
- 登录授权

# 数据格式样例

{
  /**
   * 请求结果状态码
   *
   *  0: 请求成功，数据正常返回
   *  9xx: 身份认证授权相关，系统预留异常状态
   *  其他状态码(4-6位)：业务检查不通过
   */
  "code": number,
  /**
   * 请求异常的提示信息
   *
   * 业务检查不通过示例
   * {
   *   "code": 10086,
   *   "msg": "您的电话号码异常！",
   *   "data": {}
   * }
   *
   * 网站/管理平台请求成功的示例
   * {
   *   "code": 0,
   *   "msg": "ok",
   *   "data": {
   *     业务数据
   *   }
   * }
   * 手机客户端请求成功的示例
   * {
   *   "code": 0,
   *   "msg": "用户订单更新成功！",
   *   "data": {
   *     业务数据
   *   }
   * }
   */
  "msg": string,
  /**
   * 请求后返回的数据内容都应在 data 节点下输出
   * data 节点的数据类型必须为 object 类型
   */
  "data": {
    // 常规单一数据节点
    "attr": value,
    // 对象数据节点
    "user": {
      "name": "zhangsan",
      "age": 18
    },
    // 列表型数据节点
    "users": [{ object }, ...],
    // 数据表格查询结果输出的专用数据节点
    "grid": {
      // 总记录数
      "total": number,
      // 数据列表内容
      "list": [
        {
          object // 数据模型
        },
        { ... }
      ]
    },
    // 用户登录、更新/刷新 token 等登录授权操作后输出的专用数据节点
    "access": {
      "accessToken": string,
      "refreshToken": string,
      "expiresIn": number
    }
  }
}

# 数据输出的固定结构

除文件流输出等特殊情况下，数据接口请求都应返回以下数据结构

{
  "code": number,
  "msg": string,
  "data": object
}

# 部分场景说明

请求成功

{
  "code": 0,
  "msg": "ok",
  "data": object
}

网站/管理平台 在数据接口请求成功的场景下，msg 字段固定输出 ok 文本内容

手机客户端 在进行人机交互场景，需要提示信息时，相关文本内容均来自 msg 字段，若无文本输出需求，同样默认输出 ok 文本内容

请求失败

{
  "code": 10086,
  "msg": "您的电话号码异常！",
  // 固定输出空对象 {}
  "data": {}
}

# 状态码

请求结果状态码按照大类来划分，分为 成功、系统预留异常、业务状态异常 等类型，输出字段为 code

// 数据请求成功
0: 成功

// 身份认证授权相关，系统预留异常状态，网站/管理平台或手机 APP 需执行后续操作
901: access token 过期或无效，需刷新令牌
902: refresh token 过期或失效，需重新进行登录认证操作
903: sign 签名无效，需重新登录手机 APP
904: client id 或 client secret 无效，需强制更新手机 APP
905: uuid 无效

# 业务错误状态

对于业务错误状态，通常会是四位数字状态码，但在业务场景需要的情况下，会有五位甚至六位的数字状态码，实际情况取决于业务场景的需求及复杂程度

对于业务错误的场景，网站/管理平台或手机 APP 通常情况下仅对错误内容进行通知提示，没有后续操作

# 跨域与重复请求

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

# 跨域（CORS）

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

构成网址的三个基本元素

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

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

# 跨域请求模式

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

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

# 简单请求

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

请求方法是以下三种方法之一：HEAD、GET、POST
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,
  // 自定义业务/查询参数
  ...
}

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

以下为原表格输出数据格式，此处仅作为 归档记录 以便查询

原表格输出数据格式

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

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

# 登录授权

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

{
  "code": 0,
  "data": {
    "access": {
      "accessToken": string,
      "refreshToken": string,
      "expiresIn": number
    }
  }
}

← 命名 API 交互规范 →