一、主流规范：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 个字符
bash
fix(payment): 修复微信支付回调超时问题
此前未设置 socket 超时时间，导致网络波动时连接挂起。
现添加 30 秒读写超时，并在超时后触发重试机制。
Closes #2345. 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）
javascript
{
"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 将变得像结构化的变更日志，极大提升团队协作效率和代码可维护性。