JavaScript工程项目的一系列最佳实践|博客系列

# 1.Git

# 1.1 一些Git规则

这里有一套规则要牢记

在功能分支中执行开发工作

因为这样，所有的工作都是在专用的分支而不是在主分支上隔离完成的。它允许您提交多个 pull request 而不会导致混乱。您可以持续迭代提交，而不会使得那些很可能还不稳定而且还未完成的代码污染 master 分支

从 develop 独立出分支

这样，您可以保持 master 分支中的代码稳定性，这样就不会导致构建问题，并且几乎可以直接用于发布

永远也不要将分支（直接）推送到 develop 或者 master ，请使用合并请求（Pull Request）

通过这种方式，它可以通知整个团队他们已经完成了某个功能的开发。这样开发伙伴就可以更容易对代码进行 code review，同时还可以互相讨论所提交的需求功能

在推送所开发的功能并且发起合并请求前，请更新您本地的develop分支并且完成交互式变基操作（interactive rebase）

ebase 操作会将（本地开发分支）合并到被请求合并的分支（ master 或 develop ）中，并将您本地进行的提交应用于所有历史提交的最顶端，而不会去创建额外的合并提交（假设没有冲突的话），从而可以保持一个漂亮而干净的历史提交记录

请确保在变基并发起合并请求之前解决完潜在的冲突

合并分支后删除本地和远程功能分支
- 如果不删除需求分支，大量僵尸分支的存在会导致分支列表的混乱。而且该操作还能确保有且仅有一次合并到master 或 develop。只有当这个功能还在开发中时对应的功能分支才存在

在进行合并请求之前，请确保您的功能分支可以成功构建，并已经通过了所有的测试（包括代码规则检查）

因为您即将将代码提交到这个稳定的分支。而如果您的功能分支测试未通过，那您的目标分支的构建有很大的概率也会失败。此外，确保在进行合并请求之前应用代码规则检查。因为它有助于我们代码的可读性，并减少格式化的代码与实际业务代码更改混合在一起导致的混乱问题

使用这个 .gitignore 文件

此文件已经囊括了不应该和您开发的代码一起推送至远程仓库（remote repository）的系统文件列表。另外，此文件还排除了大多数编辑器的设置文件夹和文件，以及最常见的（工程开发）依赖目录

保护您的 develop 和 master 分支

这样可以保护您的生产分支免受意外情况和不可回退的变更

# 1.2 Git 工作流

基于以上原因, 我们将功能分支工作流，交互式变基的使用方法结合一些 Gitflow中的基础 (比如，命名和使用一个develop branch)一起使用。主要步骤如下

针对一个新项目, 在您的项目目录初始化您的项目。如果是（已有项目）随后的功能开发/代码变动，这一步请忽略

cd <项目目录>
git init

@前端进阶之旅: 代码已经复制到剪贴板

检出（Checkout）一个新的功能或故障修复（feature/bug-fix）分支

git checkout -b <分支名称>

@前端进阶之旅: 代码已经复制到剪贴板

新增代码变更

git commit -a 会独立启动一个编辑器用来编辑您的说明信息，这样的好处是可以专注于写这些注释说明

git add
git commit -a

@前端进阶之旅: 代码已经复制到剪贴板

（切换至功能分支并且）通过交互式变基从您的develop分支中获取最新的代码提交，以更新您的功能分支

您可以使用 --autosquash 将所有提交压缩到单个提交。没有人会愿意（看到） develop 分支中的单个功能开发就占据如此多的提交历史

git checkout <branchname>
git rebase -i --autosquash develop

@前端进阶之旅: 代码已经复制到剪贴板

如果没有冲突请跳过此步骤，如果您有冲突, 就需要解决它们并且继续变基操作

git add <file1> <file2> ...
git rebase --continue

@前端进阶之旅: 代码已经复制到剪贴板

推送您的（功能）分支。变基操作会改变提交历史, 所以您必须使用 -f 强制推送到远程（功能）分支。如果其他人与您在该分支上进行协同开发，请使用破坏性没那么强的 --force-with-lease 参数

