代码规范之进阶篇

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

类型必须是 string,并且是由 / 分割的一些 term 组成.
term应该符合[a-zA-Z0-9_]+ 这个规则.
没有.js 后缀.
应该跟文件的路径保持一致.

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

relative moduleId: 以 ./ 或者 ../ 开头的 moduleId
top-level module: e.g. bar/a

包结构规范

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

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

模块定义
必须采用匿名 id define( factory ) 进行定义.不采用 define( mofuleId, factory)
依赖管理
包中的模块对其他模块的依赖分成两种: 内部模块依赖和外部包依赖.

内部模块依赖require 必须采用 relative id.
对外部包依赖必须采用 top-level id.

开发时,我们通常会做一些测试用例或者示例,此时需要通过 AMD loader 将当前包粘合到页面环境,并使其可运行,我们这时候需要遵守一些规则:
1.对内部模块依赖, AMD loader 配置通过 packages 将 location 配置到${root}下的 src 目录,不允许通过 paths 进行路径映射.

对外部包依赖,可以参照 项目目录结构规范将相关依赖包导入,通过 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 格式的文本文件.

必选字段

name: 包名,必须是由 camel 命名法产生的字母组成的字符串.
version: 版本号
maintainers: 维护者列表.该字段是一个数组.数组中每项必须包含维护者的'name'字段以及'email'字段.

可选字段

main: 模块名,是当前包的入口文件,如果包名是 foo,那么执行 require('foo')的时候,返回的内容就是当前包 exports 的内容.
description: 描述信息
dependencies: 依赖声明.JSON Object,key 是依赖的包名,value 是版本号.支持格式:version, >version >=version, <version, <=version; *: 任意版本
devDependencies: 类似 dependencies,但不是当前包必须的,只是在开发和调试的时候一些依赖的内容
contributors: 贡献者列表. 数组,类似维护者 maintainers 数组
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}表示项目的根目录

资源分类

源代码资源: 开发者编写的源代码包括 js,html,css,template 等等
内容资源:图片,字体,flash,pdf,doc 等等

目录命名原则

简洁有习惯性缩写的单词,必须采用容易理解的缩写.如: 源代码使用 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/

业务目录划分原则

js 资源不允许按资源类型划分目录,必须按业务逻辑划分目录,js 资源应该直接置于业务目录下,即: 业务目录下不允许出现 js 目录.
除 js 资源外的源文件资源,当资源数量较多时,为管理方便,允许资源类型划分目录.即:业务目录下方允许出现 css,tpl 目录.
内容资源允许按资源类型划分目录,即:业务目录下允许出现 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 资源文件,但是 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 目录下, . 代表当前页面所在目录.

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

font
存放字体资源文件,常见的字体资源有tff/woff/svg 等等.
swf
存放 flash,不允许至于 img 目录中.

业务目录

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