Git 提交代码规范指南

一、主流规范：Conventional Commits

最广泛使用的标准是 Conventional Commits，它让提交历史清晰可读，并支持自动化生成 CHANGELOG。

基本格式

<type>(<<scope>): <subject>

<body>

<<footer>

---

二、各字段说明

1. type（必填）提交类型

类型	含义	示例
feat	新功能（feature）	feat(user): 添加用户登录功能
fix	修复 bug	fix(api): 修复空指针异常
docs	文档更新	docs(readme): 更新部署说明
style	代码格式调整（不影响逻辑）	style(css): 统一缩进格式
refactor	重构代码	refactor(service): 优化订单查询逻辑
perf	性能优化	perf(db): 添加索引提升查询速度
test	测试相关	test(unit): 补充用户模块单元测试
chore	构建/工具/依赖变动	chore(deps): 升级 spring-boot 至 3.2
ci	CI/CD 配置变更	ci(github): 添加自动部署流程
revert	回滚提交	revert: 回滚 feat(auth) 的 OAuth 改动

2. scope（可选）影响范围

标记修改涉及的模块、组件或文件路径，用括号包裹。

feat(auth): 添加 JWT 鉴权
fix(api/user): 修复用户信息接口
docs(README): 补充环境变量说明

3. subject（必填）简短描述

• 不超过 50 个字符

• 使用祈使句 （现在时），开头不要大写 ，末尾不加句号

• 清晰表达"做了什么"而非"怎么做"

✅ 正确：feat(cart): 添加购物车数量校验

❌ 错误：feat(cart): Added the cart quantity validation.

4. body（可选）详细说明

• 空一行后书写

• 说明为什么修改 、与之前行为的对比 、注意事项

• 每行不超过 72 个字符

fix(payment): 修复微信支付回调超时问题

此前未设置 socket 超时时间，导致网络波动时连接挂起。
现添加 30 秒读写超时，并在超时后触发重试机制。

Closes #234

5. footer（可选）元信息

• BREAKING CHANGE: 不兼容变更说明

• Closes/Fixes/Refs: 关联 Issue 或 PR

  BREAKING CHANGE: 移除对 Node.js 14 的支持，最低版本要求 16+

  Fixes #456

---

三、完整示例

feat(notification): 集成钉钉消息推送

- 支持文本、链接、Markdown 三种消息类型
- 配置项支持多环境切换（dev/prod）
- 默认关闭，需在 application.yml 手动开启

Closes #89

refactor(order): 拆分订单服务为读写分离架构

将订单查询与写入拆分为独立服务，降低数据库锁竞争。
查询服务支持只读副本，写入服务保证事务一致性。

BREAKING CHANGE: 订单查询 API 路径变更
旧：/api/v1/orders
新：/api/v2/orders

Refs #112, #113

---

四、进阶实践建议

1. 提交粒度原则

• 一个提交只做一件事：不要把功能开发和 bug 修复混在一起

• 提交要可编译、可运行：不要提交半成品代码

2. 分支命名配合

feature/user-auth      # 功能分支
fix/memory-leak        # 修复分支
hotfix/payment-crash   # 紧急修复
release/v2.3.0         # 发布分支

3. 工具辅助

• Commitizen：交互式生成规范提交信息

• Husky + commitlint：提交前自动校验格式

• standard-version / semantic-release：自动生成版本号和 CHANGELOG

4. 团队配置示例（.commitlintrc）

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [2, "always", ["feat","fix","docs","style","refactor","test","chore","perf","ci","revert"]],
    "subject-max-length": [2, "always", 50]
  }
}

---

五、快速对照表

场景	推荐写法
新增接口	feat(api): 添加用户列表分页查询
修线上 bug	fix(order): 修复订单金额计算精度丢失
改配置文件	chore(config): 调整日志输出级别
补测试用例	test(payment): 补充退款流程异常场景测试
代码格式化	style(all): 统一使用 2 空格缩进
性能优化	perf(cache): 引入 Caffeine 本地缓存

---

遵循这些规范后，你的 git log 将变得像结构化的变更日志，极大提升团队协作效率和代码可维护性。