当您进行 rebase 操作时，您会改变功能分支的提交历史。这会导致 Git 拒绝正常的 git push 。那么，您只能使用 -f 或 --force 参数了

git push -f

@前端进阶之旅: 代码已经复制到剪贴板

提交一个合并请求（Pull Request）

Pull Request 会被负责代码审查的同事接受，合并和关闭

如果您完成了开发，请记得删除您的本地分支。

git branch -d <分支>

@前端进阶之旅: 代码已经复制到剪贴板

（使用以下代码）删除所有已经不在远程仓库维护的分支

git fetch -p && for branch in `git branch -vv | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done

@前端进阶之旅: 代码已经复制到剪贴板

# 1.3 如何写好 Commit Message

坚持遵循关于提交的标准指南，会让在与他人合作使用 Git 时更容易。这里有一些经验法则

用新的空行将标题和主体两者隔开

Git 非常聪明，它可将您提交消息的第一行识别为摘要。实际上，如果您尝试使用 git shortlog ，而不是 git log ，您会看到一个很长的提交消息列表，只会包含提交的 id 以及摘要（，而不会包含主体部分）

将标题行限制为50个字符，并将主体中一行超过72个字符的部分折行显示

提交应尽可能简洁明了，而不是写一堆冗余的描述

标题首字母大写

不要用句号结束标题

使用主体部分去解释是什么和为什么而不是怎么做

# 2. 文档

可以使用这个模板作为 README （的一个参考）
对于具有多个存储库的项目，请在各自的 README 文件中提供它们的链接
随项目的进展，持续地更新 README
给您的代码添加详细的注释，这样就可以清楚每个主要部分的含义
不要把注释作为坏代码的借口。保持您的代码干净整洁
也不要把那些清晰的代码作为不写注释的借口
当代码更新，也请确保注释的同步更新

# 3. 环境

如果需要，请分别定义 development, test 和 production 三个环境

不同的环境可能需要不同的数据、token、API、端口等。您可能需要一个隔离的 development 环境，它调用 mock 的 API，mock 会返回可预测的数据，使自动和手动测试变得更加容易。或者您可能只想在 production 环境中才启用 Google Analytics（分析）

依据不同的环境变量加载部署的相关配置，不要将这些配置作为常量添加到代码库中

您会有令牌，密码和其他有价值的信息。这些配置应正确地从应用程序内部分离开来，这样代码库就可以随时独立发布，不会包含这些敏感配置信息

怎么做：使用 .env 文件来存储环境变量，并将其添加到 .gitignore 中使得排除而不被提交（到仓库）。另外，再提交一个 .env.example 作为开发人员的参考配置。对于生产环境，您应该依旧以标准化的方式设置环境变量

建议您在应用程序启动之前校验一下环境变量

它可能会将其他人从上小时的故障排查中解救

const joi = require('joi')

const envVarsSchema = joi.object({  
  NODE_ENV: joi.string()
    .valid(['development', 'production', 'test', 'provision'])
    .required(),
  PORT: joi.number()
    .required(),
  LOGGER_LEVEL: joi.string()
    .valid(['error', 'warn', 'info', 'verbose', 'debug', 'silly'])
    .default('info'),
  LOGGER_ENABLED: joi.boolean()
    .truthy('TRUE')
    .truthy('true')
    .falsy('FALSE')
    .falsy('false')
    .default(true)
}).unknown()
  .required()

const { error, value: envVars } = joi.validate(process.env, envVarsSchema)  
if (error) {  
  throw new Error(`Config validation error: ${error.message}`)
}

const config = {  
  env: envVars.NODE_ENV,
  isTest: envVars.NODE_ENV === 'test',
  isDevelopment: envVars.NODE_ENV === 'development',
  logger: {
    level: envVars.LOGGER_LEVEL,
    enabled: envVars.LOGGER_ENABLED
  },
  server: {
    port: envVars.PORT
  }
  // ...
}

module.exports = config;

@前端进阶之旅: 代码已经复制到剪贴板

# 3.1 一致的开发环境

在 package.json 里的 engines 中设置您的node版本

让其他人可以清晰的知道这个项目中用的什么node版本

另外，使用 nvm 并在您的项目根目录下创建一个 .nvmrc 文件。不要忘了在文档中标注

任何使用nvm的人都可以使用 nvm use 来切换到合适的node版本

最好设置一个检查 node 和 npm 版本的 preinstall 脚本

某些依赖项可能会在新版本的 npm 中安装失败。

如果可以的话最好使用 Docker 镜像

它可以在整个工作流程中为您提供一致的环境，而且不用花太多的时间来解决依赖或配置

使用本地模块，而不是使用全局安装的模块

您不能指望您的同事在自己的全局环境都安装了相应的模块，本地模块可以方便您分享您的工具

# 3.2 依赖一致性

确保您的团队成员获得与您完全相同的依赖。

因为您希望代码在任何开发环境中运行都能像预期的一样

在npm@5或者更高版本中使用 package-lock.json

我们没有 npm@5
- 或者，您可以使用 yarn ，并确保在 README.md 中标注了使用 yarn 。您的锁文件和package.json在每次依赖关系更新后应该具有相同的版本
我不太喜欢 Yarn
- 不喜欢 Yarn，太糟糕了。对于旧版本的npm，在安装新的依赖关系时使用 -save --save-exact ，并在发布之前创建npm-shrinkwrap.json

# 4. 依赖

持续跟踪您当前的可用依赖包: 举个例子, npm ls --depth=0

查看这些软件包是否未使用或者与开发项目无关: depcheck

您可能会在代码中包含未使用的库，这会增大生产包的大小。请搜索出这些未使用的依赖关系并去掉它们吧

在使用依赖之前，请检查他的下载统计信息，看看它是否被社区大量使用： npm-stat

更多的使用量很大程度上意味着更多的贡献者，这通常意味着拥有更好的维护，这些能确保错误能够被快速地发现并修复

在使用依赖之前，请检查它是否具有良好而成熟的版本发布频率与大量的维护者：例如， npm view async

如果维护者没有足够快地合并修补程序，那么这些贡献者也将会变得不积极不高效

如果需要使用那些不太熟悉的依赖包，请在使用之前与团队进行充分讨论

始终确保您的应用程序在最新版本的依赖包上面能正常运行，而不是无法使用：npm outdated

# 1.Git

# 1.1 一些Git规则

这里有一套规则要牢记

在功能分支中执行开发工作

因为这样，所有的工作都是在专用的分支而不是在主分支上隔离完成的。它允许您提交多个 pull request 而不会导致混乱。您可以持续迭代提交，而不会使得那些很可能还不稳定而且还未完成的代码污染 master 分支

从 develop 独立出分支

这样，您可以保持 master 分支中的代码稳定性，这样就不会导致构建问题，并且几乎可以直接用于发布

永远也不要将分支（直接）推送到 develop 或者 master ，请使用合并请求（Pull Request）

通过这种方式，它可以通知整个团队他们已经完成了某个功能的开发。这样开发伙伴就可以更容易对代码进行 code review，同时还可以互相讨论所提交的需求功能

在推送所开发的功能并且发起合并请求前，请更新您本地的develop分支并且完成交互式变基操作（interactive rebase）

ebase 操作会将（本地开发分支）合并到被请求合并的分支（ master 或 develop ）中，并将您本地进行的提交应用于所有历史提交的最顶端，而不会去创建额外的合并提交（假设没有冲突的话），从而可以保持一个漂亮而干净的历史提交记录

请确保在变基并发起合并请求之前解决完潜在的冲突

合并分支后删除本地和远程功能分支
- 如果不删除需求分支，大量僵尸分支的存在会导致分支列表的混乱。而且该操作还能确保有且仅有一次合并到master 或 develop。只有当这个功能还在开发中时对应的功能分支才存在

在进行合并请求之前，请确保您的功能分支可以成功构建，并已经通过了所有的测试（包括代码规则检查）

因为您即将将代码提交到这个稳定的分支。而如果您的功能分支测试未通过，那您的目标分支的构建有很大的概率也会失败。此外，确保在进行合并请求之前应用代码规则检查。因为它有助于我们代码的可读性，并减少格式化的代码与实际业务代码更改混合在一起导致的混乱问题

使用这个 .gitignore 文件

此文件已经囊括了不应该和您开发的代码一起推送至远程仓库（remote repository）的系统文件列表。另外，此文件还排除了大多数编辑器的设置文件夹和文件，以及最常见的（工程开发）依赖目录

保护您的 develop 和 master 分支

这样可以保护您的生产分支免受意外情况和不可回退的变更

# 1.2 Git 工作流

基于以上原因, 我们将功能分支工作流，交互式变基的使用方法结合一些 Gitflow中的基础 (比如，命名和使用一个develop branch)一起使用。主要步骤如下

针对一个新项目, 在您的项目目录初始化您的项目。如果是（已有项目）随后的功能开发/代码变动，这一步请忽略

cd <项目目录>
git init

@前端进阶之旅: 代码已经复制到剪贴板

检出（Checkout）一个新的功能或故障修复（feature/bug-fix）分支

git checkout -b <分支名称>

@前端进阶之旅: 代码已经复制到剪贴板

新增代码变更

git commit -a 会独立启动一个编辑器用来编辑您的说明信息，这样的好处是可以专注于写这些注释说明

git add
git commit -a

@前端进阶之旅: 代码已经复制到剪贴板

（切换至功能分支并且）通过交互式变基从您的develop分支中获取最新的代码提交，以更新您的功能分支

您可以使用 --autosquash 将所有提交压缩到单个提交。没有人会愿意（看到） develop 分支中的单个功能开发就占据如此多的提交历史

git checkout <branchname>
git rebase -i --autosquash develop

@前端进阶之旅: 代码已经复制到剪贴板

如果没有冲突请跳过此步骤，如果您有冲突, 就需要解决它们并且继续变基操作

git add <file1> <file2> ...
git rebase --continue

@前端进阶之旅: 代码已经复制到剪贴板

当您进行 rebase 操作时，您会改变功能分支的提交历史。这会导致 Git 拒绝正常的 git push 。那么，您只能使用 -f 或 --force 参数了

git push -f

@前端进阶之旅: 代码已经复制到剪贴板

提交一个合并请求（Pull Request）

Pull Request 会被负责代码审查的同事接受，合并和关闭

如果您完成了开发，请记得删除您的本地分支。

git branch -d <分支>

@前端进阶之旅: 代码已经复制到剪贴板

（使用以下代码）删除所有已经不在远程仓库维护的分支

git fetch -p && for branch in `git branch -vv | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done

