每次都开发正确的东西并成为 10x 工程师🏆：编写 RFC 的艺术🥋

想象一下，你被委派在正在开发的产品中实现一项至关重要的新功能。这就是你期盼已久的机会——每个人都会见证你是一位多么出色的10倍速开发者！你打开一份你一直想尝试的最酷的新库和设计模式的清单，然后立即投入其中，完全进入“地下室”模式。一周后，你胜利出击，提交了完美的拉取请求！

但是，团队中的高级开发人员立即拒绝了它—— “太复杂了，你应该简单地使用库 X 并重用 Y。”什么！？显然，他们不明白你的解决方案有多么天才，很快，你就会看到你的 PR 上有 100 条评论，接下来就是几天的重构。

如果在实现所有功能之前，能有一种方法可以提前了解 X 和 Y 就好了。嗯，现在就有了，它就是 RFC！

我们将通过RFC 中关于在 Wasp 中实现身份验证的示例来学习它。Wasp是一个基于 React、Node.js 和 Prisma 构建的全栈框架，它提供了大量开箱即用的功能，是构建和部署应用程序的最快方法。它还附带一个免费的 GPT 驱动的代码库生成器MAGE，该生成器已被用于创建超过 30,000 个应用程序。

让我们开始吧！

支持我们！🙏⭐️

如果您觉得这篇文章有帮助，不妨在 Github 上给我们点个星！Wasp 的所有开源项目都是开源的，您的支持能帮助我们简化 Web 开发，并激励我们撰写更多类似的文章。

⭐️感谢您的支持🙏

那么，什么是 RFC？

RFC 是“征求意见稿”的缩写，简单来说就是“一份提议修改代码库以解决特定问题的文档”。其主要目的是在实施之前找到解决问题的最佳方法。RFC最初由开源社区采用，但如今，几乎所有类型的开发者组织都在使用它们。

您可能在行业中遇到过此类文档的其他名称，例如 TDD（技术设计文档）或 SDD（软件设计文档）。有些人会争论它们之间的区别，但我们不会。

有趣的是：RFC 是由 IETF（互联网工程任务组）发明的，该工程组织正是我们今天使用的一些最重要的互联网标准和协议背后的推动者！这还不算太糟，对吧？

我什么时候应该写 RFC，什么时候可以跳过它？

那么，为什么要费心去写最终要写的代码呢？与其省时间，直接写代码呢？如果你正在处理一个 bug 或一个相对简单的功能，并且你很清楚要做什么，而且不会影响项目结构，那么就不需要 RFC 了——直接打开 IDE 开始吧！

但是，如果您要引入一个全新的概念（例如，引入基于角色的权限系统）或改变项目的架构（例如，添加对运行后台作业的支持），那么您可能需要在输入git checkout -b my-new-feature并进入那个甜蜜的编码区域之前退后一步。

综上所述，有时很难确定是否应该编写 RFC。也许这是一个更突出的功能，但你之前做过类似的事情，并且已经在脑海中规划好了一切，几乎没有任何疑问。为了解决这个问题，我喜欢使用一个简单的启发式方法：是否有多个显而易见的方法来实现这个功能？是否有新的库/服务可供选择？如果这两个问题的答案都是“否”，那么你可能不需要 RFC。否则，就需要进行讨论，而 RFC 就是实现 RFC 的方法。

这对我有什么好处？

我们已经确定了如何决定何时编写 RFC，但以下也是您应该这样做的原因：

• 你会理清思路，思路清晰。如果你决定写一份 RFC，那就意味着你正在处理一个非同寻常的、开放式的问题。把事情写下来有助于提炼你的想法，并客观地看待它们。
• 相比直接开始编程，你学到的东西会更多。你将有空间去探索不同的方法，并且常常会发现一些你最初从未想过的东西。
• 你将众包团队的知识。通过向团队征求反馈（即征求意见），你将全面了解正在解决的问题，并填补任何剩余的空白。
• 您将提升团队对代码库的理解。通过协作完成 RFC，团队中的每个人都能理解您正在做什么以及最终是如何完成的。这意味着下次有人需要接触这部分代码时，他们只需问您更少的问题（=== 更长时间的不间断编码！）。
• PR 审核会更加顺利。还记得本文开头提到的那个情况吗？你的 PR 被拒是因为“太复杂”吗？那是因为审核者没有了解具体情况，而且你之前没有得到团队其他成员的认可就做了一个相当大的改动。如果先写 RFC，你就不会再遇到这种情况了。
• 您的文档已经完成了 50%！需要明确的是，RFC 并非最终文档，您不能直接引用它，但您可以重复使用其中的许多内容，例如图片、图表、段落等等。

