hello-sdd：从零掌握规格驱动开发的实战教程
> hello-sdd 是一个从零开始系统讲解 SDD（Spec-Driven Development，规格驱动开发）的中文实战教程项目，由知名开发者 mouredev 维护，用 Python 示例贯穿全流程。
## 为什么需要 SDD？—— 先看传统开发的痛点
在传统开发流程中，我们习惯先写代码，再补测试，最后写文档。但这种方式有几个根深蒂固的问题：
1. **需求与代码脱节**：产品经理写一份需求文档，开发照着理解写代码，测试照着需求写用例，三方对同一需求的理解经常出现偏差，最后上线时才发现功能与预期不符。
2. **测试滞后**：很多项目测试是在功能开发完成后才补写，导致测试覆盖不全，或者为了赶进度直接跳过测试。
3. **文档过时**：代码迭代频繁，但文档往往停留在初始版本，新同事接手时只能靠读代码猜逻辑，维护成本极高。
4. **沟通成本高**：前后端联调时，接口定义反复修改，每次都要口头沟通，容易遗漏。
**SDD 的核心思想**是：在写任何实现代码之前，先把需求转化为可执行的规格（Specification）。这个规格既是测试用例，也是文档，更是开发的唯一依据。代码只是规格的“实现细节”。
## hello-sdd 是什么？
hello-sdd 是 mouredev 发起的一个免费课程，定位是“从零开始学 SDD”。它不是一个库或框架，而是一套完整的教学代码库 + 文档，包含：
- 一系列按章节组织的 Python 示例代码
- 每个示例都遵循 SDD 流程：先写规格（测试），再实现
- 配套的说明文档（Markdown），讲解每一步的思考过程
- 使用 pytest 作为测试框架，展示规格如何驱动实现
项目地址：https://github.com/mouredev/hello-sdd
## 快速上手：安装与第一个 SDD 示例
### 环境准备
需要 Python 3.8+，推荐使用虚拟环境：
bash
# 克隆项目
git clone https://github.com/mouredev/hello-sdd.git
cd hello-sdd
# 创建虚拟环境（可选但推荐）
python -m venv venv
source venv/bin/activate # Linux/macOS
# 或 venv\Scripts\activate # Windows
# 安装依赖（主要是 pytest）
pip install -r requirements.txt
### 第一个 SDD 示例：计算器
项目中有个典型的示例，展示如何用 SDD 写一个计算器。传统做法是先写 `calculator.py`，但 SDD 要求**先写测试**。
**步骤 1：写规格（测试文件）**
python
# test_calculator.py
import pytest
from calculator import add, subtract
def test_add_positive_numbers():
assert add(2, 3) == 5
def test_add_negative_numbers():
assert add(-1, -2) == -3
def test_subtract_basic():
assert subtract(10, 4) == 6
def test_subtract_negative_result():
assert subtract(3, 10) == -7
**步骤 2：运行测试，看到失败**
bash
pytest test_calculator.py
# 输出：ModuleNotFoundError: No module named 'calculator'
这正是 SDD 的关键：**先让测试失败**，因为还没有实现。失败本身就是规格的一部分——它明确告诉我们“现在缺什么”。
**步骤 3：实现最小代码让测试通过**
python
# calculator.py
def add(a, b):
return a + b
def subtract(a, b):
return a - b
**步骤 4：再次运行测试，全部通过**
bash
pytest test_calculator.py
# 输出：4 passed
看起来很简单？但这就是 SDD 的最小闭环。项目里更复杂的示例（如用户管理、API 模拟）会展示如何处理边界条件、异常、依赖注入等，但核心流程始终一致：**规格先行，实现跟进，测试驱动**。
## 核心亮点深度解析
### 1. 规格即文档，文档即真相
在 hello-sdd 中，每个功能模块的测试文件就是最权威的文档。新成员加入时，不需要阅读冗长的设计文档，直接看测试用例就能理解功能的行为边界。这解决了传统文档“写时过期”的问题。
### 2. 天然的回归保护
因为规格（测试）先于代码存在，每次修改代码后运行测试，就能立刻知道是否破坏了原有功能。这比事后补测试要可靠得多——因为事后补测试时，开发者往往会根据实现来“将就”测试，导致测试形同虚设。
### 3. 促进接口设计思考
写规格的过程，本质上是在思考“这个函数应该接受什么输入，返回什么输出，有哪些边界情况”。这强制开发者在写代码前先理清接口契约，避免“边写边想”导致的接口混乱。
### 4. 与 TDD 的关系
很多人问 SDD 和 TDD（测试驱动开发）有什么区别。hello-sdd 项目明确给出了解释：
- **TDD** 更关注“测试先行”，重心在测试代码本身，通常从单元测试开始。
- **SDD** 是更上层的概念，它强调“规格先行”，规格不一定是测试代码，可以是行为描述、契约、甚至是伪代码。测试只是规格的一种体现形式。
在 hello-sdd 中，SDD 的实践方式是用 pytest 作为规格载体，但 SDD 也可以用于设计 API 契约、数据库 schema 等非代码场景。
### 5. 完整的实战项目结构
项目不是零散示例，而是按真实项目的结构组织：
hello-sdd/
├── docs/ # 理论讲解，每个章节对应一个主题
├── examples/ # 按难度递增的示例代码
│ ├── 01_basics/ # 最基础的 SDD 演示
│ ├── 02_intermediate/ # 涉及异常、依赖
│ └── 03_advanced/ # 模拟真实业务场景
├── tests/ # 所有测试的汇总
└── requirements.txt
这种结构让学习者可以循序渐进，从“什么是规格”到“如何在大型项目中应用 SDD”。
## 适用场景
hello-sdd 最适合以下人群和场景：
- **Python 开发者**：想系统学习 SDD 方法论，但苦于没有好的中文教程。
- **测试工程师**：想理解“测试先行”的底层逻辑，提升测试设计能力。
- **团队技术负责人**：想在团队内推行规格驱动开发，需要一套可复制的培训材料。
- **个人项目维护者**：想提高自己项目的可维护性，减少回归 bug。
- **教学场景**：高校或培训机构教授软件工程实践时，可作为 SDD 的教学案例。
不适用场景：
- 如果你只关心性能优化或算法实现，SDD 的帮助有限。
- 如果团队完全没有测试习惯，直接引入 SDD 会阻力较大，建议先从 TDD 过渡。
## 与其他同类项目对比
| 对比项 | hello-sdd | Test-Driven Development with Python (书) | pytest 官方文档 |
|--------|-----------|----------------------------------------|----------------|
| 侧重点 | SDD 方法论 + Python 实战 | TDD 实践 + Django Web 开发 | 测试框架用法 |
| 语言 | 中文 | 英文 | 英文 |
| 适合人群 | 零基础到中级 | 中级以上 | 有基础即可 |
| 代码风格 | 简洁、教学导向 | 真实项目导向 | 参考手册 |
| 是否免费 | 完全免费 | 付费书籍 | 免费 |
| 覆盖范围 | SDD 全流程 + 原理 + 示例 | 偏重 TDD 在 Web 开发中的运用 | 仅测试框架本身 |
相比其他资源，hello-sdd 的最大优势是：**它把 SDD 从理论讲到了实践，而且全程中文，示例代码量适中，不会让初学者感到淹没在大量代码中**。
另外，与一些只讲“测试先行”的教程不同，hello-sdd 强调规格的多种形式。比如在高级示例中，它展示了如何先用文字描述规格，再转化为测试代码，最后实现——这更接近真实工作中的流程。
## 项目维护与社区
mouredev 是西班牙开发者社区中非常活跃的人物，他的项目以高质量和高更新频率著称。hello-sdd 目前有 296 个 star，虽然不算多，但内容质量很高，每个 commit 都有清晰的说明。项目采用 MIT 协议，可以自由使用和修改。
值得注意的是，项目的文档和代码注释都是中文，这对中文开发者非常友好。虽然作者是西班牙人，但项目的中文本地化做得很好，这在开源项目中比较少见。
## 我的使用体验
我花了一个周末把整个项目过了一遍。最直观的感受是：**它不像一个教程，更像一个思维训练营**。每个示例都强迫你先思考“规格是什么”，而不是急着写代码。这种思维转换对习惯了“先写代码再补测试”的人来说，确实需要一点适应时间，但一旦养成习惯，代码质量会有明显提升。
有几个细节让我印象深刻：
1. **失败测试的刻意展示**：项目特意保留了一些“失败状态”的测试，让你看到规格先行时，测试失败是正常的、预期的，而不是错误。
2. **边界条件的处理**：在高级示例中，它展示了如何用 pytest 的 `parametrize` 来覆盖大量边界条件，这比手写多个断言要优雅得多。
3. **规格的演化**：项目展示了当需求变化时，如何修改规格（测试），再修改实现。这模拟了真实开发中的迭代过程。
## 总结与建议
hello-sdd 是一个值得花时间学习的项目，尤其适合以下情况：
- 你写 Python 但从未认真写过测试。
- 你写过测试但总是“事后补”，想改变工作流。
- 你想向团队推广规格驱动开发，但需要一个可落地的参考。
- 你想理解“规格”和“测试”的本质区别，以及它们如何协作。
建议学习路径：先阅读 `docs/` 下的理论部分，然后按顺序跑通 `examples/` 中的代码，最后尝试用 SDD 方法重写一个自己以前的项目（比如一个简单的 CLI 工具），这样体会最深。
**项目链接**：https://github.com/mouredev/hello-sdd