項目目錄結構規範

時間  2019-11-10
標籤 項目 目錄 結構 規範 简体版
原文   原文鏈接

轉載：原地址javascript

簡介

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

編撰

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

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

要求

在本文檔中，使用的關鍵字會以中文+括號包含的關鍵字英文表示：必須(MUST)。關鍵字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"被定義在rfc2119中。java

規範說明約定

如下規範文檔中：git

  1. 項目包含但不限於業務項目和包項目。
  2. ${root}表示項目的根目錄。

資源分類

資源分紅兩大類：github

  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}下。json

經常使用的目錄有src、doc、dep、test等。詳細請參考一級目錄詳細說明sass

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

業務項目目錄結構劃分

業務項目的${root}目錄結構劃分遵循${root}目錄結構劃分。less

項目代號

業務項目 能夠(SHOULD) 爲項目起一個代號名稱。代號名稱 必須(MUST) 爲一個單詞，不宜過長。例：北斗的項目代號爲triones，哥倫布的項目代號爲clb，百度錦囊的項目代號爲jn。項目代號有利於區分不一樣項目，爲將來項目之間的重用留下擴展的後路。

在項目開發時，一般會使用以下加載器配置，將項目代號指向src。

javascript{
    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下面對源代碼資源劃分目錄。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程