哇，这听起来太棒了，我现在就想写一个新功能，好让它写个 RFC！玩笑归玩笑，先把 RFC 看完会让编码过程轻松很多——你清楚地知道自己要做什么，而且不用再质疑自己的方法，也不用担心创建 PR 后大家会怎么看。

好的，好的，我同意了！那么，我该怎么写呢？

很高兴你问到这个问题！现在有很多不同的格式，或多或少有些正式，但我更喜欢简洁明了。我们在 Wasp 编写的 RFC 并不遵循严格的格式，但有一些通用的部分：

• 元数据——标题、日期、评论者等……
• 问题/目标——你要解决什么问题
• 建议的解决方案（或更多）
• 实施概述
• 备注/未解决的问题

基本就是这样了！每个部分都可以进一步细分和完善，但这是一个你可以开始的基本框架。

现在让我们逐一介绍这些内容，并在 Wasp 中的身份验证示例中看看它们在实践中是什么样子的。

元数据 ⌗

这个非常不言自明 - 您可能想要跟踪有关 RFC 的一些基本信息 - 状态、创建日期等。

一些模板还明确列出了审阅者及其对 RFC 的“批准”状态 - 我们没有它，因为我们是一个小团队，沟通很快，但它对于不是每个人都认识每个人的大型团队来说很方便，并且您希望有更多的流程（例如，在指导初级开发人员时）。

问题🤔

事情开始变得有趣了。你对问题、目标/功能以及实现原因的定义越清晰，后续步骤就越容易。所以，在开始撰写 RFC 之前，这一点就值得投入——务必与所有相关方（例如产品负责人、其他开发者，甚至用户）沟通，以加深你对即将解决的问题的理解。

通过这样做，您也很可能获得有关可能的解决方案的第一个提示和指示，并对您所处的问题空间有一个大致的了解。

以下是上述示例中的一些提示：

• 从高层次的总结开始- 这样，读者可以快速决定这是否与他们相关以及是否应该继续阅读。
• 提供一些背景信息- 解释一下当前的世界状况。这可以是一句话，也可以是一整章，具体取决于目标受众。
• 清楚地陈述问题/目标——解释为什么存在问题并将其与用户/公司的痛点联系起来，以便动机明确。
• 如果可能的话，提供额外的细节——图表、代码示例等等。任何能帮助读者更快找到灵感的内容都可以。使用可折叠的章节可以加分，这样 RFC 的核心部分就能保持易于理解的长度。

如果你做到了以上所有，那么你已经离完美 RFC 的目标不远了！既然明确定义问题至关重要，那就大胆地添加更多内容，并进一步细分问题。

非目标🛑

这是“问题”的子部分，有时非常有价值。写下我们不想或不会在本次代码库变更中做的事情，可以帮助设定预期并更好地定义变更范围。

例如，如果我们正在为应用添加基于角色的身份验证系统，人们可能会认为我们还会为其构建某种管理面板来管理用户和添加/删除角色。通过明确说明不会这样做（并简要解释原因——不需要、耗时太长等等），审阅者将更好地理解你的目标，你也能省去不必要的讨论。

解决方案与实施🛠️

一旦我们知道了想要做什么，就必须找到最佳方案！你可能已经在“问题”部分暗示了可能的解决方案，但现在是时候深入研究了——研究不同的方法，评估它们的优缺点，并勾勒出如何将它们融入现有系统。

这部分可能是所有部分中最自由的——因为它高度依赖于你正在做的事情的性质，所以在这里施加太多限制是没有意义的。你可能想停留在更高的层次，例如系统架构，或者你可能需要深入研究代码并开始编写你需要的部分代码。因此，我没有一个确切的格式供你遵循，而是提供一组指导原则：

