RealWorld 实现提交规范详解：MVP 级架构底线、最低测试要求与完整验收清单

本文围绕 RealWorld 官方的《Expectations》规范文档展开，系统讲解向该仓库提交新框架实现时必须满足的三条核心准则：保持"简单但健壮"的 MVP 级架构（10 分钟可理解原则）、以最少一个单元测试为底线的测试策略，以及功能实现、仓库组织、README 与框架星标门槛等硬性验收项。读完本文，你能对照官方标准评估一份实现是否合格，并知道如何用官方 API 测试套件（Hurl/Bruno）与共享 E2E 用例来自检。

简单但健壮：10 分钟可理解原则

规范文档 expectations.md 开宗明义：

Remember: Keep your codebases simple, yet robust.

具体判定标准是：如果一个全新接触该框架的开发者无法在 10 分钟之内理解实现的高层架构，说明工程上"用力过猛"了。这条标准直接约束了目录组织、分层数量和依赖引入的复杂度——RealWorld 的各参考实现应当让新成员快速建立全局认知。

但"简单"有一条不可逾越的边界：

你绝不能为了追求简单而放弃基本最佳实践，否则等于在教新手开发者"错误"的做法。

两条约束合起来沉淀为对整体质量的定位——早期创业公司 MVP 的样子：功能完整且稳定（functionally complete & stable），但绝不过度工程化（not unnecessarily over-engineered）。这既是给实现作者的写作指南，也是给评审者的验收标尺。

测试要求：最低一个单元测试，鼓励但不强制全覆盖

TL;DR

规范的测试要求一句话概括：每个仓库至少提交一个单元测试（minimum of one unit test）是硬性要求；如果维护者有意愿、或社区成员愿意通过 Pull Request 补全，官方"肯定希望"所有实现都具备优秀的测试覆盖。

官方文档 tests.md 对该条做了呼应式表述：

Include at least one unit test in your repo to demonstrate how testing works (full testing coverage is not required!).

即：一个单元测试的作用是示范该框架下测试怎么写，而不追求覆盖率数字。

为什么测试没有进入规范主体

这一条背后有一段明确的取舍逻辑，值得所有做"规范 vs 最佳实践"决策的团队参考：

1. 成本考量：为每个 Conduit 实现构建完整测试覆盖本身就是一个巨大的时间投入。规范最初刻意不把它列为强制项，而是定位为愿意做的仓库的"extra credit"（加分项）。文档中举了真实案例：Angular 2 仓库当时没有完整测试，是若干社区成员在 issue 诉求后以 PR 形式补上的——这正是规范期望的社区协作路径。
2. Golden Rule 的一致性：强制全量测试与上面"MVP 级质量"的定位存在张力。规范作者观察到，多数做面向消费者应用（如 Conduit 这类内容站）的初创公司，在产品-市场契合（PMF）稳固之前不会全面推行 TDD/测试，因为大部分时间应花在产品与 UI 的快速迭代上。
3. 辩证补充：规范同时明确——TDD/测试并不等于过度工程，只是在特定场景下（找 PMF 的消费型产品、副项目、需要快速验证的原型）该等式恰好成立。因此官方的最终立场是"倾向于希望每个仓库都包含能体现 TDD 优秀实践的测试"。

对实现作者的实操含义

• 单元测试是提交门槛：哪怕只写一个，也要写成能示范框架测试惯例的样子（测试框架选择、断言风格、mock 方式）；
• 全量测试是社区协作路径：可以先以最小测试交付，在 README 或 issue 中开放"欢迎补测试 PR"的口子，参考 Angular 2 仓库的社区模式；
• RealWorld 官方仓库本身示范了另一层测试：后端用 Hurl/Bruno 契约测试（见下文），前端用 Playwright 共享 E2E 套件（specs/e2e/），二者都是对"参考实现如何验证"的活教材。

其他硬性 Expectations 清单

除架构与测试两条原则外，规范列出了五条可直接逐条勾选的验收项：