@前端进阶之旅: 代码已经复制到剪贴板

# 1.3 如何写好 Commit Message

坚持遵循关于提交的标准指南，会让在与他人合作使用 Git 时更容易。这里有一些经验法则

用新的空行将标题和主体两者隔开

Git 非常聪明，它可将您提交消息的第一行识别为摘要。实际上，如果您尝试使用 git shortlog ，而不是 git log ，您会看到一个很长的提交消息列表，只会包含提交的 id 以及摘要（，而不会包含主体部分）

将标题行限制为50个字符，并将主体中一行超过72个字符的部分折行显示

提交应尽可能简洁明了，而不是写一堆冗余的描述

标题首字母大写

不要用句号结束标题

使用主体部分去解释是什么和为什么而不是怎么做

# 2. 文档

可以使用这个模板作为 README （的一个参考）
对于具有多个存储库的项目，请在各自的 README 文件中提供它们的链接
随项目的进展，持续地更新 README
给您的代码添加详细的注释，这样就可以清楚每个主要部分的含义
不要把注释作为坏代码的借口。保持您的代码干净整洁
也不要把那些清晰的代码作为不写注释的借口
当代码更新，也请确保注释的同步更新

# 3. 环境

如果需要，请分别定义 development, test 和 production 三个环境

不同的环境可能需要不同的数据、token、API、端口等。您可能需要一个隔离的 development 环境，它调用 mock 的 API，mock 会返回可预测的数据，使自动和手动测试变得更加容易。或者您可能只想在 production 环境中才启用 Google Analytics（分析）

