简介

该文档主要的设计目标是项目开发的目录结构保持一致,使容易理解并方便构建与管理。

编撰

李玉北、erik、黄后锦、王杨、张立理、赵雷、陈新乐、刘恺华。

本文档由商业运营体系前端技术组审校发布。

要求

在本文档中,使用的关键字会以中文+括号包含的关键字英文表示:必须(MUST)。关键字”MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”被定义在rfc2119中。

规范说明约定

以下规范文档中:

  1. 项目包含但不限于业务项目包项目
  2. ${root}表示项目的根目录。

资源分类

资源分成两大类:

  1. 源代码资源:指开发者编写的源代码,包括jshtmlcsstemplate等。
  2. 内容资源:指希望做为内容提供给访问者的资源,包括图片字体flashpdf等。

目录命名原则

  1. 简洁。有习惯性缩写的单词 必须(MUST) 采用容易理解的缩写。如:源代码目录使用src,不使用source。下面是更多例子:
    1. img: 图片。 不允许(MUST NOT) 使用imageimagesimgs等。
    2. js: javascript脚本。 不允许(MUST NOT) 使用scriptscripts等。
    3. css: 样式表。 不允许(MUST NOT) 使用stylestyles等。
    4. swf: flash。 不允许(MUST NOT) 使用flash等。
    5. src: 源文件目录。 不允许(MUST NOT) 使用source等。
    6. dep: 引入的第三方依赖包目录。 不允许(MUST NOT) 使用liblibrarydependency等。
  2. 不允许(MUST NOT) 使用复数形式。如:imgsdocs是不被允许的。

目录划分

${root}目录结构划分

在${root}下,目录结构 必须(MUST) 按照职能进行划分, 不允许(MUST NOT)资源类型业务逻辑划分的目录直接置于${root}下。

常用的目录有srcdocdeptest等。详细请参考一级目录详细说明

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

业务项目目录结构划分

业务项目的${root}目录结构划分遵循${root}目录结构划分

项目代号

业务项目 可以(SHOULD) 为项目起一个代号名称。代号名称 必须(MUST) 为一个单词,不宜过长。例:北斗的项目代号为triones,哥伦布的项目代号为clb,百度锦囊的项目代号为jn。项目代号有利于区分不同项目,为未来项目之间的重用留下扩展的后路。

在项目开发时,通常会使用如下加载器配置,将项目代号指向src

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

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

业务项目src目录内,绝大多数情况 应当(SHOULD) 根据业务逻辑划分目录结构。划分出的子目录(比如例子中的biz1)我们称为业务目录

src必须(MUST) 只包含业务目录common目录。业务公共资源 必须(MUST) 命名为commoncommon目录做为业务公共资源的目录,也视如业务目录

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

较小规模的业务项目(如投放端),src目录允许视如业务目录,直接按照业务目录划分原则划分目录结构。

${root}/
    src/
        foo.js

业务目录划分原则

  1. JS资源 不允许(MUST NOT)资源类型划分目录, 必须(MUST)业务逻辑划分目录。JS资源应直接置于业务目录下。即:业务目录下不允许出现js目录。
  2. JS资源外的源文件资源,当资源数量较多时,为方便管理, 允许(SHOULD)资源类型划分目录。即:业务目录下允许出现csstpl目录。
  3. 内容资源 允许(SHOULD)资源类型划分目录。即:业务目录下允许出现imgswffont目录。
  4. 业务目录中,如果文件太多不好管理,需要划分子目录时,也 必须(MUST) 继续遵守根据业务逻辑划分的原则,划分子业务。如:下面例子中的subbiz1

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

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

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

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

遇到确实是一个业务整体,无法划分子业务时, 允许(MAY) 将非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
    ......

包项目目录结构划分

包项目的${root}目录结构划分遵循${root}目录结构划分

包项目src目录结构划分

是实现某个独立功能,有复用价值的代码集。按照通常的理解,一个包项目不应该特别复杂。

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

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

常用目录

一级目录

直接置于${root}下的目录称作一级目录。一级目录 必须(MUST) 具有某种职能属性。

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

src

src目录用于存放开发时源文件,发布时 必须(MUST) 被删除。

dep

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

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

更多关于的内容请参考 包结构规范

tool

tool目录用于存放开发时或构建阶段使用的工具。该目录在发布时 必须(MUST) 被删除。

test

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

doc

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

entry

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

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

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

多页面项目通常页面入口文件较多, 可以(SHOULD) 统一放在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

asset目录用于存放用于线上访问的静态资源。

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

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

资源目录

资源类型命名的目录称作资源目录资源目录 不允许(MUST NOT) 直接置于${root}下。

js

js目录可用于存放js资源文件(包含可编译成jscoffeescript等语言)。js文件后缀名 必须(MUST) 为.js,coffeescript文件后缀名 必须(MUST) 为.coffee。

js目录内 必须(MUST) 存放js资源文件,但js资源文件不一定(MAY NOT)存放于js目录下:

  1. 对于src目录,js资源文件 不允许(MUST NOT) 存放于js目录下。
  2. 对于asset目录,js资源文件 可以(SHOULD) 存放于js目录下,视构建行为决定。
  3. 对于其他一级目录内,js资源文件 可以(SHOULD) 不存放于js目录下。

css

css目录可用于存放css资源文件(包含lesssass等动态样式表语言)。css文件后缀名 必须(MUST) 为.css,less文件后缀名 必须(MUST).less

css目录内 必须(MUST) 存放css资源文件,但css资源文件不一定(MAY NOT)存放于css目录下:

  1. 对于src目录,css资源文件 可以(SHOULD) 存放于业务目录下,也 可以(SHOULD) 存放于css目录下。
  2. 对于asset目录,css资源文件 可以(SHOULD) 存放于css目录下,视构建行为决定。
  3. 对于其他一级目录内,css资源文件 可以(SHOULD) 不存放于css目录下。

关于css引用图片的位置说明,请参考img章节。

img

img目录可用于存放图片资源文件。包括页面直接引用的图片与css引用图片。常见的图片资源有gif/jpg/png/svg/bmp等。

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

对于页面直接引用的图片:

  1. 被多页面引用的图片 应该(SHOULD) 放在${root}/src/common/img目录下。
  2. 单一页面引用的图片 应该(SHOULD) 放在./img目录下,.代表当前页面所在的目录。

tpl

tpl目录可用于存放template资源文件。template资源文件后缀名 可以(SHOULD).html.tpl

通常,对于RIA系统,template资源文件采用.html后缀使其能够被xhr加载。

font

font目录可用于存放字体资源文件。常见的字体资源有tff/woff/svg等。

swf

swf目录可用于存放flash资源文件。flash资源文件 不允许(MUST NOT) 置于img目录中。

业务目录

common

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

FAQ

为啥biz下面没资源类型目录了?

如果在biz下继续划分资源目录,代码的结构可能就是这样子了:

${root}/
    src/
        biz1/
            js/
                list.js

当我们需要使用list.js的时候,必须写如下的代码:require("../biz1/js/list"),但是从逻辑上说,更合理的写法应该是require("../biz1/list")。因此我们不推荐在biz下面对源代码资源划分目录。