项目目录结构规范 - 文章教程

项目目录结构规范

发布于 2020-12-06 字数 13346 浏览 1134 评论 0

该文档主要的设计目标是项目开发的目录结构保持一致,使容易理解并方便构建与管理。

要求

在本文档中,使用的关键字会以中文+括号包含的关键字英文表示:必须(MUST)。关键字”MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”被定义在rfc2119中。

规范说明约定

以下规范文档中:

  1. 项目包含但不限于业务项目包项目
  2. ${root}表示项目的根目录。

资源分类

资源分成两大类:

  1. 源代码资源:指开发者编写的源代码,包括jshtmlcsstemplate等。
  2. 内容资源:指希望做为内容提供给访问者的资源,包括图片字体flashpdf等。

目录命名原则

  1. 简洁。有习惯性缩写的单词 必须(MUST) 采用容易理解的缩写。如:源代码目录使用src,不使用source。下面是更多例子:
    1. img: 图片。 不允许(MUST NOT) 使用imageimagesimgs等。
    2. js: javascript脚本。 不允许(MUST NOT) 使用scriptscripts等。
    3. css: 样式表。 不允许(MUST NOT) 使用stylestyles等。
    4. swf: flash。 不允许(MUST NOT) 使用flash等。
    5. src: 源文件目录。 不允许(MUST NOT) 使用source等。
    6. dep: 引入的第三方依赖包目录。 不允许(MUST NOT) 使用liblibrarydependency等。
  2. 不允许(MUST NOT) 使用复数形式。如:imgsdocs是不被允许的。

目录划分

${root}目录结构划分

在${root}下,目录结构 必须(MUST) 按照职能进行划分, 不允许(MUST NOT)资源类型业务逻辑划分的目录直接置于${root}下。

常用的目录有srcdocdeptest等。详细请参考一级目录详细说明

${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) 命名为commoncommon目录做为业务公共资源的目录,也视如业务目录

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

较小规模的业务项目(如投放端),src目录允许视如业务目录,直接按照业务目录划分原则划分目录结构。

${root}/
  src/
    foo.js

业务目录划分原则

  1. JS资源 不允许(MUST NOT)资源类型划分目录, 必须(MUST)业务逻辑划分目录。JS资源应直接置于业务目录下。即:业务目录下不允许出现js目录。
  2. JS资源外的源文件资源,当资源数量较多时,为方便管理, 允许(SHOULD)资源类型划分目录。即:业务目录下允许出现csstpl目录。
  3. 内容资源 允许(SHOULD)资源类型划分目录。即:业务目录下允许出现imgswffont目录。
  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.shbuild.xmlMakefileGruntfile等等.

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资源文件(包含可编译成jscoffeescript等语言)。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资源文件(包含lesssass等动态样式表语言)。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下面对源代码资源划分目录。

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2583 文章
29 评论
84935 人气
更多

推荐作者

清欢

文章 1 评论 0

贱贱哒

文章 3 评论 0

悸初

文章 2 评论 0

西瓜杏

文章 0 评论 0

各自安好

文章 0 评论 0