E-JSON 数据传送标准

JSON 数据类型

JSON包括基本数据类型 Number(整数和浮点数), Boolean, String, Null以及 Object, Array 两种复合数据类型,Object 是无需的集合,以键值对的方式保持数据.一个 Object 中包含0到多个 name/value 的数据,数据间以逗号分隔,name 是 String 类型,value 可以是任何类型的数据.

Object 的最后一个元素之后一定不要加上分隔符的逗号,否则可能导致解析错误.这个错误我见过许多次了...smarty 和 ajax 请求返回的本地假数据我都碰到过...而且错误提示不太好...或许 smarty 的错误提示可以更好一些或者自动忽略该低级错误.

http 响应头

Content-Type

该字段定义了响应体的类型,一般情况下浏览器会根据该类型会内容进行正确的处理.对于传输 JSON 数据的响应,Content-Type 设置为'text/javascript'或者'text/plain'不要设置为 text/html, 否则可能会有安全问题.

Content-Type 可以指定字符集.返回的数据包含在 http

数据字段

响应体中,数据必须是一个 JSON Object,该 Object 可能包含3个字段:status, statusInfo, data.

status

必须是一个整数,表示请求状态.

statusInfo

可选,String 或者 Object 表示除了请求状态之外 Server 端想要对 status 做的说明.使 client 能够获取更多信息进行后续处理.

data

可以是除了 Null 之外的 JSON 类型,表示请求返回的数据主体,包含了在请求成功时有意义的数据.

...

模块和加载器规范

*这部分的目标是定义前端代码的模块规范,便于开发资源的共享和复用.本规范再 amdjs 规范的基础上进行了更加细粒度的规范化.

模块定义

必须采用 define(factory); 的形式.不应该采用 define(moduleId, deps, factory); 的格式.

moduleId

1. 类型必须是 string,并且是由 / 分割的一些 term 组成.

2. term应该符合[a-zA-Z0-9_]+ 这个规则.

3. 没有.js 后缀.

4. 应该跟文件的路径保持一致.

在实际使用的时候, 分类:

1. relative moduleId: 以 ./ 或者 ../ 开头的 moduleId

2. top-level module: e.g. bar/a

包结构规范

该规范主要是针对资源分包进行约定规范,使得开发资源被共享和复用.

• ${root}表示包的根目录

  -包定义

包在具体实现过程中,必须按照模块和加载器规范来开发和管理模块.

• 模块定义

  必须采用匿名 id define( factory ) 进行定义.不采用 define( mofuleId, factory)

• 依赖管理

  包中的模块对其他模块的依赖分成两种: 内部模块依赖和外部包依赖.

1. 内部模块依赖require 必须采用 relative id.

2. 对外部包依赖必须采用 top-level id.

开发时,我们通常会做一些测试用例或者示例,此时需要通过 AMD loader 将当前包粘合到页面环境,并使其可运行,我们这时候需要遵守一些规则:

1.对内部模块依赖, AMD loader 配置通过 packages 将 location 配置到${root}下的 src 目录,不允许通过 paths 进行路径映射.

1. 对外部包依赖,可以参照 项目目录结构规范将相关依赖包导入,通过 packages 项配置 AMD loader.

//ER package 的 test 配置require.config({    packages: [        {            name: 'er',            location: '../src',            main: 'main'        },        {            name: 'mini-event',            location: '../dep/mini-event/1.0.0/src',            main: 'main'        },        {            name: 'etpl',            location: '../dep/etpl/2.0.2/src',            main: 'main'        }    ]});

包描述文件

必须置于{$root}下, package.json, 是一个 UTF-8编码的严格 json 格式的文本文件.

必选字段

1. name: 包名,必须是由 camel 命名法产生的字母组成的字符串.

2. version: 版本号

3. maintainers: 维护者列表.该字段是一个数组.数组中每项必须包含维护者的'name'字段以及'email'字段.

可选字段

1. main: 模块名,是当前包的入口文件,如果包名是 foo,那么执行 require('foo')的时候,返回的内容就是当前包 exports 的内容.

2. description: 描述信息

3. dependencies: 依赖声明.JSON Object,key 是依赖的包名,value 是版本号.支持格式:version, >version >=version, <version, <=version; *: 任意版本