要求	说明	对照依据
全部必需功能实现	所有规范要求的功能必须落地	功能清单见 features.md
独立 GitHub 仓库 + 开放 Issues	实现须发布在专属仓库，且 Issues 区块保持开启以便社区反馈	CONTRIBUTING.md 亦要求用 Discussions 协作、issue 报 bug
README 提供总览 + 本地运行说明	必须介绍实现概览并说明如何在本地跑起来	—
所用库/框架 GitHub Stars ≥ 300	确保所选框架具备足够的社区成熟度	—
尽力保持实现更新	跟随框架版本演进，避免长期腐烂的实现	—

其中"全部必需功能"指向 features.md 中的通用功能清单，实现作者需完整覆盖：

• 通过 JWT 认证用户（登录/注册页 + 设置页登出按钮）
• 用户的 Create/Read/Update（注册与设置页；无需删除用户）
• 文章的完整 CRUD
• 文章评论的 Create/Read/Delete（无需更新评论）
• 分页展示文章列表
• 收藏文章
• 关注其他用户

注意这些"CRU-/CR-D"式的刻意裁剪：它们就是 MVP 定位在功能层面的体现——不做删除用户、不做编辑评论，把实现成本压在核心路径上。

用官方测试套件验证 Expectations：测试即事实源

"功能完整"不能靠自述，RealWorld 提供两套官方测试作为客观验证手段。

后端：Hurl 契约测试（事实源）

specs/api/ 下的 Hurl 集合与 OpenAPI 规范 是后端契约的权威定义。官方后端规范文档 introduction.md 特别强调：

这些文档页面用文字概括契约，但 OpenAPI spec 与 Hurl 测试套件才真正定义它。当文字与测试不一致时，测试说了算——请针对测试构建，发现偏差请开 issue。

本地对后端跑测试只需一行（见 specs/api/README.md）：

HOST=http://localhost:3000/api ./run-api-tests-hurl.sh

后端：Bruno 集合（由 Hurl 生成，保持同步）

Bruno 集合不是手写的，而是由 Hurl 套件自动生成，并通过 CI 检查一致性。仓库根目录 Makefile 提供了对应目标：

# 从 Hurl 重新生成 Bruno 集合
make bruno-generate   # 实际执行: bun specs/api/hurl-to-bruno.js

# CI 一致性检查
make bruno-check      # 实际执行: bun specs/api/hurl-to-bruno.js --check

specs/api/bruno/ 中的请求按 auth、articles、comments、feed、pagination、errors-* 等目录组织，可直接在 Bruno 客户端中交互式执行，也支持脚本化运行：HOST=http://localhost:3000/api ./run-api-tests-bruno.sh。

前端：共享 Playwright E2E 套件

前端实现的验收由官方共享 E2E 套件 specs/e2e/ 承担，覆盖健康检查（specs/e2e/health.spec.ts 中验证导航栏可见、登录/注册表单渲染）、文章流、认证、评论、错误处理、XSS 安全等场景，选择器约定集中在 specs/e2e/SELECTORS.md。实现作者只需在本地跑通这套用例，即可证明前端行为与规范一致。

提交前自检清单

综合规范文档与仓库配套测试，一份合格的新实现提交前可逐项核对：

1. 架构：新开发者 10 分钟内能讲清高层架构；无过度工程化，但未牺牲基本最佳实践；
2. 功能：features.md 清单全覆盖，且通过 Hurl/Bruno API 测试（后端）或 Playwright 共享 E2E 套件（前端）；
3. 测试：仓库内至少有一个示范性的单元测试；
4. 仓库：独立 GitHub 仓库、Issues 已开启、README 含实现总览与本地运行步骤；
5. 选型：所用框架 GitHub Stars ≥ 300；
6. 维护：愿意跟随框架版本持续更新实现。

这套规范的价值在于把"什么是合格的框架示例应用"从主观感受变成了可验证的清单：架构复杂度有人类时间成本做标尺，功能完整性有机器测试做裁判，测试投入则有明确的最低线而非覆盖率军备竞赛。对照它，你可以快速判断自己（或他人）的实现离提交还差哪几步。