ajax response 规范

规范

HTTP Header

• 所有接口必须支持 CORS

• Content-Type

• • json application/json
• • form application/x-www-form-urlencoded

请求格式

请求分 GET 和 POST, 为 GET 时数据统一在 query 中, 为 POST 时数据统一为 json 格式, 放在 body 中. 对于特定场景, 字段有具体的约束.

响应格式

响应统一为 json 格式:

{
    "code": 200,      // {String|Number} 业务响应代码 (可选, 由业务自行决定)
    "success": true,  // {Boolean} 处理是否成功
    "message": "OK",  // {String} 响应消息内容, 如果 success = false 时, 应该是错误消息
    "errors": {},     // {Array|Object} 更加结构化的错误消息 (如表单错误)
    "data": [         // {Array} 数据列表/树形类型
        {
            "label": "选项1",
            "value": "值",
            "children": [ ... ] // 当 data 为树形时, 节点可能会有 children 属性
        }
    ],
    "data": {         // {Object} 列表数据 (带分页)
        "list": [],
        "total": 1234,
        "pageNo": 1,
        "pageSize": 20
    },
    "data": {         // {Object} 对象数据
        "id": 111,
        "name": "foobar",
        "type": "none"
    }
}

不同场景下, 具体的响应格式如下:

请求失败

简单场景如下:

{
    "success": false,
    "message": "请求的 ID 不存在"
}

复杂错误场景 (如表单校验):

{
    "success": false,
    "message": "表单校验失败, 有 3 处错误",
    "errors": {
        "name": "name 必须由字母或数字组成",
        "content": "内容不得少于 10 个字符",
        "status": "未定义 status"
    }
}

请求列表/树形数据

适用于下拉选项, 以及树形类目等不可分页的数据. 列表和树形结构, 统一采用数组表示, 列表可以认为是特殊的树形结构, 即没有 children 属性.

示例如下:

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "label": "选项一",
      "value": "a1",
      "children": [
        {
          "label": "选项二",
          "value": "b1"
        }
      ]
    }
  ]
}

请求分页列表

适用表格列表数据等需要分页的数据.

示例如下:

{
  "success": true,
  "message": "OK",
  "data": {
    "list": [
      {
        "id": 1112,
        "label": "选项一",
        "name": "a1"
      }
    ],
    "total": 1234,
    "pageSize": 20,
    "pageNo": 1
  }
}

请求对象数据

适用于返回某个数据模型, 示例如下:

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "name": "xxx",
    "template": "xx/aaa",
    "description": "asdaf"
  }
}

常见属性约定

时间

时间属性的统一格式化为时间戳，包括请求参数和响应属性。例如 1523188180169。

下拉框数据

属性名分别用 label、value。

[{
    "label": "bar",
    "value": "foo" 
}]

树形数据

子节点属性名使用 children。

[{
    "label": "显示名称",
    "value": "s11212",
    "children": [{
        "label": "显示名",
        "value": "s12111"
    }]
}]

分页字段

{
    "pageNo": 1,      // {Number} 当前页, 以 1 开始
    "pageSize": 20,   // {Number} 每页条数
    "total": 1234,    // {Number} 总条数
}