代码规范之进阶篇

发布时间:2019-08-11 发布网站:脚本宝典
脚本宝典收集整理的这篇文章主要介绍了代码规范之进阶篇脚本宝典觉得挺不错的,现在分享给大家,也给大家做个参考。

E-JSON 数据传送标准

JSON 数据类型

JSON包括基本数据类型 Number(整数和浮点数), Boolean, String, Null以及 Object, Array 两种复合数据类型,Object 是无需的集合,以键值对的方式保持数据.一个 Object 中包含0到多个 name/value 的数据,数据间以逗号分隔,nameString 类型,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 packagetest 配置
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.

@H_512_324@项目目录结构规范
在以下规范说明中: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用的很少.所以并不很了解...

    脚本宝典总结

    以上是脚本宝典为你收集整理的代码规范之进阶篇全部内容,希望文章能够帮你解决代码规范之进阶篇所遇到的问题。

    如果觉得脚本宝典网站内容还不错,欢迎将脚本宝典推荐好友。

    本图文内容来源于网友网络收集整理提供,作为学习参考使用,版权属于原作者。
    如您有任何意见或建议可联系处理。小编QQ:384754419,请注明来意。