百度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下面对源代码资源划分目录。

时间： 2024-10-14 03:14:19

百度Baidu EFE team的前端规范——项目目录结构规范的相关文章

学习一份百度的项目目录结构规范

项目目录结构规范 简介 该文档主要的设计目标是项目开发的目录结构保持一致,使容易理解并方便构建与管理. 编撰 李玉北.erik.黄后锦.王杨.张立理.赵雷.陈新乐.刘恺华. 本文档由商业运营体系前端技术组审校发布. 要求 在本文档中,使用的关键字会以中文+括号包含的关键字英文表示:必须(MUST).关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT"

nodejs项目目录结构规范

参考: https://github.com/jifeng/node-app dispatch.js 主进程文件 worker.js 工作进程 app.js 应用 routes.js url路由表 package.json 依赖模块 config.js or config/ 配置文件 controllers/ 业务逻辑相关 views/ 试图模板 common/ 跟业务相关的公共模块 proxy/ 数据访问代理层 lib/ 跟业务无关的公共模块 assets/ images|scripts|st

Day4 - 迭代器&生成器、装饰器、Json & pickle 数据序列化、软件目录结构规范

---恢复内容开始--- 本节内容 迭代器&生成器 装饰器 Json & pickle 数据序列化 软件目录结构规范 作业:ATM项目开发 1.列表生成式,迭代器&生成器 列表生成式 需求:列表a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],要求把列表里的每个值加1 1 a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 2 b = [] 3 for i in a: 4 b.append(i+1) 5 a = b 6 print(a) 普通青

关于软件目录结构规范———（转自Alex Li）

软件目录结构规范 为什么要设计好目录结构? "设计项目目录结构",就和"代码编码风格"一样,属于个人风格问题.对于这种风格上的规范,一直都存在两种态度: 一类同学认为,这种个人风格问题"无关紧要".理由是能让程序work就好,风格问题根本不是问题. 另一类同学认为,规范化能更好的控制程序结构,让程序具有更高的可读性. 我是比较偏向于后者的,因为我是前一类同学思想行为下的直接受害者.我曾经维护过一个非常不好读的项目,其实现的逻辑并不复杂,但是却耗费

python学习day4软件目录结构规范

为什么要设计好目录结构? 参考:http://www.cnblogs.com/alex3714/articles/5765046.html "设计项目目录结构",就和"代码编码风格"一样,属于个人风格问题.对于这种风格上的规范,一直都存在两种态度: 1.一类同学认为,这种个人风格问题"无关紧要".理由是能让程序work就好,风格问题根本不是问题: 2.另一类同学认为,规范化能更好的控制程序结构,让程序具有更高的可读性: 我是比较偏向于后者的,因为

python 软件目录结构规范

为什么要设计好目录结构? "设计项目目录结构",就和"代码编码风格"一样,属于个人风格问题.对于这种风格上的规范,一直都存在两种态度: 一类同学认为,这种个人风格问题"无关紧要".理由是能让程序work就好,风格问题根本不是问题. 另一类同学认为,规范化能更好的控制程序结构,让程序具有更高的可读性. 我是比较偏向于后者的,因为我是前一类同学思想行为下的直接受害者.我曾经维护过一个非常不好读的项目,其实现的逻辑并不复杂,但是却耗费了我非常长的时间去

Laravel项目目录结构说明

Laravel项目目录结构说明: |- vendor 目录包含你的 Composer 依赖模块及laravel框架. |- bootstrap 目录包含几个框架启动跟自动加载配置的文件. |- app.php |- autoload.php |- config 应用程序的配置文件. |- database 数据库迁移与数据填充文件. |- public 项目web入口和静态资源文件 (图片.js.css,字体等等). |-index.php 入口 |- resources 目录包含视图.原始的资

软件目录结构规范

软件目录结构规范 为什么要设计好目录结构? "设计项目目录结构",就和"代码编码风格"一样,属于个人风格问题.对于这种风格上的规范,一直都存在两种态度: 一类同学认为,这种个人风格问题"无关紧要".理由是能让程序work就好,风格问题根本不是问题. 另一类同学认为,规范化能更好的控制程序结构,让程序具有更高的可读性. 我是比较偏向于后者的,因为我是前一类同学思想行为下的直接受害者.我曾经维护过一个非常不好读的项目,其实现的逻辑并不复杂,但是却耗费

python软件目录结构规范

软件目录结构规范 软件开发规范 一.为什么要设计好目录结构? 1.可读性高: 不熟悉这个项目的代码的人,一眼就能看懂目录结构,知道程序启动脚本是哪个,测试目录在哪儿,配置文件在哪儿等等.从而非常快速的了解这个项目. 2.可维护性高: 定义好组织规则后,维护者就能很明确地知道,新增的哪个文件和代码应该放在什么目录之下.这个好处是,随着时间的推移,代码/配置的规模增加,项目结构不会混乱,仍然能够组织良好. 二.目录组织方式 关于如何组织一个较好的Python工程目录结构,已经有一些得到了共识的目录结