简介
该文档主要的设计目标是项目开发的目录结构保持一致，使容易理解并方便构建与管理。
编撰
李玉北、erik、黄后锦、王杨、张立理、赵雷、陈新乐、刘恺华。
本文档由商业运营体系前端技术组审校发布。
要求
在本文档中，使用的关键字会以中文+括号包含的关键字英文表示：必须(MUST)。关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"被定义在rfc2119中。
规范说明约定
以下规范文档中：
- 项目包含但不限于业务项目和包项目。
- ${root}表示项目的根目录。
资源分类
资源分成两大类：
- 源代码资源：指开发者编写的源代码，包括js、html、css、template等。
- 内容资源：指希望做为内容提供给访问者的资源，包括图片、字体、flash、pdf等。
目录命名原则
-
简洁。有习惯性缩写的单词 必须(MUST) 采用容易理解的缩写。如：源代码目录使用src，不使用source。下面是更多例子：
- img: 图片。 不允许(MUST NOT) 使用image、images、imgs等。
- js: javascript脚本。 不允许(MUST NOT) 使用script、scripts等。
- css: 样式表。 不允许(MUST NOT) 使用style、styles等。
- swf: flash。 不允许(MUST NOT) 使用flash等。
- src: 源文件目录。 不允许(MUST NOT) 使用source等。
- dep: 引入的第三方依赖包目录。 不允许(MUST NOT) 使用lib、library、dependency等。
- 不允许(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
业务目录划分原则
- JS资源不允许(MUST NOT) 按资源类型划分目录， 必须(MUST) 按业务逻辑划分目录。JS资源应直接置于业务目录下。即：业务目录下不允许出现js目录。
- 除JS资源外的源文件资源，当资源数量较多时，为方便管理， 允许(SHOULD) 按资源类型划分目录。即：业务目录下允许出现css、tpl目录。
- 内容资源允许(SHOULD) 按资源类型划分目录。即：业务目录下允许出现img、swf、font目录。
- 业务目录中，如果文件太多不好管理，需要划分子目录时，也 必须(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目录下：
- 对于src目录，js资源文件 不允许(MUST NOT) 存放于js目录下。
- 对于asset目录，js资源文件 可以(SHOULD) 存放于js目录下，视构建行为决定。
- 对于其他一级目录内，js资源文件 可以(SHOULD) 不存放于js目录下。
css
css目录可用于存放css资源文件（包含less，sass等动态样式表语言）。css文件后缀名 必须(MUST) 为.css，less文件后缀名 必须(MUST) 为.less。
css目录内 必须(MUST) 存放css资源文件，但css资源文件不一定（MAY NOT）存放于css目录下：
- 对于src目录，css资源文件 可以(SHOULD) 存放于业务目录下，也 可以(SHOULD) 存放于css目录下。
- 对于asset目录，css资源文件 可以(SHOULD) 存放于css目录下，视构建行为决定。
- 对于其他一级目录内，css资源文件 可以(SHOULD) 不存放于css目录下。
关于css引用图片的位置说明，请参考img章节。
img
img目录可用于存放图片资源文件。包括页面直接引用的图片与css引用图片。常见的图片资源有gif/jpg/png/svg/bmp等。
对于css引用的图片， 必须(MUST) 放在./img目录下，.代表当前css资源所在的目录。
对于页面直接引用的图片：
- 被多页面引用的图片 应该(SHOULD) 放在${root}/src/common/img目录下。
- 单一页面引用的图片 应该(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下面对源代码资源划分目录。
- 本文固定链接: https://www.zxbcw.cn/post/4318/
- 转载请注明：必须在正文中标注并保留原文链接
- QQ群： PHP高手阵营官方总群(344148542)
- QQ群： Yii2.0开发(304864863)