跳到正文
零到全栈 · 卷 8 · 从作品到产品

迭代与协作

本合集目录
本章目录

单册说明:本文件是卷 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 切出,改完当天合并,合并即部署。规则只有两条:

  1. 分支存活不超过 2 天——超过就说明这件事该拆了;
  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、三分钟演示、复盘,以及简历上的那一行。

→ 卷8-06-把项目讲清楚.md