06-代码提交规范Commitlint统一提交日志、版本迭代追溯前言打开团队 Git 仓库的提交记录画风是这样的update fix bug 修改了一下 test 123 我改了点东西看这些提交信息你能知道改了什么出了问题想回溯某个功能是哪次提交引入的做梦。本文讲清楚两件事Conventional Commits 提交规范是什么、怎么写Commitlint Husky怎么集成到项目里让团队成员不按规范写就提交不上去。一、Conventional Commits 规范详解1.1 规范长什么样Conventional Commits约定式提交是一个广泛使用的 Git 提交信息规范核心思想是让每条提交信息有固定格式机器可读、人类可理解。标准格式如下type(scope): subject body footer一个真实的例子feat(gateway): 新增设备心跳上报接口 新增 /api/device/heartbeat 接口支持售货柜设备每30秒上报状态 心跳数据写入 Redis超时设备自动标记离线 Closes #1231.2 type 类型全解type含义示例场景feat新功能feature新增设备注册接口fix修复 Bug修复心跳上报超时判断错误docs文档变更更新 API 文档style代码格式调整不影响逻辑格式化代码、调整缩进refactor重构既不是新功能也不是修 Bug提取公共方法、拆分大类test测试相关新增单元测试chore构建/工具/依赖变更升级 Spring Boot 版本perf性能优化优化 SQL 查询性能build构建系统或外部依赖变更修改 DockerfileciCI 配置变更修改 GitHub Actions 配置revert回退之前的提交回退某次错误的功能发布1.3 scope作用域scope 是可选的用来标明改动的范围/模块。在微服务项目中特别有用feat(user-service): 新增用户注册接口 fix(gateway): 修复路由转发空指针 chore(pom): 升级Spring Boot至3.2.01.4 subject主题行使用祈使句、现在时“add” 而不是 “added”首字母小写结尾不加句号控制在 50 字符以内1.5 body 和 footerbody用于补充详细说明解释为什么改而不是改了什么代码本身能看到改了什么。footer用于关联 Issue 或标记 Breaking ChangeBREAKING CHANGE: 设备注册接口返回格式从数组改为对象前端需要同步适配 Closes #4561.6 完整规范示例fix(cabinet-sensor): 修复售货柜重力传感器重量校准偏差 # 问题 设备上架后传感器读数持续偏移导致商品识别准确率下降 # 原因 校准流程缺少温度补偿系数环境温度变化时传感器零点漂移 # 方案 新增温度补偿算法校准时读取环境温度并修正基准值 Closes #789二、Commitlint 配置2.1 安装依赖在项目根目录执行npminstall--save-dev commitlint/cli commitlint/config-conventional2.2 创建配置文件在项目根目录创建commitlint.config.jsmodule.exports{extends:[commitlint/config-conventional],rules:{// type 枚举限制type-enum:[2,always,[feat,fix,docs,style,refactor,test,chore,perf,build,ci,revert]],// type 不能为空type-empty:[2,never],// subject 不能为空subject-empty:[2,never],// subject 最大长度subject-maxlength:[2,always,100],// subject 不以句号结尾subject-full-stop:[2,never,.]}};规则中数字含义0disabled关闭1warning警告仍可提交2error报错阻止提交2.3 测试验证# 正确格式通过echofeat(gateway): 新增设备心跳接口|npx commitlint# 错误格式报错echoupdate something|npx commitlint# ⧗ input: update something# ✖ subject may not be empty [subject-empty]# ✖ type may not be empty [type-empty]三、Husky Git Hook 集成光有 Commitlint 配置还不够成员可以绕过检查直接用git commit --no-verify。需要在commit-msg这个 Git Hook 上挂载检查而 Husky 就是管理 Git Hook 的利器。3.1 安装 Huskynpminstall--save-dev husky3.2 初始化 Husky# package.json 中添加 prepare 脚本npmpkgsetscripts.preparehusky install# 执行安装npmrun prepare# 创建 commit-msg hooknpx huskyadd.husky/commit-msgnpx --no-install commitlint --edit $13.3 验证 Hook 生效当 Husky 配置完成后任何不合规的提交都会被拦截gitcommit-m随便写的# ⧗ input: 随便写的# ✖ type may not be empty [type-empty]# ✖ found 1 problems, 0 warnings# husky - commit-msg hook exited with code 1提交直接被拒绝必须按规范来。3.4 Java 项目的适配方案如果项目是纯 Maven/Gradle 的 Java 项目没有package.json可以单独建一个最小的package.json只用于管理 Git Hook{name:device-gateway,version:1.0.0,private:true,devDependencies:{commitlint/cli:^19.0.0,commitlint/config-conventional:^19.0.0,husky:^9.0.0},scripts:{prepare:husky install}}首次 clone 项目后执行npm install即可激活 Hook。四、版本迭代追溯实践4.1 自动生成 CHANGELOG规范化的提交信息最大的价值之一可以用工具自动生成变更日志。npminstall--save-dev conventional-changelog-cli# 生成 CHANGELOG.mdnpx conventional-changelog-pangular-iCHANGELOG.md-s-r0生成的 CHANGELOG 内容示例## 1.2.0 (2025-08-01) ### Features * **gateway**: 新增设备心跳上报接口 * **cabinet**: 支持重力传感器自动校准 ### Bug Fixes * **gateway**: 修复心跳超时判断逻辑错误 ### Breaking Changes * **gateway**: 设备注册接口返回格式变更4.2 按类型过滤提交记录追溯某个功能是何时引入的# 查看所有 feat 提交gitlog--grep^feat# 追溯心跳接口的引入历史gitlog--grepheartbeat4.3 自动化版本号语义配合standard-version或semantic-release工具可以根据提交类型自动决定版本号递增有feat→ minor 版本 1如 1.2.0 → 1.3.0有fix→ patch 版本 1如 1.2.0 → 1.2.1有BREAKING CHANGE→ major 版本 1如 1.2.0 → 2.0.0npminstall--save-dev standard-version# 自动分析提交记录生成版本号和CHANGELOGnpx standard-version五、团队落地建议先规范后强制先在团队内宣贯规范给一周适应期再用 Husky 强制拦截提供模板在项目根目录放一份COMMIT_TEMPLATE.txtIDE 配置使用模板CI 层兜底在 CI/CD 流水线加一层commitlint检查双重保险Code Review 闭环PR 审查时如果发现不合规提交要求 squash 合并并修改 message总结提交规范不是形式主义它是团队协作的基础设施。规范的提交信息带来三个直接收益收益说明可追溯根据提交类型快速定位功能引入/修复记录可自动化自动生成 CHANGELOG、自动版本号可审查Code Review 时一眼看清每个提交的意图Conventional Commits 定义规范Commitlint 校验规范Husky 强制规范三者组合拳打下来团队的提交日志就不再是自由发挥了。
