此文严格按照W3C规范和部分实际项目可读性,浏览器加载,性能等众多属性权衡,做出平时前端编码规范
文档。供广大web工作者参考并实施,对维护和项目扩展升级都能省时省力。
场景:前后端分离 异步利用JSON 传输数据;
E-JSON数据传输标准
简介
E-JSON的设计目标是使业务系统向浏览器端传递的JSON数据保持一致,容易被理解和处理,并兼顾传输的数据量。E-JSON依托于http协议(rfc2616)与JSON数据交换格式(rfc4627)。
JSON数据类型
JSON(JavaScript Object Notation)是一种轻量级,基于文本,语言无关的数据交换格式。其包括了基本数据类型4种和复合数据类型2种,共6种数据类型。在下面章节中,JSON数据类型的表示法为JSON+空格+数据类型,如:JSON Array。
传输的数据,包括对象属性以及数组成员, 必须(MUST) 是6种JSON数据类型之一。 杜绝(MUST NOT)
基本数据类型
- Number可以表示整数和浮点数。
- Boolean可以表示真假,值为true或false。
- String表示一个字符串。
- Null通常用于表示空对象。
"true"和true,这两个数据代表的是不同的数据类型。非字符串类型数据输出时一定 不要(MUST NOT)
复合数据类型
Object是无序的集合,以键值对的方式保持数据。一个Object中包含零到多个name/value的数据,数据间以逗号(,)分隔。name为String类型,value可以是任意类型的数据。
Object的最后一个元素之后一定 不要(MUST NOT)
Array(数组)为多个值的有序集合,数组元素间以逗号(,)分隔。
http响应头
status
http响应的status 必须(MUST)
Content-Type
Content-Type字段定义了响应体的类型。一般情况下,浏览器会根据该类型对内容进行正确的处理。对于传输JSON数据的响应,Content-Type 推荐(RECOMMENDED) 设置为"text/javascript"或"text/plain"。 避免(MUST NOT)
Content-Type中可以指定字符集。通常 需要(SHOULD)
Context-Type示例
数据字段
返回的数据包含在http响应体中。数据 必须(MUST)
status
status字段 必须(MUST) 是一个不小于0的JSON Number整数,表示请求的状态。这个字段 可以(SHOULD)
0:表示server端理解了请求,成功处理并返回。
非0:表示发生错误。 可以(SHOULD)
一个成功请求的status字段
statusInfo
statusInfo字段 通常(SHOULD) 是一个JSON String或JSON Object,表示除了请求状态外server端想要对status做出的说明,使client端能够获取更多信息进行后续处理。这个字段是 可选的(OPTIONAL)
client端参数错误的statusInfo
简单说明的statusInfo:
具有更多信息的statusInfo:
data
data字段可以是除JSON Null之外的任意JSON类型,表示请求返回的数据主体。这个字段是 可选的(OPTIONAL)
一个查询姓名请求的返回数据
数据场景
本章为常见数据场景定义了通用的标准数据格式,用于数据传输和使用。额外地,本章为部分可能大数据量传输的数据场景定义了变通数据格式。变通数据格式可在数据解析阶段转换成标准数据格式。
变通数据格式 必须(MUST) 是一个JSON Object,其中 必须(MUST) 包含e-type属性和data属性。e-type属性标识数据类型,便于对数据进行解析;data属性包含变通后的数据。变通数据 可以(MAY)
变通数据格式的e-type属性定义了table值。e-type属性可以使用者扩展其他属性值,扩展的属性值 必须(MUST)
日期类型
日期类型不属于JSON数据类型。对于日期类型,我们 必须(MUST) 使用JSON String来表示。为了让日期能够更容易的被显示和被解析,对于日期我们 应当(SHOULD)
数据场景:日期
记录
记录代表二维表中的一行,通常用于表示某个具体事务抽象的属性。标准记录数据 必须(MUST) 为一个JSON Object,记录的主键命名 必须(MUST)
数据场景:记录
二维表
二维表类型表识为table,是关系模型的主要数据结构。二维表结构具有变通数据格式。标准二维表数据 必须(MUST) 以一维JSON Array形式表示,JSON Array中每一项是一个JSON Object,代表一条记录。JSON Object的每个成员代表一个字段。每条记录的主键命名 必须(MUST)
在标准二维表中,字段名在每条记录中都被传输,会造成额外的数据量传输。这个问题会随着记录数的增大会更加突出。为了减少传输数据量,变通格式使用二维JSON Array传输数据,扩展fields属性用于字段说明。fields字段为JSON Array。
数据场景:标准二维表
数据场景:变通二维表
数据页
数据页是列表数据常用的数据方式,可能通过查询或翻页获得数据。数据页是二维表数据的包装,包含列表数据本身更多的信息。
数据页 必须(MUST) 是一个JSON Object,其中 必须(MUST) 包含的属性为data。data是一个二维表。数据页可以包括一些 可选(OPTIONAL)
数据页可选属性
- {Number} page - 当前页码,计数 必须(MUST)
- {Number} pageSize - 每页显示条数, 必须(MUST)
- {Number} total - 列表总记录数, 必须(MUST)
- {String} orderBy - 列表排序规则。多个排序规则之间以逗号分割(,);正序或倒序以asc或desc表示,与字段名之间以一个空格间隔。例:"id desc,name asc"
- {String} keyword - 列表所属的搜索关键字。
- {Object} condition - 列表所属的搜索条件集合。属性中可以包含或不包含keyword字段,如果不包含, 建议(RECOMMMANDED)
数据场景:数据页
键/值对象
对于在一个JSON Object中表示键/值:
- 键的属性名 必须(MUST) 为name, 杜绝(MUST NOT)
- 值的属性名 必须(MUST) 为value, 杜绝(MUST NOT)
数据场景:键/值对象
键/值有序集合
键/值有序集合表示对事务或逻辑类型的抽象与分类。常见的应用场景有单选复选框集合,下拉菜单等。
标准的键/值有序集合是一个JSON Array,集合中的每一项是一个JSON Object。项 必须(MUST) 包含name和value属性。 可以(MAY)
数据场景:键/值有序集合
树
树形数据用于表示层叠的数据结构。树型数据 必须(MUST) 是一个JSON Object,代表树型数据的根节点。下面是标准定义的可选节点列表,不在列表中的属性 可以(SHOULD)
树型数据结构的可选节点属性
- {Number|String} id - 节点的唯一标识。
- {String} text - 名称或用于显示的字符串。
- {Array} children - 子节点列表。
数据场景:树型数据
入坑方式:
web前端 聚集地,汇聚了全国顶尖的web前端热爱者,最新技术,最炫潮流,最靠谱的话题:
做好现在!技术只是为了改变生活!JS前端实用开发QQ群 :147250970
扫描屏幕下方的二维码,可以关注 我的前端公众号 。听说妹子挺多的,及时更新一些前端解惑和段子