Git 代码提交规范：构建高质量软件体系的必要准则

Git代码提交规范：提升协作与代码质量

原创已于 2025-04-14 09:10:01 修改 · 1.5k 阅读

24 ·

CC 4.0 BY-SA版权

文章标签：

#前端 #git

于 2025-04-14 09:07:59 首次发布

git 专栏收录该内容

5 篇文章

订阅专栏

前言

在项目开发中，你是否翻阅过 Git 提交历史，面对一堆含义不明的提交信息而感到困惑？不规范的代码提交信息，会给代码审查、版本回溯带来极大阻碍。为了避免这类情况，清晰、规范的提交信息就显得尤为重要，它能让团队成员迅速了解代码变更的意图，提升协作效率，Git 代码提交信息规范应运而生。它就像一把钥匙，为高效的代码管理与协作打开了大门。

文章目录

一、提交信息结构
 二、提交类型的规范
 三、分支管理与提交关联
 四、使用工具进行规范检查
 五、总结

一、提交信息结构

1.1 标题（Subject）

标题是提交信息的第一行，应该简短但具有描述性。其长度一般建议不超过 50 个字符。
标题应该以动词开头，如 Fix（修复）、Add（添加）、Update（更新）、Remove（移除）等，这样可以清晰地表明此次提交的动作类型。

1.2 正文（Body）

标题若无法详述提交内容，就需正文补充。正文要清晰说明提交内容，如新增代码功能、修改位置和逻辑；阐述目的，比如修复故障、优化性能或实现业务需求；分析对项目的影响，包括功能、性能及兼容性。为保证可读性，每行不超 72 字符，以方便在各种终端和工具中查看。

1.3 脚注（Footer）

脚注用于关联补充，可引用项目管理工具（如 Jira、Trello ）的任务编号，明确提交与任务的关系，方便定位追溯。也能关联其他提交，梳理提交脉络，助团队理解项目开发过程。

二、提交类型的规范

2.1 `feat`：新功能（Feature）

解释：

当你为项目添加了新的功能或特性时使用该类型。这些新功能会为项目带来新的功能模块、业务逻辑或用户交互，并且通常会涉及对现有代码库的扩展，以满足新的业务需求或用户需求。
示例：

实现用户注册功能：添加了用户注册功能，包括前端界面和后端逻辑，使新用户能够注册账号并保存用户信息时使用。
为用户添加头像上传功能：在用户个人资料页面添加头像上传功能，包括上传文件、存储文件、显示头像等一系列操作。

2.2 `fix`：修复 bug（Bug Fix）

解释：

当你在代码中发现并修复了错误或缺陷时使用。这些错误可能导致程序运行异常、产生错误结果、或未按预期工作，使用该类型能清晰地表明你正在修复问题。
示例：

修复用户登录时密码验证错误：如果用户输入正确密码但无法登录，而你通过检查和修改登录逻辑解决了此问题，可使用该提交。
修复购物车结算时价格计算错误：当购物车中的商品总价计算结果不符合预期，你找出错误并修正计算逻辑时使用。

2.3 `docs`：文档变更（Documentation）

解释：

此类型适用于对项目文档的更新或修改。文档是项目的重要组成部分，包括但不限于 README 文件、API 文档、代码注释、用户手册等，确保文档与代码同步更新，有助于其他开发者和用户更好地理解项目。
示例：

更新 README 文件中的项目架构描述：如果对项目架构进行了调整，需要修改 README 中关于架构的部分，让读者更清晰地了解架构组成。
完善 API 文档中用户管理接口的说明：对用户管理接口的请求参数、响应格式、错误码等进行详细说明，方便前端开发人员使用。

2.4 `style`：格式（Style）

解释：

主要用于代码格式的调整，不会对代码的实际逻辑产生影响。这有助于保持代码的一致性和可读性，例如统一的缩进、空格、换行符、分号使用等，通常由代码格式化工具或手动调整引起。
示例：

将代码缩进从 4 个空格调整为 2 个空格：为了遵循团队的代码风格规范，对整个代码库或部分代码进行缩进调整。
移除多余的空行并添加一致的代码注释格式：整理代码结构，使其更具可读性。

2.5 `refactor`：重构（Refactoring）

解释：

当你对现有代码进行重构，旨在提高代码的质量、可维护性或遵循更好的设计模式，但不添加新功能或修复错误时使用。重构可能包括代码结构的调整、函数的拆分、类的重构、优化算法等。
示例：

重构用户服务模块，将大函数拆分为多个小函数：为了提高代码的可读性和可测试性，将原来复杂的用户服务函数拆分成多个小函数。
用迭代器模式重构数据处理逻辑：采用迭代器模式优化数据处理逻辑，使代码更清晰，但功能保持不变。

2.6 `perf`：性能优化（Performance）

解释：

当你对代码进行性能改进，如优化算法、减少执行时间、降低内存占用、减少网络请求、提高数据库查询效率等，使用该类型来表示你正在致力于提高代码的性能。
示例：

优化数据库查询，使用索引减少查询时间：在数据库操作中添加适当的索引，加快查询速度。
优化图片加载算法，提高加载速度：使用更高效的图片加载算法，降低用户等待时间。

2.7 `test`：测试（Testing）

