Baidu EFE team's front-end specification--project directory structure specification

Introduction to the project directory structure specification

The main design objective of this document is to keep the directory structure of project development consistent, making it easy to understand and easy to build and manage.

Compiled

Li Yu bei, Erik, Huang, breeder, Zhanglili, Lei, Chen Wan, Jacky Lau Hua.

This document is 商业运营体系前端技术组 published by review.

Requirements

In this document, the keywords that are used are expressed in English with the keywords enclosed in parentheses: must (MUST). Keywords ' must ', ' must not ', ' REQUIRED ', ' shall ', ' shall not ', ' should ', ' should not ', ' RECOMMENDED ', ' may ', and ' OPTIONAL ' are defined in R The fc2119.

Specification conventions

In the following specification document:

1. 项目including but not limited to 业务项目 and 包项目 .

2. ${root}Represents 项目 the root directory.

Resource classification

资源Divided into two main categories:

1. 源代码资源: Refers to the source code written by the developer, including,,, js html , and css template so on.

2. 内容资源: Refers to the resources that you want to provide to your visitors, including,,, 图片 字体 , and flash pdf so on.

Directory naming principles

1. Simple. Words that have a habitual abbreviation must (must) be abbreviated with an easy-to-understand abbreviation. Such as: The source code directory src is used, not used source . Here are more examples:

1. imgPicture do not allow (must not) to use image , images , and imgs so on.

2. js: JavaScript script. do not allow (must not) to use script , and scripts so on.

3. css: Style sheet. do not allow (must not) to use style , and styles so on.

4. swf: Flash. do not allow (must not) to use flash etc.

5. src: Source file directory. do not allow (must not) to use source etc.

6. dep: The imported third-party dependency package directory. do not allow (must not) to use lib , library , and dependency so on.

2. do not allow (must not) to use the plural form. such as: imgs , docs is not allowed.

Directory Partitioning

${root} directory Structure Division

Under ${root}, the directory structure must (must) be 职能 divided and not allow (must not) to place 资源类型 or 业务逻辑 partition the directory directly under ${root}.

Commonly used directories are,,, and src doc dep test so on. For more information, please refer to the first level catalogue

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

Business Project directory Structure Division

业务项目${root} directory structure is divided according to ${root} directory structure.

Project Code

A business item can (should) a code name for the project. The code name must (must) be a word, not too long. Example: Beidou project codenamed triones , Columbus Project codenamed clb , Baidu Kam SAC Project code jn . The project designator helps to differentiate between different projects, leaving an extended posterior for reuse between future projects.

When developing a project, the following loader configuration is typically used to point to the project designator src .

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

Partition SRC directory structure according to business logic

业务项目srcdirectory, the vast majority of cases should (should) be based on the partitioning of the 业务逻辑 directory structure. The sub-directories (as in the example biz1 ) we call 业务目录 .

srcUnder must (must) contain only 业务目录 with the common directory. 业务公共资源 must (must) be named common . Directories are common 业务公共资源 also considered as directories 业务目录 .

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

Smaller size 业务项目 (such as on-end), the src catalog allows 业务目录 the directory structure to be partitioned directly according to the Business Directory Division principle.

${root}/Src/foo.js

Business Directory Division principle

1. JS资源do not allow (must not) by 资源类型 dividing the directory, must (must) by 业务逻辑 dividing the directory. JS资源should be placed directly 业务目录 below. That is, 业务目录 the directory is not allowed under js .

2. JS资源In addition 源文件资源 , when the number of resources, for the convenience of management, allow (should) by 资源类型 dividing the directory. That is: 业务目录 under Allow css , tpl directory.

3. 内容资源allow (should) by 资源类型 dividing the directory. That is: 业务目录 under Allow img , swf font directory.

4. 业务目录, if the file too much bad management, need to divide sub-directories, also must (must) continue to abide by 业务逻辑 the principle of division, the demarcation of the business. As in the following example: subbiz1

Usually, for one 业务目录 , encourage (should) to place business-related 源文件资源 directly 业务目录 under.

Biz1/img/add_button.png add.js add.tpl.html Add.css

业务目录源文件资源when the number is large, our first instinct should be: is the business division not thin enough? Should the sub-business be divided and the sub-business directory established?

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

When encountering a business as a whole and unable to divide sub-businesses, allow (May) to be JS资源 managed by non- 资源类型 partitioned catalogs.

Biz1/css/add.css edit.css remove.css img/add_button.png tpl/add.ht ML edit.html remove.html add.js edit.js remove.js

源文件资源and 内容资源 please refer to the Resources section, please refer 资源目录 to the Resource Catalogue section for more information, 业务目录 please refer to the Business Catalogue section for common use.

Business Project Catalog Partitioning Example

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

Package Project directory Structure Division

包项目${root} directory structure is divided according to ${root} directory structure.

Package Project SRC directory structure Division

包is a code set that implements an independent function that has a reusable value. According to the usual understanding, one 包项目 should not be particularly complicated.

