研发开发规范 · 提交前检查清单

本篇学习指南

读完你能

每次提交前对照 11 项清单快速自检
用速查卡秒查「这个场景该用什么分支」
养成「改完→检查→提交」的肌肉记忆

阅读时长

约 5 分钟 · 建议收藏，每次提交前翻一遍

前置知识

先通读 01~06，本篇是其浓缩版

接着读

08-其他建议规范

怎么用这份清单

把它当成出门前的「伸手要钱」口诀（身手钥钱 = 身份证、手机、钥匙、钱包）——不是为了背条文，而是形成本能。刚开始可能要逐条对照，一两周后扫一眼就能过。其中第 1 项（分支命名）和第 2 项（提交信息）是底线，这两项不合规在评审环节直接打回（建议启用的 Git Hook 也会拦截），先确保这两项过关。

使用说明

●下面 11 项覆盖从分支名到魔法值的提交全流程，每项右侧标了对应的规范出处。
●「速查卡」帮你快速判断该用哪种分支类型。

改完代码

→ → →

对照清单检查

→ → →

git commit

分支类型速查卡

我要做…	应该用…	基点
开发新功能	`feature/<版本>/xxx`	从开发中 `release` 头拉（已发布版本禁止）
现场报 bug 需修复	`hotfix/<版本>/xxx`	从对应 `release` 分支头拉，禁改库
某客户要定制	`custom/<版本>/客户-xxx`	从对应 `release` 分支头拉，保持下行同步，禁回流
某子产品独立演进	`line/<产品>/<版本>`	从对应主产品 `release` 分支头拉，禁上行回流（详见 01·产品线分支）
我自己临时实验	`dev/<版本>/我的名字-xxx`	用完即删
发布新版本	主产品在 `release/x.x.x` 打 `vX.Y.Z`；子产品在 `line/<产品>/x.x.x` 打 `<产品>-vX.Y.Z`	—

示例（取自 EasyPro 真实分支）：

分支名	说明
`feature/2.1.1/bacnet-cov`	基于 release/2.1.1 开发 BACnet COV 订阅功能
`hotfix/2.1.0/knx隧道假死优化`	基于 release/2.1.0 分支头修复 KNX 隧道假死（中文语义段）
`custom/2.1.0/huzhou-energy`	基于 release/2.1.0 分支头的湖州能耗定制
`line/eos/2.1.0`	基于主产品 release/2.1.0 分支头的 EOS 产品线主线
`feature/eos/2.1.0/择机算法`	基于 line/eos/2.1.0 的 EOS 专属功能
`dev/2.1.1/zhangsan-simulate`	基于 2.1.1 的张三临时模拟实验

提交前 11 项自检清单

每次提交代码前，对照以下清单逐项检查。养成习惯后会变成本能。

不确定的项目可以先跳过，但「分支命名」和「提交信息格式」是最基础的两项，务必掌握。

#	检查项	相关规范
1	分支名符合 `<前缀>/<版本号>/<语义>` 规范？	01-分支与Tag管理
2	提交信息符合 `<type>(<scope>): <subject>`？	02-提交规范
3	改动是否属于客户定制或某子产品专属？若是，是否放在 `custom/` 或 `line/<产品>/`？	03-合并回流
4	SQL 改动是否增量、幂等、无破坏性？	06-SQL版本化
5	SQL 是否按 `<序号>_<语义>.sql` 命名（序号即执行顺序）、放在对应分支目录并登记 CHANGELOG？	06-SQL版本化
6	是否误提交了日志、IDE 配置、构建产物？	08-其他建议
7	接口是否加了 `@Tag`/`@Operation`？格式是否正确？	04-命名与接口
8	Controller 是否返回 `Result<T>`？入参是否 `@Validated`？	05-代码规范
9	事务 `@Transactional` 是否加在 ServiceImpl？	05-代码规范
10	日志是否用 `@Slf4j` + `{}` 占位符？有无敏感信息？	05-代码规范
11	是否有魔法值硬编码、临时调试代码？	05-代码规范

一次合格的提交

SHELL

$ git branch
feature/2.1.1/bacnet-cov     # ✓ 分支规范
$ git diff --cached           # ✓ 先看 diff
 # 只改了 DriverCovService.java
 # 无 target/、无 .log、无 System.out
$ git commit -m "feat(bacnet): 支持COV订阅降级"
 # ✓ type+scope+subject 齐全

11 项全过，hook 放行，review 顺畅

一次踩雷的提交

SHELL

$ git branch
bacnet-dev                    # ✗ 无前缀无版本
$ git add -A                  # ✗ 全加，没diff
 # 夹带了 target/ 和 .log
$ git commit -m "改完了"
 # ✗ hook 直接拦截
 # 就算过了，review 必被打回

第 1、2、6 项全挂，返工三连

为什么强调「先 git diff 再 commit」？因为这一个动作就能挡住清单里一半的问题——误提交的文件、调试代码、魔法值、拼错的分支名，在 diff 里一目了然。养成「commit 前 diff 一遍」的习惯，比事后返工省得多。

新手常见问题

提交被拦、清单项看不懂时，看这里

我 git commit 时 hook 报错了，提交不上去，怎么办？

别慌，这是 hook 在帮你。看报错提示——最常见两种：① 分支名不合规（改成 feature/版本/语义 格式）；② commit message 格式不对（改成 type(scope): 描述）。改对后用 git commit --amend 修改最近一次提交即可，不用从头来。

清单第 11 项「检查项太多记不住」，有没有偷懒办法？

有——前两项（分支命名、提交信息）hook 会自动拦，不用你操心。剩下的项里，第 3 项（定制归属）和 SQL 相关项最容易漏，重点盯这两项。养成「改完先 git diff 看一遍再 commit」的习惯，大部分问题都能在 diff 里发现。

我改的代码通过了清单，但 review 还是被打回？

清单是底线（必过的硬性检查），review 是更高的质量要求（可读性、设计合理性、边界情况）。清单过了只代表「没犯规范错误」，不代表代码完美。被打回是正常的协作过程，按 review 意见改就行。