项目目录结构规范

Question

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

要求

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

规范说明约定

以下规范文档中：

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

资源分类

资源分成两大类：

1. 源代码资源：指开发者编写的源代码，包括js、html、css、template等。
2. 内容资源：指希望做为内容提供给访问者的资源，包括图片、字体、flash、pdf等。

目录命名原则

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

目录划分

${root}目录结构划分

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

常用的目录有src、doc、dep、test等。详细请参考一级目录详细说明

${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) 命名为common。common目录做为业务公共资源的目录，也视如业务目录。

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

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

${root}/
  src/
    foo.js

业务目录划分原则

1. JS资源 不允许(MUST NOT) 按资源类型划分目录， 必须(MUST) 按业务逻辑划分目录。JS资源应直接置于业务目录下。即：业务目录下不允许出现js目录。
2. 除JS资源外的源文件资源，当资源数量较多时，为方便管理， 允许(SHOULD) 按资源类型划分目录。即：业务目录下允许出现css、tpl目录。
3. 内容资源 允许(SHOULD) 按资源类型划分目录。即：业务目录下允许出现img、swf、font目录。
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.sh，build.xml，Makefile，Gruntfile等等.

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资源文件（包含可编译成js的coffeescript等语言）。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资源文件（包含less，sass等动态样式表语言）。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下面对源代码资源划分目录。