迭代与协作
本合集目录
本章目录
单册说明:本文件是卷 8 的第 5 章,可独立阅读。前置:第 4 章(安全清单)。本章让"下一次改动"变得可预测:issue 怎么写、提交信息怎么留、多久发一次、坏了怎么回、和别人怎么约定接口。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 8 · 从作品到产品(第 5 / 6 章) |
| 前置章节 | 8.4 安全清单 |
| 本章产出 | 5 条可执行的 issue + 一份提交信息规范与检查脚本 + CHANGELOG + 回滚预案 |
| 对应代码 | scripts/check_commit_msg.py、.githooks/commit-msg、CHANGELOG.md |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 任何人打开仓库,能看懂"为什么改、改了什么、坏了怎么退" |
8.5.1 一句话结论:让下一次改动的成本可预测
三个月后,你想改标签的合并逻辑。打开 git log:
update
fix bug
修改
update
test
最终版
七条提交,没有一条说清改了什么、为什么改。你翻了半小时聊天记录,找到一句"当时好像是因为标签重复",然后决定"算了,别动了"。
同一周,一次发布让登录接口 500。你想回滚,发现上一次部署是"攒了两周的大合并",回滚等于把五个功能一起撤掉;而数据库里已经多了一个 NOT NULL 的新列,旧代码写不进去。最后花了 40 分钟手工修数据。
一句话结论:迭代与协作的全部目的,是把"改坏了"从一场事故,变成一次可预期、可撤销的操作。
这件事和团队规模无关。一个人写代码,也需要三个月后的自己看得懂;一个人发布,也需要知道坏了怎么退。
8.5.2 原理与方法
issue:把"感觉不对"变成可复现的事实
一条能用的 issue 必须让另一个人不看你的屏幕也能复现。六个字段,缺一个就会来回问:
| 字段 | 写什么 | 反例 |
|---|---|---|
| 环境 | 浏览器/系统、账号、时间 | "我的电脑" |
| 复现步骤 | 编号,每步一个动作 | "点几下就出错了" |
| 期望 | 你认为应该发生什么 | "不正常" |
| 实际 | 实际发生了什么,含准确报错 | "坏了" |
| 证据 | 响应体、日志、截图 | 无 |
| 影响面 | 谁能遇到、数据是否受影响 | 无 |
模板长这样,直接存成 docs/issue-template.md,提 issue 时整段复制:
## 环境
- 浏览器 / 系统:
- 账号:
- 时间:
## 复现步骤
1.
2.
3.
## 期望
## 实际
## 证据(响应体 / 日志 / 截图)
## 影响面(谁会遇到、是否丢数据)
写 issue 的过程本身就是排查的一半。很多人写到"复现步骤"第 3 步时,自己就发现了问题——因为被迫把动作拆成了可验证的小步。
提交信息:一句话说清"改了什么、为什么"
格式固定成三行结构:
<类型>: <一句话,不超过 50 字>
为什么改、影响什么。可以多行,每行不超过 72 字。
类型只用六个,够覆盖个人项目:
| 类型 | 用于 | 例子 |
|---|---|---|
feat |
新功能 | feat: 按标签筛选支持多选 |
fix |
修 bug | fix: 标签去重时忽略大小写 |
refactor |
不改行为的重构 | refactor: 把标签规范化抽到 service |
docs |
文档 | docs: README 补本地启动三步 |
test |
测试 | test: 补越权读取的接口用例 |
chore |
构建、依赖、脚本 | chore: 升级 pytest 到当前稳定版 |
对照一下好坏:
| 提交信息 | 问题 | 三个月后能回答什么 |
|---|---|---|
update |
没说改什么 | 什么都回答不了 |
fix bug |
没说哪个 bug | 只能靠 diff 猜 |
修改标签 |
没说为什么 | 知道改了标签,不知道为什么 |
fix: 标签去重时忽略大小写 |
合格 | 改了什么、哪个场景,一目了然 |
为什么值得花这十秒:git log 是项目的日记,git blame 是排错时的地图,git revert 需要一条边界清晰的提交。三条都依赖提交信息可读。省下的十秒,会在半年后以小时为单位还回来。
分支与发布:小步合并,别攒大招
| 方式 | 合并频率 | 冲突成本 | 回滚粒度 | 适合 |
|---|---|---|---|---|
| 短分支 | 每 1–2 天 | 低,通常 1–2 个文件 | 单个提交 | 个人项目、小团队 |
| 长期分支 | 每 2 周 | 高,几十个文件冲突 | 整包 | 有 QA 流程的团队 |
| 发布火车 | 每周固定一天 | 中 | 一个版本 | 有外部用户、需要预告 |
「读到」用短分支:从 main 切出,改完当天合并,合并即部署。规则只有两条:
- 分支存活不超过 2 天——超过就说明这件事该拆了;
- 合并前测试必须绿——第 2 章那 9 条,跑一次 2 秒,没有借口跳过。
CHANGELOG:写给用户,不是写给 git
变更记录不是 git log 的复制。它按版本组织,只写对使用者的影响:
# 变更记录
## [1.2.0] - 2026-11-20
### 新增
- 按标签筛选支持多选,最多同时选 5 个
### 修复
- 标签大小写不同(Python / python)导致保存失败
### 变更
- 列表接口不再返回摘录全文,首屏加载明显变快
## [1.1.0] - 2026-11-08
### 新增
- 摘录支持编辑与删除
三条规则:按版本倒序;分类只用"新增/修复/变更/移除";每条写"用户感知到什么",不写"改了哪个函数"。版本号遵循"有新增功能升次版本,只有修复升补丁版本"即可,不必严格。
回滚预案:发布之前先写
发布前回答三个问题,写进 docs/release.md:
| 问题 | 「读到」的答案(示例) |
|---|---|
| 怎么判断这次发布坏了 | 健康检查 /health 非 200,或 5 分钟内 5xx 超过 10 次 |
| 回滚命令是什么 | git revert <提交> → 推送 → 服务器 git pull → systemctl restart dudao-api |
| 数据能不能跟着回滚 | 代码能,数据不能;所以迁移必须向前兼容 |
第三行是重点。代码回滚是分钟级,数据回滚是小时级,有时不可能。 因此数据库变更要遵守"三步走":
| 步骤 | 做什么 | 为什么 |
|---|---|---|
| 第一次发布 | 只加列/加表,允许为空,新旧代码都能跑 | 旧代码不知道新列也不会报错 |
| 第二次发布 | 代码开始写新列、读新列 | 此时回滚代码,新列还在但不影响旧逻辑 |
| 第三次发布 | 确认稳定后,才加约束或删旧列 | 不可逆的动作放最后 |
一次发布就加 NOT NULL 新列,是回滚失败的经典原因:代码退回去了,旧 INSERT 不带这一列,直接违反约束。
和别人协作:先把接口约定写死
两个人以上,最容易吵的不是代码风格,是字段。约定写进 docs/api.md,至少包含四件事:
| 项 | 约定 | 例子 |
|---|---|---|
| 字段名与类型 | 驼峰还是下划线,统一 | 响应用 snake_case,与数据库一致 |
| 错误结构 | 固定一个形状 | {"detail": "人话", "code": "NOTE_NOT_FOUND"} |
| 状态码语义 | 401/403/404/422 各表示什么 | 401 未登录,403 无权,404 不存在 |
| 变更规则 | 加字段兼容,删/改字段算破坏性变更 | 破坏性变更提前一个版本通知 |
加字段是兼容的,改字段名不是。 前端不会因为多了一个字段崩溃,但会因为 title 改名成 name 而白屏。这条规则能让前后端各自推进,不必每次联调都对齐。
8.5.3 动手:五个动作
动作一:把接下来的五件事写成 issue
不要写"优化性能"这种无法验收的标题。五行示例:
| # | 标题 | 类型 | 优先级 | 验收标准 |
|---|---|---|---|---|
| 1 | 标签大小写不同导致保存 500 | bug | P0 | 输入 Python / python 共用同一标签,不报错 |
| 2 | 4G 网络下列表首屏 4.2 秒 | 性能 | P1 | P95 < 1 秒,首屏 < 2.5 秒 |
| 3 | 未登录访问 /notes 白屏 | bug | P1 | 跳转登录页,登录后回到 /notes |
| 4 | 支持导出 Markdown | 功能 | P3 | 单条导出含标题、正文、来源、标签 |
| 5 | README 缺本地启动步骤 | 文档 | P2 | 新人照做能在 10 分钟内跑起来 |
优先级只看两件事:是否丢数据/泄数据(是则 P0)、是否阻断主线(是则 P1)。"想做"不是优先级。
动作二:给提交信息加一道自动检查
"""校验提交信息:类型前缀 + 首行不超过 50 字 + 正文前空行。"""
import sys
TYPES = ("feat", "fix", "refactor", "docs", "test", "chore")
MAX_LEN = 50
def check(message: str) -> list[str]:
lines = message.splitlines()
if not lines or not lines[0].strip():
return ["首行为空:提交信息必须有一句标题"]
subject = lines[0].rstrip()
problems = []
prefix = subject.split(":", 1)[0]
if ":" not in subject or prefix not in TYPES:
problems.append(f"首行要用 {'/'.join(TYPES)}: 开头,当前是「{subject}」")
if len(subject) > MAX_LEN:
problems.append(f"首行 {len(subject)} 字,超过 {MAX_LEN} 字")
if len(lines) > 1 and lines[1].strip():
problems.append("第 2 行必须是空行,正文从第 3 行开始")
return problems
def main(path: str) -> int:
with open(path, encoding="utf-8") as f:
message = f.read()
problems = check(message)
if not problems:
return 0
print("提交信息不合规:")
for item in problems:
print(f" - {item}")
print("示例:fix: 标签去重时忽略大小写")
return 1
if __name__ == "__main__":
if len(sys.argv) != 2:
print("用法:python scripts/check_commit_msg.py .git/COMMIT_EDITMSG")
raise SystemExit(2)
raise SystemExit(main(sys.argv[1]))
挂成 Git 钩子。钩子不随仓库走,所以放进 .githooks/ 并配置路径:
mkdir -p .githooks
cat > .githooks/commit-msg <<'HOOK'
#!/usr/bin/env sh
python scripts/check_commit_msg.py "$1"
HOOK
chmod +x .githooks/commit-msg
git config core.hooksPath .githooks
之后每次 git commit 都会先过一遍。试着提交 update,会被拦下:
提交信息不合规:
- 首行要用 feat/fix/refactor/docs/test/chore: 开头,当前是「update」
示例:fix: 标签去重时忽略大小写
Windows 上钩子由 Git Bash 执行,chmod 不生效也没关系,sh 能读就行。
动作三:建 CHANGELOG.md 并在发布时更新
把上一节的格式存成文件,发布前从 git log 里挑"用户能感知的",翻译成人话。不要自动生成全文——自动生成的日志里 80% 是 chore 和 test,用户不关心。
动作四:发布与回滚各走一遍
# 发布:打标签
git tag -a v1.2.0 -m "v1.2.0: 标签多选筛选"
git push origin main --tags
# 服务器上
cd /srv/dudao && git pull --ff-only
sudo systemctl restart dudao-api
curl -fsS https://dudao.example.com/health || echo "健康检查失败,准备回滚"
# 回滚:撤销那一条提交(保留历史,可再次回滚)
git revert --no-edit <出问题的提交>
git push origin main
# 服务器上
cd /srv/dudao && git pull --ff-only
sudo systemctl restart dudao-api
curl -fsS https://dudao.example.com/health
用 revert 而不是 reset --hard:前者生成一条新提交,历史完整,别人拉取不会冲突;后者改写历史,一旦推送过就很难收场(详见附录 C)。
动作五:写下接口约定
在 docs/api.md 里固定错误结构,并让代码真的这么返回:
{
"detail": "无权访问这条摘录",
"code": "NOTE_FORBIDDEN"
}
前端只需要判断 code,不用匹配中文文案。文案以后想改就改,契约不变。
发布前 60 秒检查表
把这张表贴在发布脚本旁边,每次照着走一遍,比"我觉得没问题"可靠:
| 检查 | 命令 | 期望 |
|---|---|---|
| 测试全绿 | python -m pytest -q |
9 passed |
| 健康检查 | curl -fsS https://你的域名/health |
{"status":"ok"} |
| 版本正确 | git describe --tags |
本次要发布的 tag |
| 今天有备份 | ls -lh /srv/backup | tail -3 |
日期是今天 |
| 回滚目标明确 | git log --oneline -5 |
知道要 revert 哪一条 |
| 日志无异常 | tail -50 /var/log/nginx/error.log |
没有新的 5xx 刷屏 |
8.5.4 三个坑
坑 1:提交信息全是 update
症状:git log --oneline 刷三屏,没有一条能看出改了什么;排错时只能逐条看 diff。
成因:把提交当成"保存一下",觉得信息不重要。
修法:装 commit-msg 钩子,强制前缀和长度;写不出"为什么"时,说明这次改动还没想清楚,先别提交。
坑 2:攒两周再合并
症状:合并时 40 个文件冲突,解决冲突花了一下午;上线出问题,只能整包回滚。 成因:怕麻烦、想"做完一起提",或者分支拉得太早。 修法:分支不超过 2 天,做完一个可验证的小步就合并;大功能拆成"先加字段(不影响界面)→ 再加接口 → 最后接界面"三次提交,每次都能独立回滚。
坑 3:代码回滚了,数据没回滚
症状:回滚后所有新建摘录报 500,日志是 NOT NULL constraint failed: notes.visibility。
成因:迁移和代码同一次发布,且新列设了 NOT NULL 无默认值;旧代码不知道这一列。
修法:迁移永远向前兼容——先加可空列,代码兼容两版,最后才加约束。回滚预案里明确写"数据不回滚,只回滚代码",并确认旧代码能读新数据。
本章验收
- 仓库里有 5 条 issue,每条含复现步骤、期望、实际、验收标准
-
commit-msg钩子生效:提交update会被拒绝 - 有一次完整的
feat:或fix:提交,正文写清了"为什么" -
CHANGELOG.md有至少两个版本,条目写的是用户影响 -
docs/release.md写清了三件事:怎么判断坏、回滚命令、数据能否回滚 - 实际执行过一次
git revert并验证服务恢复
自测
Q1:为什么回滚用 git revert 而不是 git reset --hard?
看答案
`revert` 生成一条反向提交,历史保留,已经拉取过代码的人不会冲突,而且这次回滚本身也能再被回滚。`reset --hard` 把分支指针往回挪,等于删掉历史;如果已经推送,别人再拉取会出现分叉,必须强制推送,风险很高。只有在"提交还没推送、只是本地弄乱了"时,才用 reset。Q2:一次发布包含 6 个功能,上线后发现其中一个有问题。回滚的代价是什么?
看答案
另外 5 个功能一起被撤掉,用户看到的是"昨天能用的功能今天没了",而且如果这次发布带了数据库迁移,回滚代码还可能不兼容新数据。这就是"攒大招"的隐性成本:回滚粒度等于发布粒度。小步发布的价值不在于快,而在于**出问题时只损失一小步**。Q3:接口加一个字段算不算破坏性变更?改字段名呢?
看答案
加字段不算:旧客户端会忽略不认识的字段,行为不变。改字段名算:旧客户端读不到原字段,直接拿到 `undefined`,页面空白或报错。删字段也算。规则是"只加不改不删";必须改时,先同时返回新旧两个字段,等调用方迁完再删旧的。下一步
改动有了记录、能回滚,最后一章把整个项目讲给外人听:README、三分钟演示、复盘,以及简历上的那一行。