項(xiàng)目目錄結(jié)構(gòu)規(guī)范

目錄命名原則

簡(jiǎn)潔。有習(xí)慣性縮寫(xiě)的單詞 必須(MUST) 采用容易理解的縮寫(xiě)。如：源代碼目錄使用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) 使用復(fù)數(shù)形式。如：imgs、docs是不被允許的。

目錄劃分

${root}目錄結(jié)構(gòu)劃分

在${root}下，目錄結(jié)構(gòu) 必須(MUST) 按照職能進(jìn)行劃分， 不允許(MUST NOT) 將資源類型或業(yè)務(wù)邏輯劃分的目錄直接置于${root}下。

常用的目錄有src、doc、dep、test等。詳細(xì)請(qǐng)參考一級(jí)目錄詳細(xì)說(shuō)明

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

業(yè)務(wù)項(xiàng)目目錄結(jié)構(gòu)劃分

業(yè)務(wù)項(xiàng)目的${root}目錄結(jié)構(gòu)劃分遵循${root}目錄結(jié)構(gòu)劃分。

業(yè)務(wù)項(xiàng)目 可以(SHOULD) 為項(xiàng)目起一個(gè)代號(hào)名稱。代號(hào)名稱 必須(MUST) 為一個(gè)單詞，不宜過(guò)長(zhǎng)。例：北斗的項(xiàng)目代號(hào)為triones，哥倫布的項(xiàng)目代號(hào)為clb，百度錦囊的項(xiàng)目代號(hào)為jn。項(xiàng)目代號(hào)有利于區(qū)分不同項(xiàng)目，為未來(lái)項(xiàng)目之間的重用留下擴(kuò)展的后路。

在項(xiàng)目開(kāi)發(fā)時(shí)，通常會(huì)使用如下加載器配置，將項(xiàng)目代號(hào)指向src。

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

業(yè)務(wù)項(xiàng)目的src目錄內(nèi)，絕大多數(shù)情況 應(yīng)當(dāng)(SHOULD) 根據(jù)業(yè)務(wù)邏輯劃分目錄結(jié)構(gòu)。劃分出的子目錄（比如例子中的biz1）我們稱為業(yè)務(wù)目錄。

src下 必須(MUST) 只包含業(yè)務(wù)目錄與common目錄。業(yè)務(wù)公共資源 必須(MUST) 命名為common。common目錄做為業(yè)務(wù)公共資源的目錄，也視如業(yè)務(wù)目錄。

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

較小規(guī)模的業(yè)務(wù)項(xiàng)目（如投放端），src目錄允許視如業(yè)務(wù)目錄，直接按照業(yè)務(wù)目錄劃分原則劃分目錄結(jié)構(gòu)。

${root}/ src/ foo.js

JS資源 不允許(MUST NOT) 按資源類型劃分目錄， 必須(MUST) 按業(yè)務(wù)邏輯劃分目錄。JS資源應(yīng)直接置于業(yè)務(wù)目錄下。即：業(yè)務(wù)目錄下不允許出現(xiàn)js目錄。

除JS資源外的源文件資源，當(dāng)資源數(shù)量較多時(shí)，為方便管理， 允許(SHOULD) 按資源類型劃分目錄。即：業(yè)務(wù)目錄下允許出現(xiàn)css、tpl目錄。

內(nèi)容資源 允許(SHOULD) 按資源類型劃分目錄。即：業(yè)務(wù)目錄下允許出現(xiàn)img、swf、font目錄。

業(yè)務(wù)目錄中，如果文件太多不好管理，需要?jiǎng)澐肿幽夸洉r(shí)，也 必須(MUST) 繼續(xù)遵守根據(jù)業(yè)務(wù)邏輯劃分的原則，劃分子業(yè)務(wù)。如：下面例子中的subbiz1。

通常，對(duì)于一個(gè)業(yè)務(wù)目錄， 鼓勵(lì)(SHOULD) 將業(yè)務(wù)相關(guān)的源文件資源都直接置于業(yè)務(wù)目錄下。

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

業(yè)務(wù)目錄下源文件資源數(shù)量較多時(shí)，我們第一直覺(jué)應(yīng)該是：是否業(yè)務(wù)劃分不夠細(xì)？是否應(yīng)該劃分子業(yè)務(wù)，建立子業(yè)務(wù)目錄？

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