编写伪代码

RFC 的目的是传达思想和原则，而不是编写能够编译并涵盖所有边缘情况的生产级代码。您可以自由地构思/想象/编写任何您需要的功能（例如，假设您已经有一个发送电子邮件的函数，即使您没有实现，也可以直接使用它），并且不要用实现细节来束缚您自己或读者（除非 RFC 正是为此而设计的）。

最好从较高的层次开始，然后当您意识到需要它或其中一位审阅者建议它时再进行更深入的了解。

了解其他人是如何做的

根据您开发的产品类型，找到答案的方法可能有所不同，但几乎总有办法。如果您正在开发像Wasp这样的开源工具，您可以参考其他流行的解决方案（它们也是开源的），并学习它们是如何实现的。如果您正在开发 SaaS 产品，并且需要确定应该使用 Cookie 还是 JWT 进行身份验证，您可能有一些朋友之前做过类似的，可以咨询他们。最后，只需使用 Google/GPT 即可。

为什么这如此有用？因为它能让你（以及审阅者）对你的解决方案更有信心。如果其他人以这种方式成功了，这可能是一个很有前景的方向。它也可能帮助你发现以前从未想过的方法，或者作为你构建的基础。当然，永远不要想当然，要考虑到你具体情况的具体需求，但一定要利用他人的知识和专业知识。

把事情留着未完成，让它保持脏乱

RFC 的重点在于“C”部分，也就是协作（是的，我知道它实际上代表“注释”）。它不是一场要求你获得满分且不被提问的考试——如果出现这种情况，你可能一开始就不应该写这份 RFC。

解决问题需要团队合作，而你只是第一个尝试并推动事情进展的人。你的任务是尽可能多地打好基础（细化问题，探索多种解决方法，识别新发现的子问题），以便评审人员能够快速掌握进度并提供有效的反馈，并将其引导到最需要的地方。

RFC 的主要作用是找出最重要的问题并引导审阅者的注意力，而不是解决这些问题。

您所编写的 RFC 应该被视为一个讨论区和一项正在进行的工作，而不是一件必须在观众面前展示之前完善的艺术品。

备注和未解决的问题🎯

在文档的最后一部分，你可以总结主要思想，并突出最重要的未解决的问题。在阅读完所有内容后，这有助于提醒读者哪些方面最值得关注。

现在我知道何时以及如何编写 RFC 了！您有什么模板可以作为我的起点吗？

当然！如前所述，我们的格式非常简洁，但您可以参考我们用作示例的 RFC来获取灵感。您的公司也可能已经拥有他们推荐的现成模板。

您可以使用和/或调整以下几个以满足您的需要：

• Squarespace RFC 模板
• 您有推荐的模板吗？我很乐意在这里列出！

我应该用什么工具来写 RFC？选择太多了！

你使用的具体工具可能是 RFC 编写过程中最不重要的部分，但它仍然很重要，因为它决定了相关的工作流程。如果你的公司已经选择了工具，那么当然要坚持使用那个。如果没有，以下是我遇到的最常见的选择，以及一些简短的评论：

• Google Docs - 经典之选。超级方便地在文档的任何部分发表评论，这是最重要的功能。
• Notion - 也非常适合协作，另外还提供了一些 markdown 组件，例如可折叠组件和表格，可以使您的 RFC 更具可读性。
• Github 问题/PR - 有时会使用，尤其是在开源软件 (OSS) 项目中。缺点是很难针对文档的特定部分进行评论（只能针对整行进行评论），而且插入图表也相当繁琐。优点是所有内容（代码和 RFC）都保留在同一平台上。

我们目前使用 Notion，但以上任何一个都是不错的选择。

概括

正如在 RFC 末尾添加摘要是最佳实践一样，我们也会在这里这样做！这篇文章比我预期的要长，但有很多内容需要提及——希望你会觉得它有用！

最后，能够清晰地表达你的想法，阐明问题，并客观地分析可能的解决方案，并得到团队的反馈，这将有助于你开发出正确的东西，这是最终的生产力技巧。

这就是你成为一名真正的 10x 工程师的方法。感谢阅读，下次再见！