依据不同的环境变量加载部署的相关配置，不要将这些配置作为常量添加到代码库中

您会有令牌，密码和其他有价值的信息。这些配置应正确地从应用程序内部分离开来，这样代码库就可以随时独立发布，不会包含这些敏感配置信息

怎么做：使用 .env 文件来存储环境变量，并将其添加到 .gitignore 中使得排除而不被提交（到仓库）。另外，再提交一个 .env.example 作为开发人员的参考配置。对于生产环境，您应该依旧以标准化的方式设置环境变量

建议您在应用程序启动之前校验一下环境变量

它可能会将其他人从上小时的故障排查中解救

const joi = require('joi')

const envVarsSchema = joi.object({  
  NODE_ENV: joi.string()
    .valid(['development', 'production', 'test', 'provision'])
    .required(),
  PORT: joi.number()
    .required(),
  LOGGER_LEVEL: joi.string()
    .valid(['error', 'warn', 'info', 'verbose', 'debug', 'silly'])
    .default('info'),
  LOGGER_ENABLED: joi.boolean()
    .truthy('TRUE')
    .truthy('true')
    .falsy('FALSE')
    .falsy('false')
    .default(true)
}).unknown()
  .required()

const { error, value: envVars } = joi.validate(process.env, envVarsSchema)  
if (error) {  
  throw new Error(`Config validation error: ${error.message}`)
}

