
Hello,我是小兔大白糖。 Reviewer 打开一个「大功能」PR,Diff 像一锅乱炖:基建、模型、鉴权、业务、测试搅在同一页——想点头却找不到该先验哪一层。写成这篇,给要做 大变更提交与审查切片 心智模型调研的初中级后端同学:不是某仓库的 rebase 工单,而是业界常见的分层拆法。
说明:下文的 L0–L7 是教学骨架,不是某厂「官方分层标准」。Commit 消息、重组手法均为脱敏示意;不绑定具体 hash、工单号或内部包路径。
估计阅读时间:8 分钟
目录
为什么现在要关心
目标不是「commit 越多越好」,而是每个可审查切片只有一个职责平面,合起来仍是一条可部署故事。
一次功能浪潮常留下几十个交织提交。Reviewer 打开 Diff 时,典型痛点是:
| 你看到的 | 常见真相 |
|---|---|
| 相关改动散落多个 commit | 因果链断了,无法按层点头 |
| 一个巨型 commit | 基建与业务合同绑死,无法局部验收 |
| 修 lint 和改对外错误码挤在一起 | CI / bisect / revert 粒度不对 |
| 「先合 API,鉴权下周补」 | 合入窗口期裸奔 |
这和「按文件类型拆 PR」相邻,但焦点不同:文件类型拆法管目录;分层拆法管依赖方向与审查问题。
可复述硬规则(删掉比喻也成立):
- 依赖只能上层引用下层;审查与合入按同序。
- 一个 commit 只回答一个审查问题。
- 中间态优先可编译、可测——至少不破坏主路径编译。
心智模型:盖楼验收
先验地基与管线,再验门锁,再验户型,最后看大门与说明书——验收员不会在「还没装门」时争论墙纸。
| 验收顺序 | 对应层(教学) | Reviewer 在干什么 |
|---|---|---|
| 地基与管线 | L0–L1 | 工具链、客户端、超时与密钥注入是否安全默认 |
| 门锁 | L3 | 有没有绕过路径;过期与吊销 |
| 户型 | L4–L5 | 约束是否匹配查询;事务与副作用边界 |
| 大门与说明书 | L6–L7 | 鉴权是否挂上;测试是否锁住本层行为 |
类比局限:盖楼管 依赖序与审查注意力;解释不了「这一层业务本身该不该做」——产品对错仍要另开讨论,别塞进基建 commit 的评论里。
硬规则:什么叫「一个审查切片」
一个审查切片 = 能用一句话问完「这层单独合进去,系统更稳还是更炸?」的最小合入单元。
三条可检验规则:
-
自下而上分层
依赖方向只能「上层引用下层」。合入也按同序:infra → data → auth → domain → API → tests/docs。层序反了(先合裸 API 再补鉴权)会留下窗口期。 -
一个 commit 一个审查问题
消息与 Diff 应对齐同一问题。写着fix却改了对外错误码合同 → 审查清单错位。 -
可编译、可测的中间态优先
理想情况:每个中间 commitbuild + 单测绿。实在做不到,至少不破坏主路径编译——「为凑层数切出不可编译的半截」等于把审查成本转嫁给 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 消息骨架(脱敏示意,非某仓库真实历史):
坏: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 + 正向按层续写;未推送私有分支才适合改写历史。
| 手法 | 适用 | 代价 / 副作用 |
|---|---|---|
| A. 正向继续,新 PR 按层开 | 历史已推送到共享分支 | 旧历史仍乱;靠新层「盖住」可读性 |
| B. 本地 rebase / reset 再分层 commit | 仅自己未共享分支 | 改写历史;误 force-push 会打同事 |
| C. orphan 新根或按目录生成补丁再分层 | 大爆炸迁仓、历史已不可救 | 成本高;审计链断裂需团队知情 |
| D. 叠 PR:先合 L0–L2,再合业务 | 团队协作默认 | 要协调冻结窗口;中间态对外可见 |
教学倾向:
- 已推送共享主线 → D + 正向 A
- 未推送个人分支 → 可用 B
- C 留给「真的要重写仓库叙事」的少数场景,别当日常爽文
代价先说清:叠 PR 会拉长日历时间;rebase 会让「谁在哪条 tip」变难同步。稳的是选对边界,不是永远改写历史装干净。
常见坑
按文件类型拆、反层序合入、为凑层塞格式化——都会把「一个审查问题」拆坏。
| 反模式 | 为什么炸 |
|---|---|
| 按扩展名 / 目录机械拆,却切断同一不变量 | 模型与唯一索引分到两个不可编译 commit → CI 红、审查无法单独点头 |
| 为凑层数把无关格式化塞进业务 commit | Diff 噪声淹没真正的合同变更 |
| 层序反了:先合 API 再补鉴权 | 合入窗口期裸奔 |
消息写 fix,实际改对外合同 | 审查清单与 changelog 错位;bisect 时语义骗人 |
| 巨型「refactor everything」再挂测试 | 失败时不知道哪一层坏了;revert 粒度等于整锅 |
经验法则:若你无法用一句话描述「这一 commit 单独合入后系统状态」——它还不是一个审查切片。
选型结论
读完这篇,建议带走五条可行动要点:
- 开干前画一张层表,标每层「单独合入是否可编译」。
- Review checklist 按层提问,不按文件名刷。
- 已推送历史用叠 PR + 正向续写;未推送可 rebase 分层。
- 垂直功能在领域 / API 层切开;基建保持薄而先合。
- Bisect / revert 友好 = 分层成功的验收标准之一——比「commit 数量好看」更硬。
不追求八层齐全;追求 依赖方向正确、审查问题单一、中间态可编译。下次开大功能 PR 前,先问一句:Reviewer 能不能像验楼一样,自下而上逐层点头?