Therefore, 包 as a less complex 业务 , the src following division principle and 业务项目 the principle of Business directory division are consistent.

 ${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    &NBSP, ..... 

Common Directory

First Level Directory

${root}The directory that is placed directly below is called 一级目录 . The first-level directory must have some property (must) 职能 .

In addition to some of the common directories listed below, ${root} you can also place some files related to project publishing, such as,,, and build.sh build.xml Makefile Gruntfile so on.

Src

srcThe directory is used to store the source files at development time and must be removed (must) when publishing.

Dep

depDirectories are used to store 项目 third-party packages that introduce dependencies. Content under this directory is managed by the platform tools, and project developers do not allow (must not) to change dep anything in the directory for third-party packages.

When the project needs to modify the introduction of the third-party code, the third-party package should be directly placed in the ${root}/src directory, rules see the provisions of the directory.

For more information 包 please refer to package structure specification

Tool

toolCatalogs are used to store tools used during development or during the build phase. The directory must be deleted (must) when it is published.

Test

testCatalogs are used to store simulation data for test cases and development phases. The directory must be deleted (must) when it is published.

Doc

docThe catalog is used to store project documents. The project document may be a document that is maintained by the developer, or it may be a tool-generated document.

Entry

entryA directory is used to store items 页面入口文件 , usually a static page that can be accessed directly on-line.

RIA项目Usually contain fewer, and it 页面入口文件 is common main.html that these files can (should) be placed directly under the ${root} directory.

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

多页面项目Usually 页面入口文件 more, can be (should) unified in the entry directory, by 业务逻辑 name.

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

When the project is published, the build tool can 页面入口文件 parse and compile the portal.

RIA项目After the build tool has been compiled, the directory structure might look like this:

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

多页面项目After the build tool has been compiled, the directory structure might look like this:

Output/card/asset/js/css/img/index.html gold/asset/ Js/css/img/index.html

Asset

assetA directory is used to hold 线上访问 static resources for use.

Typically, the build tool src dep parses, merges, and compresses resources in directories and directories, and generates them in a asset directory. So this directory avoids manual management as much as possible. Here is an example of the directory after the build tool was built asset :

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

Resource Directory

资源a directory named by type is called 资源目录 . 资源目录 do not allow (must not) to be placed directly under ${root}.

Js

jsDirectories can be used to hold js resource files (including languages that can be compiled js coffeescript ). The js file suffix name must be (must) to. js and the coffeescript文件 suffix must (must) be. Coffee.

jsThe resource file must be (must) stored in js the directory, but the resource file does not js necessarily reside in the js directory:

1. For src directories, js resource files are not allowed (must not) to be stored in the js directory.

2. For asset directories, js resource files can (should) be stored in the js directory, depending on the build behavior.

3. For other 一级目录 , js resource files can (should) not be stored in the js directory.

Css

cssCatalogs can be used to store css资源文件 (include less , sass etc. dynamic stylesheet languages). The css file suffix name must (must) be. CSS, and the less file suffix name must (must) be .less .

cssThe resource file must be (must) stored in css the directory, but the resource file does not css necessarily reside in the css directory:

1. For src a directory, the css resource file can be stored under (should) 业务目录 or (should) in the css directory.

2. For asset directories, css resource files can (should) be stored in the css directory, depending on the build behavior.

3. For other 一级目录 , css resource files can (should) not be stored in the css directory.

For a description of the location of the CSS reference picture, refer to the IMG section.

Img

imgThe directory can be used for storage 图片资源文件 . Include 页面直接引用 pictures and css引用 pictures. Common picture resources have to gif/jpg/png/svg/bmp wait.

For css the referenced picture, it must be placed (must) in the ./img directory, . representing css the directory where the current resource resides.

For 页面直接引用 the Picture:

1. Images that are referenced by multiple pages should (should) be placed in the ${root}/src/common/img directory.

2. A single-page-referenced picture should (should) be placed in the ./img directory, . representing the directory where the current page is located.

Tpl

tplThe directory can be used to hold template resource files. templatethe resource file suffix name can be (should) .html or .tpl .

Typically, for a RIA system, the template resource file uses a .html suffix to enable it to be xhr loaded.

Font

fontThe directory can be used to store font resource files. Common font resources have to tff/woff/svg wait.

Swf

swfThe directory can be used to hold flash resource files. flashThe resource file does not allow (must not) to be placed img in the directory.

Business Directory

Common

commonA directory is a business public directory that is used to store business public files for a project. Therefore, the 业务逻辑 business logic naming is not allowed (must not) to be based on the partitioning of the directory structure common .

FAQ Why isn't there a resource type directory under Biz?

If you biz continue to divide under 资源目录 , the structure of the code may be the same:

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

When we need to use it list.js , we have to write the following code: require("../biz1/js/list") but logically, the more reasonable wording should be require("../biz1/list") . Therefore we do not recommend the biz next facing source code resources to partition the directory.

Baidu EFE team's front-end specification--project directory structure specification