大变更按层拆 commit:一个审查问题一层

大变更按层拆 commit:一个审查问题一层

Hello,我是小兔大白糖。 Reviewer 打开一个「大功能」PR,Diff 像一锅乱炖:基建、模型、鉴权、业务、测试搅在同一页——想点头却找不到该先验哪一层。写成这篇,给要做 大变更提交与审查切片 心智模型调研的初中级后端同学:不是某仓库的 rebase 工单,而是业界常见的分层拆法。

说明:下文的 L0–L7 是教学骨架,不是某厂「官方分层标准」。Commit 消息、重组手法均为脱敏示意;不绑定具体 hash、工单号或内部包路径。

估计阅读时间:8 分钟


目录


为什么现在要关心

目标不是「commit 越多越好」,而是每个可审查切片只有一个职责平面,合起来仍是一条可部署故事。

一次功能浪潮常留下几十个交织提交。Reviewer 打开 Diff 时,典型痛点是:

你看到的常见真相
相关改动散落多个 commit因果链断了,无法按层点头
一个巨型 commit基建与业务合同绑死,无法局部验收
修 lint 和改对外错误码挤在一起CI / bisect / revert 粒度不对
「先合 API,鉴权下周补」合入窗口期裸奔

这和「按文件类型拆 PR」相邻,但焦点不同:文件类型拆法管目录;分层拆法管依赖方向与审查问题。

可复述硬规则(删掉比喻也成立):

  1. 依赖只能上层引用下层;审查与合入按同序。
  2. 一个 commit 只回答一个审查问题。
  3. 中间态优先可编译、可测——至少不破坏主路径编译。

心智模型:盖楼验收

先验地基与管线,再验门锁,再验户型,最后看大门与说明书——验收员不会在「还没装门」时争论墙纸。

盖楼验收:L0–L1 地基管线,L3 门锁,L4–L5 户型,L6–L7 大门与说明书,自下而上
盖楼验收:L0–L1 地基管线,L3 门锁,L4–L5 户型,L6–L7 大门与说明书,自下而上 · 点击查看 SVG 原图
验收顺序对应层(教学)Reviewer 在干什么
地基与管线L0–L1工具链、客户端、超时与密钥注入是否安全默认
门锁L3有没有绕过路径;过期与吊销
户型L4–L5约束是否匹配查询;事务与副作用边界
大门与说明书L6–L7鉴权是否挂上;测试是否锁住本层行为

类比局限:盖楼管 依赖序与审查注意力;解释不了「这一层业务本身该不该做」——产品对错仍要另开讨论,别塞进基建 commit 的评论里。


硬规则:什么叫「一个审查切片」

一个审查切片 = 能用一句话问完「这层单独合进去,系统更稳还是更炸?」的最小合入单元。

三条可检验规则:

  1. 自下而上分层
    依赖方向只能「上层引用下层」。合入也按同序:infra → data → auth → domain → API → tests/docs。层序反了(先合裸 API 再补鉴权)会留下窗口期。

  2. 一个 commit 一个审查问题
    消息与 Diff 应对齐同一问题。写着 fix 却改了对外错误码合同 → 审查清单错位。

  3. 可编译、可测的中间态优先
    理想情况:每个中间 commit build + 单测 绿。实在做不到,至少不破坏主路径编译——「为凑层数切出不可编译的半截」等于把审查成本转嫁给 CI。

后端类比:分层像 连接池分层预算——外层并发别穿透打穿内层上限;这里是审查注意力别被下层噪声淹没。类比只管「别超售注意力」,管不了业务语义对错。


常见分层骨架(L0–L7)

业务大功能可在领域 / 接口层再垂直切片;不要把工具链与 handler 揉进同一 commit。

层典型内容Review 问什么
L0 工具链module、lint、CI、gitignore会不会无谓加严拖垮全员?
L1 基础设施DB/缓存客户端、配置、日志连接 / 超时 / 密钥注入是否安全默认?
L2 契约与错误统一响应、错误码对外合同稳吗?
L3 安全边界鉴权中间件、会话绕过路径?过期与吊销?
L4 模型与仓储schema、索引、repository约束与查询是否匹配?
L5 领域服务用例编排事务边界?副作用?
L6 接口HTTP / GraphQL / handler鉴权与校验是否挂上?
L7 测试与文档单测、契约测、README是否锁住本层行为?