4. devDependencies: 类似 dependencies,但不是当前包必须的,只是在开发和调试的时候一些依赖的内容

5. contributors: 贡献者列表. 数组,类似维护者 maintainers 数组

6. homepage: 该字段必须是 url 格式的字符串.

{    'name': 'zrender',    'version': '0.0.1',    'maintainers':[        {'name': 'foo', 'email': 'foo@baidu.com',        {'name': 'bar', 'email': 'bar@baidu.com', 'url': 'https://www.baidu.com/bar'}    ],    'dependencies': {        'foo': '0.0.1',        'bar': '*'    },    'devDependencies': {        'uglify-js': '*'    }}

包目录结构

${root}/    package.json    README.md    src/        css/[?]        img/        main.js    dep/        foo/        bar/        tangram/        mustache/        ...    test/    doc/

package.json

必须直接放在包顶层目录${root}中

src

${root}/    src/        main.js        Control.js        Button.js        css/            button.css        package.json        README.md

dep

存放 dependencies package.

项目目录结构规范

在以下规范说明中:1.项目包含但不限于业务项目和包项目2.${root}表示项目的根目录

资源分类

1. 源代码资源: 开发者编写的源代码 包括 js,html,css,template 等等

2. 内容资源:图片,字体,flash,pdf,doc 等等

目录命名原则

1. 简洁 有习惯性缩写的单词,必须采用容易理解的缩写.如: 源代码使用 src,不使用 source.

i. img:图片,不使用 image,images,imgs 等等.ii. js:脚本,不使用 script,scritps 等等.iii. css:样式表,不使用 style.styles 等等.iv. swf:flash.不使用 flash 等等.v. src:源文件目录.不使用 source 等等.vi. dep: 引入的第三方依赖包目录.不使用 lib,library,dependency 等等.

2.不使用复数形式,比如 imgs, docs...

目录划分

${root}目录结构划分

在${root}下,目录结构必须按职能进行划分.不允许将资源类型或者业务逻辑划分的目录直接置于${root}下面.

常用的目录有 src,doc,dep,test 等等.

${root}/    src/    test/    doc/    dep/    ...

业务项目目录结构划分

项目代号

通过加载器配置,将项目代号指向 src.

{    baseUrl: '${docroot}',    paths: {        'triones': 'src'    }}

根据业务逻辑划分 src 目录结构

业务项目的 src 目录内,绝大多数情况根据业务逻辑划分目录,划分出的子目录我们称为业务目录.

src 下必须包含业务目录与 common 目录.业务公共资源必须命名为 common.

${root}/    src/        common/        biz1/            subbiz1/            subbiz2/        biz2/

业务目录划分原则

1. js 资源不允许按资源类型划分目录,必须按业务逻辑划分目录,js 资源应该直接置于业务目录下,即: 业务目录下不允许出现 js 目录.

2. 除 js 资源外的源文件资源,当资源数量较多时,为管理方便,允许资源类型划分目录.即:业务目录下方允许出现 css,tpl 目录.

3. 内容资源允许按资源类型划分目录,即:业务目录下允许出现 img,swf,font 目录.

   4.业务目录中,如果文件太多不好管理,需要划分子目录时,也必须继续遵守根据业务逻辑划分的原则,划分子业务.

通常,对于一个业务目录, 鼓励将业务相关的源文件资源都直接置于业务目录下.

biz1/    img/        add_button.html    add.js    add.tpl.html    add.css

业务目录下源文件数量较多时,我们第一直觉是: 是否业务划分不够细,是否应该划分子业务,建立子业务目录?

biz2/    subbiz1/        list.js        list.tpl.html        list.css    subbiz2/

遇到确实是一个业务整体无法划分子业务时,允许将非 js 资源按资源类型划分目录进行管理.

biz1/    css/        add.css        edit.css        remove.css        img/            add_button.png        tpl/            add.html            edit.html            remove.html        add.js        edit.js        remove.js

业务项目目录划分示例

${root}/    src/        common/            img/                sprites.png                logo.png            conf.js            layout.css        biz1/            img/                add_button.png            add.js            add.tpl.html            add.less        biz2/            subbiz1/                list.js                list.tpl.html                list.css            subbiz2/    dep/        er/            src/            test/        esui/            src/            test/    test/    doc/    index.html    main.html    ...

包项目目录结构划分

包项目 src 目录结构划分

包是实现某个独立功能,有复用价值的代码集.

所以,包可以视作一个不太复杂的业务,,其 src 下的划分原则与业务项目的目录划分原则保持一致.

${root}/    src/f        css/            img/                sprites.png            table.css            button.css            select.css            smain.js            Control.js            InputControl.js            Button.js            Table.js            Select.js        test/        doc/        package.json        ...

常用目录

一级目录

直接置于${root}下的目录称作一级目录,它必须有某种职能属性.

除了下面列举的一些常见目录之外,${root}下面也可以放置一些跟项目发布相关的文件,例如 build.sh,build,xml, Makefile, Gruntfile 等等.

• src

  用于存放开发时源文件,发布时必须被删除.

• dep

  用于存放项目引入依赖的第三方包.该目录下的内容通过平台工具管理,项目开发人员不允许更改 dep 目录下的第三方包的任何内容.

当项目需要修改引入的第三方代码时,第三方包应将源码直接置于${root}/src 目录下,规则见该目录下的规定.

• tool

  用于存放开发时或者构建阶段使用的工具,该目录在发布时必须被删除.

• test

  用于存放测试用例以及开发阶段的模拟数据,该目录在发布时必须被删除.

• doc

  用于存放项目文档,可能是开发者维护的文档,也可能是通过工具生成的文档.

• entry

  用于存放项目的页面入口文件,通常是上线后可被直接访问的静态页面.

RIA 项目通常会包含较少的页面入口文件,常见的是main.html,这些文件可以直接放在${root}目录下.

${root}/    src/        common/            conf.js        card/        gold/        message/    index.html    main.html    ...

多页面项目通常页面入口文件较多,可以统一凡在 entry 目录中,按业务逻辑命名.

${root}/    src/        common/            conf.js        card/        gold/        message/    entry/        card.html        gold.html        message.html        ...

项目在发布时,构建工具可以以页面入口文件为入口进行分析和编译.

RIA项目经过构建工具编译后,目录结构可能如下:

output/    asset/        js/        css/        tpl/        img/    index.html    main.html

多页面项目经过构建工具编译后,目录结构可能如下:

output/    card/        asset/            js/            css/            img/        index.html    gold/        asset/            js/            css/            img/        index.html

• asset

  该目录存放 可用于线上访问的静态资源.

通常构建工具会对 src 目录和 dep 目录下的资源进行分享,合并与压缩,生成到 asset 目录下,所以该目录尽量避免手工管理,下面是一个构建工具生成后的 asset 目录示例:

${root}/    asset/        js/            loader.js            build.js        css/            common.css            img/        tpl/            build.tpl.html        img/        ...

资源目录

按资源类型命名的目录称作资源目录.不允许直接置于${root}下面.

• js

1. 目录内必须存放 js 资源文件,但是 js 资源文件不一定存放于 js 目录下:

1.对于 src 目录,js 资源文件不允许存放于 js 目录下.

2.对于 asset 目录,js 资源文件可以存放于 js 目录下,视构建行为决定.3.对于其他一级目录内,js 资源文件不存放于 js 目录下.

• css

  用于存放 css资源文件.

存放规则类似 js.

• img

  存放图片资源文件.包括页面直接引用以及css 引用图片.常见的图片资源有 gif/jpg/png/svg/bmp 等等.

对于 css 引用的图片,必须放下./img 目录下,.代表当前 css 资源所在的目录.

对于页面直接引用的图片:1.被多页面引用的图片应该放在${root}/src/common/img 目录下.2.单页面引用的图片应该放在./img 目录下, . 代表当前页面所在目录.

• tpl

1. 目录可以用于存放 template 资源文件,后缀名可以是.html,也可以是.tpl.通常,对于 RIA 系统,template 资源文件采用.html 后缀使其能够被 xhr 加载.

• font

  存放字体资源文件,常见的字体资源有tff/woff/svg 等等.

• swf

  存放 flash,不允许至于 img 目录中.

业务目录

common 是业务公共目录,用于存放业务项目的业务公共文件,所以根据业务逻辑划分目录结构时,业务逻辑命名不允许为 common.

实际上还有一个比较重要的有关 es6的规范,但是我用 es6用的很少.所以并不很了解...