百度Baidu EFE team的前端規範——項目目錄結構規範

標籤：

項目目錄結構規範 簡介

該文檔主要的設計目標是項目開發的目錄結構保持一致，使容易理解並方便構建與管理。

編撰

李玉北、erik、黃後錦、王楊、張立理、趙雷、陳新樂、劉愷華。

本文檔由商業運營體系前端技術組審校發布。

要求

在本文檔中，使用的關鍵字會以中文+括弧包含的關鍵字英文表示：必須(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下面對原始碼資源劃分目錄。

百度Baidu EFE team的前端規範——項目目錄結構規範