Git提交规范及最佳实践

发布于:2025-04-16 ⋅ 阅读:(37) ⋅ 点赞:(0)

Git 提交规范通常是为了提高代码提交的可读性、可维护性和自动化效率(如生成 ChangeLog)。以下是常见的 Conventional Commits 规范,结合社区最佳实践总结而成:


1. 提交格式

每次提交的 commit message 应包含三部分:HeaderBody 和 Footer,格式如下:

复制

<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>
  • Header(必填):描述提交类型和简短说明。

  • Body(可选):详细说明修改内容(如动机、实现细节)。

  • Footer(可选):关联 Issue、描述破坏性变更(BREAKING CHANGE)等。


2. 提交类型(Type)

类型 说明
feat 新增功能(feature)
fix 修复 Bug
docs 文档更新(如 README、注释)
style 代码样式调整(如空格、格式化,不改变逻辑)
refactor 代码重构(既不修复 Bug 也不新增功能)
perf 性能优化
test 添加或修改测试用例
chore 构建过程或辅助工具的变动(如依赖更新、CI 配置)
revert 回滚之前的提交
build 构建相关的修改(如打包工具、依赖库版本升级)
ci CI/CD 配置或脚本的修改

3. 规范细则

Header
  • <type>:必填,从上述类型中选择。

  • <scope>:可选,描述影响范围(如模块名、功能名),例如 feat(user)

  • <subject>:简明描述修改内容:

    • 使用祈使句(如 "Add" 而非 "Added" 或 "Adds")。

    • 首字母小写,结尾不加标点。

    • 长度建议不超过 50 字符

Body
  • 描述为什么修改如何修改,以及与之前行为的对比

  • 每行不超过 72 字符,避免自动换行问题。

Footer
  • 关联 Issue:如 Closes #123 或 Fixes #456

  • 破坏性变更:以 BREAKING CHANGE: 开头,描述不兼容的改动。


4. 提交示例

plaintext

复制

feat(auth): add OAuth2 login support

- Integrate Google OAuth2 API
- Add login button component

Closes #123
BREAKING CHANGE: Remove deprecated login API endpoints.

plaintext

复制

fix(api): handle null response in user endpoint

When the user data is missing, return 404 instead of 500.

Fixes #456

5. 工具支持

  • commitlint:校验提交信息是否符合规范。

  • husky:通过 Git 钩子自动触发校验。

  • standard-version:基于提交记录自动生成版本号和 ChangeLog。


6. 分支命名建议

  • 功能分支feature/描述性名称(如 feature/user-login

  • Bug 分支fix/问题描述(如 fix/login-error

  • 热修复分支hotfix/问题描述


通过规范化的提交信息,可以:

  1. 提升代码审查效率。

  2. 自动化生成版本日志(ChangeLog)。

  3. 方便追踪代码变更历史。

  4. 支持语义化版本号(Semantic Versioning)。

以下是一些符合中文 Git 提交规范的示例,涵盖不同场景:


示例 1:新增功能(feat

plaintext

复制

feat(订单): 新增支持支付宝支付方式

- 添加支付宝 SDK 集成
- 创建支付结果回调处理逻辑
- 更新订单状态流转文档

Closes #45

示例 2:修复 Bug(fix

plaintext

复制

fix(登录): 修复手机号验证码重复发送问题

当用户频繁点击发送验证码按钮时,后端未正确校验时间间隔,
导致同一用户 1 秒内可发送多次请求。现已添加 60 秒冷却时间限制。

Fixes #78

示例 3:文档更新(docs

plaintext

复制

docs(API): 更新用户模块接口文档

- 补充 getUserInfo 接口的权限说明
- 修正 createUser 的请求体示例格式

示例 4:代码重构(refactor

plaintext

复制

refactor(购物车): 解耦商品价格计算逻辑

将价格计算从 ShoppingCartService 移至独立的 PriceCalculator 类,
提高代码可测试性和可维护性。

示例 5:破坏性变更(BREAKING CHANGE

plaintext

复制

feat(配置): 重构环境变量加载方式

- 废弃旧版 .env 文件格式
- 改用 YAML 格式配置文件

BREAKING CHANGE: 必须将原有 .env 文件迁移至 config.yaml
Closes #112

示例 6:简单提交(无 Body/Footer)

plaintext

复制

style: 调整首页按钮间距

示例 7:性能优化(perf

plaintext

复制

perf(图片加载): 启用 WebP 格式压缩

- 通过 CDN 自动转换图片为 WebP 格式
- 平均图片体积减少 65%

示例 8:回滚提交(revert

plaintext

复制

revert: 撤销 "feat: 实验性分页功能"

该功能导致列表渲染性能下降超过 200ms,
需重新设计实现方案。

This reverts commit 9a7b2d1c.

示例 9:测试相关(test

plaintext

复制

test(用户服务): 添加登录失败用例

- 覆盖密码错误、账号锁定等场景
- 使用 Jest 模拟 Redis 服务

示例 10:构建工具(build

plaintext

复制

build: 升级 Webpack 至 5.75 版本

- 修复 tree-shaking 对 lodash 的兼容性问题
- 优化构建产物哈希生成策略

关键要点

  1. 动词使用:描述时用 "新增/修复/优化/调整" 等祈使动词
    ❌ 错误:"修复了XXX问题" → ✅ 正确:"修复XXX问题"

  2. 长度控制

    • Header 简明扼要(50 字内)

    • Body 每行不超过 72 字符

  3. 关联问题:明确标注关闭的 Issue(如 Closes #123

  4. 破坏性变更:必须用 BREAKING CHANGE: 显式声明

实际使用中可根据团队需求调整规范细节,建议配合 Commitizen 工具实现交互式提交引导。


网站公告

今日签到

点亮在社区的每一天
去签到