const config = {  
  env: envVars.NODE_ENV,
  isTest: envVars.NODE_ENV === 'test',
  isDevelopment: envVars.NODE_ENV === 'development',
  logger: {
    level: envVars.LOGGER_LEVEL,
    enabled: envVars.LOGGER_ENABLED
  },
  server: {
    port: envVars.PORT
  }
  // ...
}

module.exports = config;

@前端进阶之旅: 代码已经复制到剪贴板

# 3.1 一致的开发环境

在 package.json 里的 engines 中设置您的node版本

让其他人可以清晰的知道这个项目中用的什么node版本

另外，使用 nvm 并在您的项目根目录下创建一个 .nvmrc 文件。不要忘了在文档中标注

任何使用nvm的人都可以使用 nvm use 来切换到合适的node版本

最好设置一个检查 node 和 npm 版本的 preinstall 脚本

某些依赖项可能会在新版本的 npm 中安装失败。

如果可以的话最好使用 Docker 镜像

它可以在整个工作流程中为您提供一致的环境，而且不用花太多的时间来解决依赖或配置

使用本地模块，而不是使用全局安装的模块

您不能指望您的同事在自己的全局环境都安装了相应的模块，本地模块可以方便您分享您的工具

# 3.2 依赖一致性

确保您的团队成员获得与您完全相同的依赖。

因为您希望代码在任何开发环境中运行都能像预期的一样

在npm@5或者更高版本中使用 package-lock.json

我们没有 npm@5
- 或者，您可以使用 yarn ，并确保在 README.md 中标注了使用 yarn 。您的锁文件和package.json在每次依赖关系更新后应该具有相同的版本
我不太喜欢 Yarn
- 不喜欢 Yarn，太糟糕了。对于旧版本的npm，在安装新的依赖关系时使用 -save --save-exact ，并在发布之前创建npm-shrinkwrap.json

# 4. 依赖

持续跟踪您当前的可用依赖包: 举个例子, npm ls --depth=0

查看这些软件包是否未使用或者与开发项目无关: depcheck

您可能会在代码中包含未使用的库，这会增大生产包的大小。请搜索出这些未使用的依赖关系并去掉它们吧

在使用依赖之前，请检查他的下载统计信息，看看它是否被社区大量使用： npm-stat

更多的使用量很大程度上意味着更多的贡献者，这通常意味着拥有更好的维护，这些能确保错误能够被快速地发现并修复

在使用依赖之前，请检查它是否具有良好而成熟的版本发布频率与大量的维护者：例如， npm view async

如果维护者没有足够快地合并修补程序，那么这些贡献者也将会变得不积极不高效

如果需要使用那些不太熟悉的依赖包，请在使用之前与团队进行充分讨论

始终确保您的应用程序在最新版本的依赖包上面能正常运行，而不是无法使用：npm outdated