git commit 规范指南

git commit 规范指南

Git Commit 规范是团队协作和代码管理中的重要实践，它能提高代码可读性、方便回溯历史、自动化生成 CHANGELOG，并促进更清晰的代码审查。以下是常见的规范和实践建议。

一、核心规范

1.1 格式标准

推荐遵循 Conventional Commits 规范，格式如下：

<类型>[可选作用域]: <主题>
// 空行
[可选正文]
// 空行
[可选页脚]

1.2 组成部分详解

1. 类型（Type）

必填，表示代码变更的性质：

类型	适用场景
​feat​	新增功能
​fix​	修复 Bug
​docs​	文档更新（如 README、API 文档）
​style​	代码格式调整（空格、缩进等，不影响功能）
​refactor​	代码重构（非功能新增或修复）
​perf​	性能优化
​test​	测试用例变更（增/删/改）
​chore​	构建工具或依赖管理变更
​ci​	持续集成配置变更
​revert​	回滚历史提交

2. 作用域（Scope）

可选，描述修改的影响范围（如模块、组件）：

feat(login): 添加微信登录功能
fix(checkout): 修复订单金额计算错误

3. 主题（Subject）

必填，简明扼要的提交描述：

• 使用祈使语气（如 "Add" 而非 "Added"）
• 首字母小写，结尾不加句号
• 长度建议不超过 50 字符

4. 正文（Body）

可选，详细说明变更内容：

• 解释 为什么修改（而非如何修改，代码差异已通过 Git 展示）
• 使用空行分隔段落，保持可读性

5. 页脚（Footer）

可选，用于关联 Issue 或标记破坏性变更：

• 关闭 Issue：Closes #123, #456​

• 破坏性变更需明确说明影响和迁移方式：

  BREAKING CHANGE: 移除旧版 API 接口，需使用 v2.0+ 版本
  

---

二、提交示例

2.1 简单场景

‍

feat: 新增用户注册接口

fix(auth): 修复 Token 过期时间计算错误

2.2 复杂场景

refactor(payment): 重构支付模块核心逻辑

- 解耦支付渠道与订单处理逻辑  
- 引入策略模式支持多支付方式  
- 移除冗余的支付状态检查代码  

Closes #89
BREAKING CHANGE: 旧版支付回调接口已废弃，需迁移至 `/api/v2/callback`

三、最佳实践

3.1 提交原则

1. 原子化提交
   每个提交仅解决一个问题，避免混合多个功能或修复。
   ✅ 正确示例：fix(login): 修复密码重置链接失效问题​
   ❌ 错误示例：fix: 修复登录和支付问题​
2. 关联上下文
   通过 Closes #123​ 或 Refs #45​ 关联 JIRA/GitHub Issue。
3. 团队统一规范
   根据项目特性扩展类型（如 i18n​、design​），但需团队达成共识。

3.2 避免常见问题

• 模糊描述：如 update​、fix bug​ 等无意义信息
• 冗长主题：超过 50 字符需优化措辞或移至正文
• 混合变更：同时修改代码和文档应拆分为 feat​ + docs​ 提交

---

四、为何需要规范？

1. 提升可读性
   通过类型标签快速识别提交目的（如快速筛选所有 fix​ 提交）。
2. 自动化流程
   工具可自动生成语义化版本号（SemVer）和 CHANGELOG。
3. 高效代码审查
   审查者通过提交描述快速理解代码意图。
4. 精准追溯问题
   ​git blame​ 和 git bisect​ 可快速定位问题代码历史。

五、结语

规范化的 Git Commit 看似增加了提交时的成本，实则为团队协作和项目管理带来长期收益。通过结合工具链与团队共识，开发者可以轻松实践这一规范，最终实现更高效、更透明的代码协作流程。

让每一次提交都成为清晰的代码故事，而非杂乱的历史碎片。