项目目录结构规范

简介

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

编撰

李玉北、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等。详细请参考一级目录详细说明

  1. ${root}/
  2. src/
  3. test/
  4. doc/
  5. dep/
  6. ...

业务项目目录结构划分

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

项目代号

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

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

  1. {
  2. baseUrl: '${docroot}',
  3. paths: {
  4. 'triones': 'src'
  5. }
  6. }

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

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

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

  1. ${root}/
  2. src/
  3. common/
  4. biz1/
  5. subbiz1/
  6. subbiz2/
  7. biz2/

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

  1. ${root}/
  2. src/
  3. foo.js

业务目录划分原则

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

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

  1. biz1/
  2. img/
  3. add_button.png
  4. add.js
  5. add.tpl.html
  6. add.css

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

  1. biz2/
  2. subbiz1/
  3. list.js
  4. list.tpl.html
  5. list.css
  6. subbiz2/

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

  1. biz1/
  2. css/
  3. add.css
  4. edit.css
  5. remove.css
  6. img/
  7. add_button.png
  8. tpl/
  9. add.html
  10. edit.html
  11. remove.html
  12. add.js
  13. edit.js
  14. remove.js

源文件资源内容资源请参考资源分类章节,常用资源目录请参考资源目录章节,常用业务目录请参考业务目录章节。

业务项目目录划分示例

  1. ${root}/
  2. src/
  3. common/
  4. img/
  5. sprites.png
  6. logo.png
  7. conf.js
  8. layout.css
  9. biz1/
  10. img/
  11. add_button.png
  12. add.js
  13. add.tpl.html
  14. add.less
  15. biz2/
  16. subbiz1/
  17. list.js
  18. list.tpl.html
  19. list.css
  20. subbiz2/
  21. dep/
  22. er/
  23. src/
  24. test/
  25. esui/
  26. src/
  27. test/
  28. test/
  29. doc/
  30. index.html
  31. main.html
  32. ......

包项目目录结构划分

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

包项目src目录结构划分

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

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

  1. ${root}/
  2. src/
  3. css/
  4. img/
  5. sprites.png
  6. table.css
  7. button.css
  8. select.css
  9. main.js
  10. Control.js
  11. InputControl.js
  12. Button.js
  13. Table.js
  14. Select.js
  15. test/
  16. doc/
  17. package.json
  18. ...

常用目录

一级目录

直接置于${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}目录下。

  1. ${root}/
  2. src/
  3. common/
  4. conf.js
  5. card/
  6. gold/
  7. message/
  8. index.html
  9. main.html
  10. ......

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

  1. ${root}/
  2. src/
  3. common/
  4. conf.js
  5. card/
  6. gold/
  7. message/
  8. entry/
  9. card.html
  10. gold.html
  11. message.html
  12. ......

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

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

  1. output/
  2. asset/
  3. js/
  4. css/
  5. tpl/
  6. img/
  7. index.html
  8. main.html

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

  1. output/
  2. card/
  3. asset/
  4. js/
  5. css/
  6. img/
  7. index.html
  8. gold/
  9. asset/
  10. js/
  11. css/
  12. img/
  13. index.html

asset

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

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

  1. ${root}/
  2. asset/
  3. js/
  4. loader.js
  5. build.js
  6. css/
  7. common.css
  8. img/
  9. tpl/
  10. build.tpl.html
  11. img/
  12. ...

资源目录

资源类型命名的目录称作资源目录资源目录 不允许(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下继续划分资源目录,代码的结构可能就是这样子了:

  1. ${root}/
  2. src/
  3. biz1/
  4. js/
  5. list.js

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