遇到確實(shí)是一個(gè)業(yè)務(wù)整體，無(wú)法劃分子業(yè)務(wù)時(shí)， 允許(MAY) 將非JS資源按資源類型劃分目錄進(jìn)行管理。

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

源文件資源和內(nèi)容資源請(qǐng)參考資源分類章節(jié)，常用資源目錄請(qǐng)參考資源目錄章節(jié)，常用業(yè)務(wù)目錄請(qǐng)參考業(yè)務(wù)目錄章節(jié)。

${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 ......

包項(xiàng)目目錄結(jié)構(gòu)劃分

包項(xiàng)目的${root}目錄結(jié)構(gòu)劃分遵循${root}目錄結(jié)構(gòu)劃分。

包是實(shí)現(xiàn)某個(gè)獨(dú)立功能，有復(fù)用價(jià)值的代碼集。按照通常的理解，一個(gè)包項(xiàng)目不應(yīng)該特別復(fù)雜。

所以，包可視如一個(gè)不太復(fù)雜的業(yè)務(wù)，其src下的劃分原則與業(yè)務(wù)項(xiàng)目的業(yè)務(wù)目錄劃分原則保持一致。

${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 ...

常用目錄

一級(jí)目錄

直接置于${root}下的目錄稱作一級(jí)目錄。一級(jí)目錄 必須(MUST) 具有某種職能屬性。

除了下面列舉的一些常見(jiàn)目錄之外，${root}下面也可以放置一些跟項(xiàng)目發(fā)布相關(guān)的文件，例如build.sh，build.xml，Makefile，Gruntfile等等.

src目錄用于存放開(kāi)發(fā)時(shí)源文件，發(fā)布時(shí) 必須(MUST) 被刪除。

dep目錄用于存放項(xiàng)目引入依賴的第三方包。該目錄下的內(nèi)容通過(guò)平臺(tái)工具管理，項(xiàng)目開(kāi)發(fā)人員 不允許(MUST NOT) 更改dep目錄下第三方包的任何內(nèi)容。

當(dāng)項(xiàng)目需要修改引入的第三方代碼時(shí)，第三方包應(yīng)將源碼直接置于${root}/src目錄下，規(guī)則見(jiàn)該目錄下的規(guī)定。

更多關(guān)于包的內(nèi)容請(qǐng)參考 包結(jié)構(gòu)規(guī)范

tool目錄用于存放開(kāi)發(fā)時(shí)或構(gòu)建階段使用的工具。該目錄在發(fā)布時(shí) 必須(MUST) 被刪除。

test目錄用于存放測(cè)試用例以及開(kāi)發(fā)階段的模擬數(shù)據(jù)。該目錄在發(fā)布時(shí) 必須(MUST) 被刪除。

doc目錄用于存放項(xiàng)目文檔。項(xiàng)目文檔可能是開(kāi)發(fā)者維護(hù)的文檔，也可能是通過(guò)工具生成的文檔。

entry目錄用于存放項(xiàng)目的頁(yè)面入口文件，通常是上線后可被直接訪問(wèn)的靜態(tài)頁(yè)面。

RIA項(xiàng)目通常會(huì)包含較少的頁(yè)面入口文件，常見(jiàn)的是main.html，這些文件 可以(SHOULD) 直接放在${root}目錄下。

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

多頁(yè)面項(xiàng)目通常頁(yè)面入口文件較多， 可以(SHOULD) 統(tǒng)一放在entry目錄中，按業(yè)務(wù)邏輯命名。

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

項(xiàng)目在發(fā)布的時(shí)候，構(gòu)建工具可以頁(yè)面入口文件為入口進(jìn)行分析和編譯。

RIA項(xiàng)目經(jīng)過(guò)構(gòu)建工具編譯后，目錄結(jié)構(gòu)可能如下：

output/ asset/ js/ css/ tpl/ img/ index.html main.html

多頁(yè)面項(xiàng)目經(jīng)過(guò)構(gòu)建工具編譯后，目錄結(jié)構(gòu)可能如下：

output/ card/ asset/ js/ css/ img/ index.html gold/ asset/ js/ css/ img/ index.html

asset目錄用于存放用于線上訪問(wèn)的靜態(tài)資源。

通常構(gòu)建工具會(huì)對(duì)src目錄和dep目錄下的資源進(jìn)行分析、合并與壓縮等，生成到asset目錄下。所以該目錄盡量避免手工管理。下面是一個(gè)構(gòu)建工具生成后的asset目錄示例：

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

資源目錄

按資源類型命名的目錄稱作資源目錄。資源目錄 不允許(MUST NOT) 直接置于${root}下。

js目錄可用于存放js資源文件（包含可編譯成js的coffeescript等語(yǔ)言）。js文件后綴名 必須(MUST) 為.js，coffeescript文件后綴名 必須(MUST) 為.coffee。

js目錄內(nèi) 必須(MUST) 存放js資源文件，但js資源文件不一定（MAY NOT）存放于js目錄下：

對(duì)于src目錄，js資源文件 不允許(MUST NOT) 存放于js目錄下。

對(duì)于asset目錄，js資源文件 可以(SHOULD) 存放于js目錄下，視構(gòu)建行為決定。

對(duì)于其他一級(jí)目錄內(nèi)，js資源文件 可以(SHOULD) 不存放于js目錄下。

css目錄可用于存放css資源文件（包含less，sass等動(dòng)態(tài)樣式表語(yǔ)言）。css文件后綴名 必須(MUST) 為.css，less文件后綴名 必須(MUST) 為.less。

css目錄內(nèi) 必須(MUST) 存放css資源文件，但css資源文件不一定（MAY NOT）存放于css目錄下：

對(duì)于src目錄，css資源文件 可以(SHOULD) 存放于業(yè)務(wù)目錄下，也 可以(SHOULD) 存放于css目錄下。

對(duì)于asset目錄，css資源文件 可以(SHOULD) 存放于css目錄下，視構(gòu)建行為決定。

對(duì)于其他一級(jí)目錄內(nèi)，css資源文件 可以(SHOULD) 不存放于css目錄下。

關(guān)于css引用圖片的位置說(shuō)明，請(qǐng)參考img章節(jié)。

img目錄可用于存放圖片資源文件。包括頁(yè)面直接引用的圖片與css引用圖片。常見(jiàn)的圖片資源有g(shù)if/jpg/png/svg/bmp等。

對(duì)于css引用的圖片， 必須(MUST) 放在./img目錄下，.代表當(dāng)前css資源所在的目錄。

對(duì)于頁(yè)面直接引用的圖片：

被多頁(yè)面引用的圖片 應(yīng)該(SHOULD) 放在${root}/src/common/img目錄下。

單一頁(yè)面引用的圖片 應(yīng)該(SHOULD) 放在./img目錄下，.代表當(dāng)前頁(yè)面所在的目錄。

tpl目錄可用于存放template資源文件。template資源文件后綴名 可以(SHOULD) 為.html或.tpl。

通常，對(duì)于RIA系統(tǒng)，template資源文件采用.html后綴使其能夠被xhr加載。

font目錄可用于存放字體資源文件。常見(jiàn)的字體資源有tff/woff/svg等。

swf目錄可用于存放flash資源文件。flash資源文件 不允許(MUST NOT) 置于img目錄中。

業(yè)務(wù)目錄

common目錄為業(yè)務(wù)公共目錄，用于存放業(yè)務(wù)項(xiàng)目的業(yè)務(wù)公共文件。所以，根據(jù)業(yè)務(wù)邏輯劃分目錄結(jié)構(gòu)時(shí)，業(yè)務(wù)邏輯命名 不允許(MUST NOT) 為common。

FAQ

為啥biz下面沒(méi)資源類型目錄了？

如果在biz下繼續(xù)劃分資源目錄，代碼的結(jié)構(gòu)可能就是這樣子了：

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

當(dāng)我們需要使用list.js的時(shí)候，必須寫(xiě)如下的代碼：require("../biz1/js/list")，但是從邏輯上說(shuō)，更合理的寫(xiě)法應(yīng)該是require("../biz1/list")。因此我們不推薦在biz下面對(duì)源代碼資源劃分目錄。

CSS

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。