解释：

用于添加新的测试代码或修改现有测试代码。测试是确保代码质量和功能稳定性的重要手段，包括单元测试、集成测试、端到端测试等。
示例：

为用户登录功能添加单元测试：编写测试用例，验证用户登录功能在各种情况下的正确性。
增加用户注册功能的集成测试，包括数据库操作测试：测试用户注册功能，确保注册信息能正确保存到数据库。

2.8 `chore`：杂项（Chores）

解释：

涉及不修改 src 或测试文件的其他变更，通常包括构建过程、辅助工具、开发环境、配置文件的更新等，这些变更不直接影响产品代码，但有助于项目的开发和维护。
示例：

更新 npm 依赖项版本：使用 npm update 更新项目的依赖项。
配置 ESLint 规则：为项目添加或修改 ESLint 规则，以保证代码规范。

2.9 `build`：构建（Build）

解释：

当对构建系统或外部依赖进行变更时使用，包括构建工具（如 gulp、webpack、npm、yarn）的修改，这些变更会影响项目的构建过程，可能涉及构建脚本、配置文件的更新。
示例：

更新 webpack 配置以支持新的文件类型：为了处理新类型的文件，修改 webpack 配置文件。
调整 npm 脚本，添加新的构建命令：添加新的构建命令，如 npm run build:prod 用于生产环境的构建。

2.10 `ci`：持续集成（Continuous Integration）

解释：

用于更改持续集成配置文件和脚本，如 Travis、Circle、Jenkins 等，以优化持续集成流程，确保代码在合并前经过自动测试和检查。
示例：

更新 Travis 配置文件，添加新的测试环境：当添加新的测试环境，如 Node.js 新版本的测试，更新 Travis 配置文件。
修改 CircleCI 配置以加快构建速度：调整 CircleCI 配置，如使用缓存等，提高构建速度。

2.11 `revert`：回退（Revert）

解释：

当你需要回退之前的一个或多个提交时使用该类型，需要在提交信息中明确指出要回退的提交的哈希值，以保持提交历史的清晰。
示例：

回退 commit abcdef123456：如果你需要撤销之前的提交，并且该提交的哈希值是 abcdef123456，使用该提交信息。

2.12 `wip`：进行中的工作（Work In Progress）

解释：

通常用于标记尚未完成的工作，这是一种临时提交，用于保存当前的工作进度，以便在后续继续开发。它有助于在多人协作或在不同设备上继续工作时保留中间状态，但应尽快完成最终的提交。
示例：

正在开发用户搜索功能，已完成前端界面部分：当开发用户搜索功能，只完成了前端界面部分，为避免代码丢失或方便他人了解进度，可使用该提交。
开始重构订单处理模块，部分代码已迁移：在重构订单处理模块的过程中，暂时提交已完成的部分代码。

三、分支管理与提交关联

3.1 不同分支的开发用途

开发中，为保障代码有序开发，通常会基于不同分支开展工作。主分支（master 或 main）是项目稳定的核心，项目经测试、修复及功能整合后，稳定版本会部署到主分支用于对外发布。例如电商项目，完成购物车、订单等功能的测试优化后，稳定版本发布到主分支供用户使用。

开发分支（如 develop）是新功能集成和测试的地方。开发人员在开发分支编写、测试新功能代码，通过初步集成测试，确认无明显问题后，再向主分支合并。比如电商 “限时抢购” 功能，在开发分支集成时间限制、库存锁定等模块并测试。

功能开发一般在特性分支（feature/xxx）进行，xxx 是功能名，如 feature/add_shopping_cart_animation 用于开发购物车动画。在特性分支，开发人员可专注单个功能，便于代码版本管理和回溯。

3.2 提交信息里的分支关联

提交信息是开发沟通的重要途径，其中提及分支关联很关键。将特性分支合并到开发分支时，提交信息需说明特性分支功能及对开发分支的影响。例如将 feature/add_search_function 合并到 develop，提交信息可写：“合并搜索功能分支，实现关键词和模糊搜索，增加搜索相关代码和接口调用。” 这样团队成员能快速了解合并内容和影响，便于协同开发与测试。

四、使用工具进行规范检查

4.1 commitlint 规范配置

开发者可以借助诸如 commitlint 等专业工具来有效检查提交信息是否契合既定规范。commitlint 具备强大的自定义配置能力，开发团队能够依据自身项目的特点和需求，灵活设置多样的规则。例如，在提交标题格式方面，可以规定其必须以特定的动词开头，像 Fix、Add、Update 等，且长度需控制在一定字符数以内，以此保证标题简洁明了、精准传达提交意图。

4.2 CI 流程规范检查

在项目的持续集成（CI）流程里，引入提交规范检查步骤是保障代码质量的关键环节。当开发者将代码提交到远程仓库时，CI 系统会自动触发构建流程，其中提交规范检查便是重要的一环。一旦提交信息不符合预先设定的规范，CI 构建过程就会敏锐地捕捉到问题，并及时向开发者发出明确的提示，告知具体是哪些规则未被满足，例如标题格式错误、缺少必要前缀等。开发者在收到提示后，能够迅速定位问题并进行修正，从而确保项目中所有的代码提交都符合统一规范，提升整个项目的代码质量和可维护性。