specification
Kissy Cake 的目录规范首先会有两个基础目录：src 和 build
ROOT
├── abc.json
├── build/
└── src/
分别存放源代码和构建后的代码；build 目录里的内容由ABC工具通过 src 中的内容生成，开发者无需写入；所以这里我们详细来看 src 目录。
src 目录会提供几套目录结构，而每套目录结构根据业务中不同 Assets 资源的作用和定位方式，在设计上到都抽离出以下4个核心目录：
这4个核心目录的作用和关系如下表：
<tbody>
<tr>
<td>page</td>
<td>应用页面的资源</td>
<td>YES</td>
<td>NO</td>
<td>widget, utils</td>
<td>YES</td>
</tr>
<tr>
<td>widget</td>
<td>全应用公共组件资源</td>
<td>YES</td>
<td>page</td>
<td>utils</td>
<td>YES</td>
</tr>
<tr>
<td>common</td>
<td>全应用可被直接引用的通用资源</td>
<td>YES</td>
<td>NO</td>
<td>utils</td>
<td>YES</td>
</tr>
<tr>
<td>utils</td>
<td>应用内跨页面, 跨组件共享的工具模块</td>
<td>NO</td>
<td>YES</td>
<td>NO</td>
<td>NO (但用线上合并必须配置)</td>
</tr>
</tbody>
| 分类名 | 说明 | 被use | 被require | 跨锁 require | 线上包配置 |
|---|
开发者应理解4大目录约定，并通过分析所开发应用的需要，将合适的资源文件归属到合适的目录中；如开发者建立其他平级目录，ABC 将对此目录及里面的文件不做任务处理；
这里强调一下整个目录的设计宗旨，我们为开发者考虑到几个情况，所以建立了4个不同的目录，开发者并不需要在每个项目中都使用到所有的目录，而是根据自身的需求来选择目录，并将对应的资源文件放入到合适的目录中。
整体的目录结构如下图:
ROOT
├── build
│ ├── common (包目录)
│ │ ├── header-min.js
│ │ ├── header.css
│ │ ├── header.js
│ │ ├── package-config-min.js
│ │ └── package-config.js
│ ├── pages
│ │ ├── home
│ │ │ └── page (包目录)
│ │ │ ├── index-min.css
│ │ │ ├── index.css
│ │ │ ├── init-min.js
│ │ │ └── init.js
│ │ └── list
│ │ └── page (包目录)
│ │ ├── index-min.css
│ │ ├── index.css
│ │ ├── init-min.js
│ │ └── init.js
│ └── widget (包目录)
│ ├── navbar
│ │ ├── index-min.css
│ │ ├── index.css
│ │ ├── init-min.js
│ │ └── init.js
│ └── sidebar
│ ├── index-min.css
│ ├── index.css
│ ├── init-min.js
│ └── init.js
├── src
│ ├── common (包目录)
│ │ ├── mods
│ │ │ ├── _s1.sass
│ │ │ └── m1.js
│ │ ├── header.css
│ │ ├── header.js
│ │ └── package-config.js
│ ├── pages
│ │ ├── home
│ │ │ └── page (包目录)
│ │ │ ├── images
│ │ │ ├── mods
│ │ │ │ └── _base.sass
│ │ │ ├── index.scss
│ │ │ └── init.js
│ │ └── list
│ │ └── page (包目录)
│ │ ├── images
│ │ ├── mods
│ │ │ └── _base.sass
│ │ ├── index.scss
│ │ └── init.js
│ ├── utils (包目录，线下包)
│ │ ├── data.js
│ │ ├── dpl.sass
│ │ ├── reset.sass
│ │ └── sample.js
│ └── widget (包目录)
│ ├── navbar
│ │ ├── images
│ │ ├── mods
│ │ │ └── _base.sass
│ │ ├── index.scss
│ │ └── init.js
│ └── sidebar
│ ├── images
│ ├── mods
│ │ └── _base.sass
│ ├── index.scss
│ └── init.js
├── Gruntfile.js
├── abc.json
└── package.json
在详细的介绍 src 下4个主要目录之前，先对目前ABC支持的资源合并方式做个介绍；
这里分两种：线上合并和线下合并：
业务需要用怎么样的合并方式，这个问题在不同的环境不同的业务会有不同的答案；而ABC提供了三种文件合并方式：
<tr>
<td>混合合并 (B)</td>
<td>线下合并</td>
<td>线上合并</td>
<td>Kissy 1.3 支持</td>
</tr>
<tr>
<td>全线下合并 (C)</td>
<td>线下合并</td>
<td>线下合并</td>
<td> </td>
</tr>
</tbody>
| 方案名称 | 锁目录内文件依赖 | 跨锁目录文件依赖 | 备注 |
|---|---|---|---|
| 全线上合并 (A) | 线上合并 | 线上合并 | Kissy 1.3 支持 |
锁目录: 就是图三中带有锁型图标标识的目录，实际目录中没什么特别，这里是为了能更简单的描述出合并规则而叫上的标注；“红色文件”是上图中文件名为红色的文件，在任何打包文件中，红色文件都是作为可以被外部
KISSY.use的入口文件，即在线上 KISSY 的 package-config 文件中描述，其他非入口文件则不描述，所以无法被use；
进一步对上述规则举例说明：
例如：list.js 文件依赖 list-control.js 文件，那么在线上 KISSY 的 package-config 文件中会描述出来 list require list-control，list.js 和 list-control.js 在CDN上是两个独立的文件；当有 KISSY.use('list') 时，将通过 CDN combo 功能将 list-control.js,list.js 这两个文件合并加载进来；
例如：list.js 文件依赖 list-control.js 文件 list-control.js 会在发布到CDN上前 合并到 list.js；当有 KISSY.use(list)时，加载合并后 list.js；
例如：list.js 文件依赖 widget/sidebar/ 和 widget/toolbar/ 文件，那么在线上 KISSY 的 package-config 文件中会描述出来list require [sidebar, toolbar]，list.js 和 两个 widget组件发布到CDN上是两个独立的文件；当有Kissy.use list时，将通过CDN combo功能将 sidebar 和 toolbar 合并在一起同时加载过来；
例如：page/list 文件依赖 widget/sidebar 文件，list.js 和 sidebar.js 会在发布到CDN上前合并为一个文件名为 page/list.js；当有 KISSY.use(list) 时，将加载和并后的 page/list.js；
开发者需要根据自己的想法来选择合并方案，ABC默认推荐A方案，但不同的业务场景，我们提出以下建议，供大家选择时做参考：
- 在 KISSY 版本 < 1.3.0 时，Loader 无法 支持 动态 combo 机制，所以建议采用线下合并，以减少 JS 文件请求数；
- 在 KISSY 版本大于等于 1.3.0 时，Loader 支持 动态 combo 机制，所以建议采用线上合并，在合并连接数同时，也可避免出现物理文件合并带来的模块重复性；
- 当应用是单页面或少量页面，而页面复杂度较高，且公共部分较少的时候，建议使用线下物理文件合并形式，以减少异步 JS 请求过程；
推荐的方案并不适用所有的场景，所以开发者还是需要在理解两种构建方式的优劣后，再结合自身应用环境来选择构建方案。
src
└── pages
├── home
│ └── page
│ ├── images
│ ├── mods
│ │ └── _base.scss
│ ├── index.scss
│ └── init.js
└── list
└── page
├── images
├── mods
│ └── _base.scss
├── index.scss
└── init.js