垂直切片(先读路径、再写路径)适合落在 L5 / L6。L0 与 L6 同 commit → 审查问题从「一两句」膨胀成「整锅」。

层数可以裁剪:小改动不必硬凑满八层;裁的是空层,不是依赖方向。


示意:缠绕 vs 分层栈

坏历史像毛线团;好历史像可抽检的楼层——同一条故事,审查粒度不同。

左侧乱炖巨型 commit;右侧自下而上分层栈,每层一个审查问题
左侧乱炖巨型 commit;右侧自下而上分层栈,每层一个审查问题 · 点击查看 SVG 原图

教学向 commit 消息骨架(脱敏示意,非某仓库真实历史):

坏:feat: everything (infra + auth + biz + ui)

好:
  chore(tooling): lint / module baseline
  feat(infra): db / cache clients
  feat(auth): session middleware
  feat(domain): use-case orchestration
  feat(api): handlers wire-up
  test: cover read / write paths

消息前缀(chore / feat / test)只是约定提示;真正约束是层与审查问题一一对应,不是前缀拼写本身。


历史已乱时怎么重组

共享主线优先叠 PR + 正向按层续写;未推送私有分支才适合改写历史。

四种重组:正向续写、本地 rebase、orphan 重建、叠 PR;标注适用与风险
四种重组:正向续写、本地 rebase、orphan 重建、叠 PR;标注适用与风险 · 点击查看 SVG 原图
手法适用代价 / 副作用
A. 正向继续,新 PR 按层开历史已推送到共享分支旧历史仍乱;靠新层「盖住」可读性
B. 本地 rebase / reset 再分层 commit仅自己未共享分支改写历史;误 force-push 会打同事
C. orphan 新根或按目录生成补丁再分层大爆炸迁仓、历史已不可救成本高;审计链断裂需团队知情
D. 叠 PR:先合 L0–L2,再合业务团队协作默认要协调冻结窗口;中间态对外可见

教学倾向:

  • 已推送共享主线 → D + 正向 A
  • 未推送个人分支 → 可用 B
  • C 留给「真的要重写仓库叙事」的少数场景,别当日常爽文

代价先说清:叠 PR 会拉长日历时间;rebase 会让「谁在哪条 tip」变难同步。稳的是选对边界,不是永远改写历史装干净。


常见坑

按文件类型拆、反层序合入、为凑层塞格式化——都会把「一个审查问题」拆坏。

反模式为什么炸
按扩展名 / 目录机械拆,却切断同一不变量模型与唯一索引分到两个不可编译 commit → CI 红、审查无法单独点头
为凑层数把无关格式化塞进业务 commitDiff 噪声淹没真正的合同变更
层序反了:先合 API 再补鉴权合入窗口期裸奔
消息写 fix,实际改对外合同审查清单与 changelog 错位;bisect 时语义骗人
巨型「refactor everything」再挂测试失败时不知道哪一层坏了;revert 粒度等于整锅

经验法则:若你无法用一句话描述「这一 commit 单独合入后系统状态」——它还不是一个审查切片。


选型结论

读完这篇,建议带走五条可行动要点:

  1. 开干前画一张层表,标每层「单独合入是否可编译」。
  2. Review checklist 按层提问,不按文件名刷。
  3. 已推送历史用叠 PR + 正向续写;未推送可 rebase 分层。
  4. 垂直功能在领域 / API 层切开;基建保持薄而先合。
  5. Bisect / revert 友好 = 分层成功的验收标准之一——比「commit 数量好看」更硬。

不追求八层齐全;追求 依赖方向正确、审查问题单一、中间态可编译。下次开大功能 PR 前,先问一句:Reviewer 能不能像验楼一样,自下而上逐层点头?