JSON 数据传输标准

JSON 数据类型

传输的数据,包括对象属性以及数组成员, 必须是6种JSON数据类型之一。 杜绝使用function、Date等js对象类型。

基本数据类型:

  • Number可以表示整数和浮点数。
  • Boolean可以表示真假,值为true或false。
  • String表示一个字符串。
  • Null通常用于表示空对象

复合数据类型:Object 和 Array。

非字符串类型数据(如 "false""0")输出时一定不要为两端加上双引号,否则可能产生不希望的后果。

http 响应头

http 响应的 status 必须为 200。返回错误的状态码可能导致数据不被处理。

Content-Type 字段定义了响应体的类型。推荐设置为 text/javascripttext/plain 。 字符集设为 UTF-8

text/javascript;charset=UTF-8

数据字段

返回的数据包含在http响应体中。数据是一个JSON Object。该Object可能包含3个字段:statusstatusInfodata

status

可选,表示请求的状态。必须是一个不小于0的JSON Number整数,省略时和为0时表示同一含义。

0:表示server端理解了请求,成功处理并返回。

非0:表示发生错误。 可以(SHOULD) 根据错误类型扩展错误码。

statusInfo

可选,表示对status做出的说明。可以是一个 JSON String 或 JSON Object。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 简易
{
"status": 1,
"statusInfo": "参数错误"
}
// 详细
{
"status": 1,
"statusInfo": {
"text": "参数错误",
"parameters": {
"email": "电子邮件格式不正确"
}
}
}

data

可选,包含了在请求成功时有意义的数据。可以是除JSON Null之外的任意JSON类型。

数据场景

除了通用的标准数据格式,对可能大数据量传输的数据场景可以变通数据格式,使用 e-type 属性标识数据类型,在数据解析阶段转换成标准数据格式。

日期类型

日期类型不属于JSON数据类型, 必须使用 JSON String 来表示。

1
2
3
4
{
"status": 0,
"data": "2010-10-10"
}

单条记录

JSON Object 格式,主键命名必须为 id

1
2
3
4
5
{
"id": 250,
"name": "erik",
"age": 18
}

多条记录(二维表)

JSON Array 格式,每一项是一个JSON Object,标准格式:

1
2
3
4
5
6
7
8
9
10
11
12
[
{
"id": 250,
"name": "erik",
"age": 18
},
{
"id": 251,
"name": "jason",
"age": 28
}
]

在标准二维表中,字段名在每条记录中都被传输,会造成额外的数据量传输。可以采用变通格式:

1
2
3
4
5
6
7
8
{
"e-type": "table",
"fields": ["id", "name", "age"],
"data": [
[250, "erik", 18],
[251, "jason", 28]
]
}

分页(数据页)

数据页是二维表数据的包装,包括一些可选的属性,表示当前数据页的信息。

数据页可选属性:

  • {Number} page - 当前页码。
  • {Number} pageSize - 每页显示条数。
  • {Number} total -列表总记录数。表示当前条件下所有记录的数目。
  • {String} orderBy - 列表排序规则。多个排序规则之间以逗号分割(,); 正序或倒序以 ascdesc 表示,与字段名之间以一个空格间隔。例:"id desc, name asc"
  • {String} keyword - 列表所属的搜索关键字。
  • {Object} condition - 列表所属的搜索条件集合。

示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"page": 0,
"pageSize": 30,
"keyword": "",
"data": [
{
"id": 250,
"name": "erik",
"sex": 1,
"age": 18
},
{
"id": 251,
"name": "json",
"sex": 1,
"age": 28
}
]
}

键/值对象

在一个JSON Object中表示键/值:键的属性名必须为name,杜绝使用key或k。值的属性名必须为value, 杜绝使用v。

1
2
3
4
{
"name": "BMW",
"value": 1
}

键/值有序集合常用于单选复选框集合,下拉菜单中,可以通过其他的属性修饰每一项的特殊信息,如selected。

1
2
3
4
5
6
7
8
9
10
11
[
{
"name": "BMW",
"value": 1
},
{
"name": "Benz",
"value": 2,
"selected": true
}
]

树形数据用于表示层叠的数据结构,JSON Object 格式。可选节点属性包括:

  • {Number|String} id - 节点的唯一标识。
  • {String} text - 名称或用于显示的字符串。
  • {Array} children - 子节点列表。

示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
"id": 1,
"text": "中国",
"children": [
{
"id": 10,
"text": "北京",
"children": [
{
"id": 100,
"text": "东城区"
},
{
"id": 101,
"text": "西城区"
},
{
"id": 102,
"text": "海淀区"
}
......
]
},
{
"id": 31,
"text": "海南",
"children": [
{
"id": 600,
"text": "海口"
},
{
"id": 601,
"text": "三亚"
},
{
"id": 602,
"text": "五指山"
}
......
]
}
......
]
}

参考

E-JSON数据传输标准

坚持原创技术分享,您的支持将鼓励我继续创作!