pages 目录下存放页面级资源，上图为一个典型目录结构，其他目录结构会在某些环节做调整，整体思想上基本相同。
第一级如list 和 home 为页面名称目录，第二级 page 为 KISSY 包配置目录，第三级为页面入口资源和页面内部子模块资源；
除了直接在第三级目录 (page 目录) 下的文件，为入口文件，其他文件将不会在 KISSY 的 package-config 文件中描述；这就意味着 mods 或者其他平级目录下的文件只能通过入口文件的依赖加载到页面，而无能直接被 use 使用。
对于一个页面同时会存在两个版本，建议新建页面，并以页面名称来区分， 如
list有两个版本，你可以新建一个list_v2页面 待稳定之后，
.
└── widget
├── navbar
│ ├── images
│ ├── mods
│ │ └── _base.scss
│ ├── index.scss
│ └── init.js
└── sidebar
├── images
├── mods
│ └── _base.scss
├── index.scss
└── init.jswidget 目录下存放应用级组件，上图为一个典型目录结构，其他目录结构会在某些环节做调整，整体思想上基本相同。
第一级如 sidebar 和 toolbar 为组件名称目录，第二级为组件入口资源和组件内部子模块资源；
除了直接在第二级目录下的文件，即红色文件名的，为入口文件，其他文件将不会在KISSY的 package-config 文件中描述；这就意味着mod或者其他平级目录下的文件只能通过入口文件的依赖加载到页面，而无法直接被use使用。
src
└── common
├── mods
│ ├── _s1.sass
│ └── m1.js
├── header.css
├── header.js
└── package-config.jscommon 目录下存放应用级公共资源文件，上图为一个典型目录结构，其他目录结构会在某些环节做调整，整体思想上基本相同。
第一级为组件入口资源和组件内部子模块资源；
除了直接在第一级目录下的文件为入口文件，其他文件将不会在 KISSY 的 package-config 文件中描述；这就意味着 mod 或者其他平级目录下的文件只能通过入口文件的依赖加载到页面，而无法直接被 use 使用。
.
└── utils
├── data.js
├── dpl.sass
├── reset.sass
└── sample.js
utils 目录下存放第三方资源文件，上图为一个典型目录结构，其他目录结构会在某些环节做调整，整体思想上基本相同。
utils 目录下文件中的资源只能通过 require 在线下合并到其他入口文件中，utils 下的文件本身不会构建到 build 目录，也不会发送到 CDN。
(end.)