SDD + Harness 四周学习计划 · Week 3 · Day 18（工程化闭环第 4 课 / 全计划第 1 个实操日）
今日主题：实操：spec 变成可执行验收——写 Gherkin 场景（Given/When/Then）或跑契约测试
建议用时：90 分钟（实操日可稍多）｜ 前置：Day 5 的
Day5-spec-<功能名>.md+ Day 15 四类契约 + Day 16 规范即测试输出物：把 Day 5 spec 的验收标准转写成 ≥3 条 Gherkin 场景（或一份可跑的契约测试）+ 转写对照表
0. 一句话剧透
关键衔接日。Day 5 你写了一份 spec，验收标准已经是 Given-When-Then 的雏形；Day 16 你学了「规范即测试」——测试从规范长出来。今天把这两头接上：把 Day 5 的验收标准正式转写成 Gherkin（Given/When/Then）场景，或跑一份契约测试。从今天起，「验收」不再是一段文字，而是一段可以被 CI/CD 执行的东西。
你的 Day 5 素材就在
Day5-spec-<功能名>.md（如 Day 7 修订过，优先用 v2）。这份文件是今天的唯一输入。
1. 今日目标（学完你能做到）
- 能写出标准 Gherkin 场景（Feature / Scenario / Given / When / Then 结构正确）
- 能把 Day 5 spec 的主路径 + 失败路径 + 边界条件各转写成至少 1 条场景
- 能说清「一条 AC 对应一条 Scenario」还是「一条 AC 多条 Scenario」
- 能判断自己的场景是否可执行（没有形容词、没有歧义动作）
- （可选）能跑通一个契约测试的最小示例
2. 学习动线（实操专用时间盒）
| 步骤 | 内容 | 用时 |
|---|---|---|
| 1 | 第 3 节：Gherkin 三要素与模板 | 10 分钟 |
| 2 | 第 4 节：从 AC 到 Scenario 的转写方法 + 范例 | 20 分钟 |
| 3 | 第 5 节：选契约测试路线时的做法 | 10 分钟 |
| 4 | 实操第 6 节：转写 ≥3 条 Gherkin | 35–45 分钟 |
| 5 | 存盘 + 自测 | 10 分钟 |
3. Gherkin：让验收标准可执行
Gherkin 是行为驱动开发（BDD）的标准场景描述格式（已核验）：Given（前置条件）→ When（操作）→ Then（预期结果）。
标准结构：
1
2
3
4
5
6
7
8
9
Feature: <功能名>
作为 <角色>
我想要 <能力>
以便 <价值>
Scenario: <场景名>
Given <前置条件>
When <操作>
Then <预期结果>
- Given：初始状态（数据、环境、登录态）
- When：用户/AI 的动作
- Then：可观测、可断言的预期结果（带数字）
关键：Then 里出现「快速、友好、稳定」任何一个形容词，这条场景就不可执行——回到 Day 5 的翻译工具包，把它换成数字 + 判定规则。
4. 从 Day 5 的 AC 到 Gherkin：转写方法
Day 5 的验收标准长这样（以 Day 5 样张「用户头像上传」为例，别照抄，用你自己的 spec）：
1
2
AC-1（主路径）：Given 已登录用户选择一张 ≤5MB 的 jpg/png/webp，When 提交上传，
Then 接口 200 且返回稳定 URL，页面刷新后头像更新，全流程 ≤3s。
转写为 Gherkin：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
Feature: 用户头像上传
作为 已登录用户
我想要 上传一张头像
以便 评论与资料页显示我的样子
Scenario: 主路径上传成功
Given 我已登录
And 我选择一张 3MB 的 jpg 图片
When 我提交上传
Then 接口返回 200
And 返回一个稳定 URL
And 页面刷新后头像更新
And 全流程耗时 ≤3s（4G 网络、样例集 50 张）
Scenario: 文件超限被拒
Given 我已登录
And 我选择一张 6MB 的 png 图片
When 我提交上传
Then 接口返回 4xx
And 返回明确错误码
And 不落任何文件
Scenario: 未登录被拒
Given 我未登录
When 我调用上传接口
Then 返回 401
And 不执行上传
转写三步法（记住这个套路）：
- 抽前置：AC 里 Given 后面的状态 → 你的 Given（登录态、数据规模、输入文件）
- 抽动作：AC 里 When 后面的动作 → 你的 When（提交、调用、选择）
- 抽断言：AC 里 Then 后面的结果（含数字）→ 你的 Then（状态码、耗时、落库与否）
判断规则：一条 AC 如果只有一个「前置 + 动作 + 结果」组合，就转成 1 条 Scenario；如果一条 AC 覆盖多条路径，就拆成多条 Scenario——目标是每条 Scenario 只有一个清晰的断言场景。
5. 选契约测试路线时（可选）
如果今天想跑契约测试而不是只写 Gherkin，思路是（已核验工具）：用 OpenAPI 定义接口契约 → 契约测试校验实现是否符合契约；没有真实服务时用 Mock Server 按契约生成模拟服务。数据契约侧可用 Pydantic 校验。最小实践建议：
- 从 Day 5 spec 挑一个接口，写一份最小 OpenAPI/JSON Schema（数据契约）；
- 用工具生成校验（Pydantic 或 OpenAPI Generator 任一即可；环境装不了就标「待核验」并记录）；
- 跑通「合法输入过、非法输入拒」两个断言即算完成。
环境受限时不用强求：把 Gherkin 写好本身就是 Day 20 的验收证据，契约测试可在 Day 20 一并补。
6. 今日实操（约 60–80 分钟）
Step 1 取出 Day 5 spec（5 分钟）
找到你的 Day5-spec-<功能名>.md（如没有，用 Day 7 修订的 v2）。
Step 2 挑 3 条验收（10 分钟）
必须覆盖三类：
- 主路径成功 1 条（如 AC-1）
- 失败/异常路径 1 条（如 AC-3 非法输入）
- 边界条件 1 条（如 AC-4 未登录 / 并发 / 超时）
Step 3 写 Gherkin（30–40 分钟）
按第 4 节模板写 Week3-Day18-<功能名>-acceptance.feature，≥3 条 Scenario。写完逐条自检：
- Given 有没有写清初始状态？
- When 是不是单一动作？
- Then 有没有数字/判定规则？零形容词？
- 每条场景能对应回 Day 5 的哪条 AC？
Step 4 填转写对照表（10 分钟）
| Day 5 AC 编号 | 对应 Scenario | 转写时我改动/补充了什么 |
|---|---|---|
| AC-1 | 主路径上传成功 | 补了样例大小（3MB） |
| AC-3 | 文件超限被拒 | 补了「不落任何文件」的断言 |
| … | … | … |
Step 5 存盘与记录（5 分钟）
文件存本目录。文末写一句：今天最卡的是把哪条 AC 转成 Given 还是 Then？（Day 21 复盘要用）
7. 自测题
- Gherkin 的三个关键字是什么？各自对应什么？
- 一条 AC 什么时候拆成多条 Scenario？
- Then 里出现「快速」为什么不行？怎么改？
- 未登录返回 401 这条验收，Given/When/Then 分别怎么写？
- 契约测试、Mock Server、Pydantic 各解决什么？
- 今天产出的 .feature 文件，Day 17 的哪道门禁可以直接消费它？
答案与提示：
- Given（前置条件）/ When（操作）/ Then（预期结果）。
- 一条 AC 覆盖多条路径（成功 + 失败 + 边界）时拆成多条 Scenario，每条只有一个清晰断言。
- 不可执行——没有数字和判定规则。改成「≤3s（P95）」并给出基线。
- Given 我未登录 / When 我调用上传接口 / Then 返回 401 且不执行上传。
- 契约测试验实现是否符合契约；Mock Server 按契约生成模拟服务；Pydantic 做数据校验。
- ② 契约测试 / ③ 烟雾测试门禁（Day 18 的 Gherkin 可落成自动化验收脚本）。
延伸阅读
- 腾讯云《SDD 规范驱动 + Harness：AI 全栈开发从「能跑」到「可控」》（规范即测试 / 契约测试工具出处）：https://cloud.tencent.com/developer/article/2703349
- CSDN《SDD 和 Harness：AI 编程的两大支柱》（Given-When-Then 场景写法回顾）：https://blog.csdn.net/qq_43284469/article/details/164267908
本工作纸依据《SDD+Harness四周学习计划.md》Day 18 主题编制。整理日期：2026-09-09
