《编写可维护的 JavaScript》自动化 - 第 13 章 文件和目录结构

自动化 - 第 13 章. 文件和目录结构

《编写可维护的 JavaScript》—— Nicholas C. Zakas

我相当乐意花一整天的时间通过编程把一个任务实现自动化，除非这个任务手动只需要 10 秒钟就能完成。——Douglas Adams

在 2000 年之前，Web 开发者把它们包含注释的源代码原封不动地直接部署到服务器的现象很普遍，
这种本地和服务器文件完全一致的镜像方式可以方便我们迅速地改动代码。
此外，这也导致了“查看源代码”时代的到来，许多 Web 开发者都会把查看其它网站的源代码作为一种学习方式。

而现在的 Web 应用动辄就有上千行的代码，由一群开发者共同完成，很显然，旧的部署方式已经不能用了。

所有的大型 Web 应用都依赖于自动化工具来处理它们项目中的 JavaScript 文件。
自动化在其他 Web 应用框架中很常见，但直到 2005 年才开始广泛应用于 JavaScript 中，
把 JavaScript 加入到整个 Web 应用自动化系统中可以让你拥有与系统其他部分同样的保障，
对于代码的可维护性来说，这是非常重要的一步。

优点：

• 本地的源代码不必与生产环境上保持一致，你可以任意组织你的代码结构
• 静态分析可以自动发现错误
• 在部署之前有多重方式处理 JavaScript，如文件的合并和压缩
• 使用自动化测试可以很容易发现问题
• 很方便地自动部署到生产环境
• 快速地重新执行常见任务

缺点：

• 在开发环境下的每次改动都需要重新构建。一些习惯了改完代码就去刷新浏览器的开发人员很难适应这一步
• 部署到生产环境下的代码与生产环境下下的代码有区别，很难定位到线上的 bug
• 技术水平偏低的开发人员使用构建系统可能会遇到问题

在开始构建你的系统之前首先要确定如何组织你的文件和目录，项目类型决定了目录结构。
如果项目是一个独立的 JavaScript 类库，其结构肯定与网站项目的结构不同。

1. 最佳实践

抛开项目类型不谈，总有一些适用于 JavaScript 文件和目录结构的最佳实践。

一个文件只包含一个对象：

每个 JavaScript 文件应该只包含一个 JavaScript 对象的代码，这种模式在其他编程语言中很常见，可使代码更易于维护。

这样做降低了多人同时修改同一文件的风险。
尽管现在的代码版本管理工具（SVN、CVS、GIT）很容易合并两个人的修改，但是人就会有合并冲突的情况发生。
文件越少，合并时冲突的可能性就越大，保持每个文件只有一个 JavaScript 对象降低了这种风险。

相关的文件置于同一目录：

如果你有多个相关联的对象，就把这些文件都放在同一个目录下。
例如，一个模块有多个文件的代码组成，那么把这个模块包含的所有文件放在一个目录下就很有意义。
给相关的文件分组有助于开发者更容易定位功能。

保持第三方代码的独立：

第三方代码应当独立于项目工程之外。
比如一个 JavaScript 类库，最理想的情况是根本不引入这样一个 JavaScript 类库，而直接从 CDN 加载它。
把这些第三方文件单独放置在项目工程中的一个目录里，是一种最佳的替代方案。

明确源码目录：

创建的 JavaScript 文件应当放置在一个完全独立的目录里，而不应该置于项目中。
网站应该使用编译后的目录，而不应该使用源码目录。
不要把编译后的代码提交到源代码中，因为编译后内容都是成型的，在部署到线上之前，会多次编译。

保持测试代码的完整性：

JavaScript 测试代码也也应当提交到项目中。

如果你的 JavaScript 不是一个独立的 JavaScript 项目，而是大型网站或 Web 应用的一部分，
文件和目录的结构基本上由服务器端使用的框架所决定。
即使项目的目录结构千变万化，但总会有一个子目录（如 js、scripts、javascript）单独用于存放 JavaScript，
针对这个目录，有几种常见的目录结构划分。

2. 基本结构

JavaScript 目录下放置如下三个主要目录是很流行的做法：

• build 或 dist：用来放置最终构建后的文件，理想情况下这个目录不应该提交
• src：用来放置所有的源文件，通常每个功能划分一个子目录
• test 或 tests：用来放置所有的测试文件，与 src 目录的结构一一对应

3. CSS Lint 项目结构

CSS Lint 项目结构：

csslint/
  demos/
  dist/   # 始终包含最新的稳定发行版本。build + release
  lib/    # 第三方库
  src/    # 按功能划分子目录
    cli/
    core/
      CSSLint.js  # 源文件
    formatters/
    rules/
    workder/
  tasks/
  tests/  # 目录结构与 src 一一对应
    cli/
    core/
      CSSLint.js  # 对应的测试文件
    formatters/
    rules/
    workder/

4. jQuery 项目结构

jQuery 项目结构

jquery/
  build/
  dist/
  external/   # 第三方库
  src/
    ajax/
    core/
    ajax.js
    core.js
  test/
    unit/
      ajax.js
      core.js
  .gitignore
  README.md
  package.json

src 目录下直接放置核心功能文件，核心功能文件对应的子目录存放相关的资源文件和扩展

src/ajax.js 的测试文件为 test/unit/ajax.js