📃 设计文档
在这篇文章中，我们将深入探讨如何撰写一份全面的设计文档。其中包含了详细的介绍，并解释了为什么这样要这样做。
概要
概要的主要作用是让读者能够以最快的速度深入了解设计文档的核心内容。
一份卓越的概要可以迅速让所有人达成共识，明确方向。在设计文档中，概要的主题通常是介绍当前需要解决的问题 ，并阐述其为何值得被关注和解决。
现状与背景
现状与背景往往是打造场景的最好方式。结合当前的业务背景和当前的产品现状相呼应，可以一针见血般直白的说明这样做的重要性。
但是在当前背景的介绍中，往往会出现与当前业务相关的专用名词或某种特性事物的简称。这些词语并不会影响背景的建设，但会成为读者深入场景的绊脚石。所以解释那些专有名词是必要的。
结论
- 简单介绍一下业务的背景与当前的产生的现状是什么样的。
- 描述正在修改的结构并定义专有名词，解释那些名字不显眼的系统的分工是什么。
需求
在此之前的铺垫都是为了营造上下文的场景，现状我们需要简要介绍需求的背景，并对需求进行分类说明。需求的种类也有很多，比如面向用户的需求、技术优化的技改、安全合规相关、或者于此之外的需求性。需求的分类不仅仅是规范化。还是为需求排期奠定基础，毕竟不是每个需求都一定是要快速安排发布的。
种类
- 面向用户的需求。
- 技术需求。
- 安全与合规性需求。
- 其他。
变更的目的
每一个需求都会比以往的产品造成变更，也许有的变更是细微的。但是在细微的变更都会造成一定范围的影响。 所以每一次的变更都是需要慎重考虑的，我们需要分析这次的变更，以确定为什么它值得我们去解决。
在进行考量的同时，我们需要考虑这个问题的重要性等级是什么？影响的范围有多广？变更后会产生什么潜在的好处？以及可能带来的改善有哪些？通过回答这4个问题，我们可以更好的理解这个问题的意义和冬季，并解决它。
关于这项变更带来的收益，我们需要把这些好处与业务需求联系起来。这意味着我们要解释为什么这些好处对业务目标的实现至关重要，以及它们如何与业务战略、客户需求或其他相关因素相契合。
"不要过度承诺"，这是一个提醒，意味着在描述好处时要保持实事求是，不要夸大或过度承诺。过度承诺可能导致失望或不信任，如果最终无法实现所承诺的好处。
结论
- 为什么这个特别的问题值得去解决？
- 描述这项工作将带来的好处，把这些好处与业务需求联系起来（不要过度承诺）。
系统构成图
系统构成图往往是了解业务链路的最直观方式。可以采用图例的方式将主要组件进行关联，展示出它们是如何交互的、每一个流程会发生什么样的变化。
这些组件往往可以是硬件设备、软件模块、人员角色、业务流程等等。图例可以是流程图、系统架构图、数据流程图等等。设计图例的时候需要强调当前正在发生的变化。这些变化可以是新的流程改进、系统升级、业务策略调整等。通过突出变化，可以更容易的理解和关注到关键的转折点。
结论
- 展示主要组件和它们如何互动的图例，突显出正在发生的变化。
潜在的解决方案
这里需要记录下你初步暂定的第一想法，但是这个想还没有被最终定稿。这个想法可能是你当前情况下选择的最合适的，但这个想法需要进一步的去考虑和评估。
当你找到一个解决方式时，并不意味着你可以停止思考。我们还需要更宏观的考虑其他的可行性方案或思路。通过其他的想法，我们可以拓展我们的思维，发现更多的可能性，并给我们更多的选择余地。对不同想法进行比较和权衡。我们需要评估每个想法的优点和缺点，考虑它们在不同方面的影响和效果。
再次需要暂定候补方案。候补方案应该是经过认真考虑和分析的，具有一定的合理性和可行性。同时解释为什么拒绝其他的替代方案。需要说明为什么这些替代方案不适合当前的情况或不能满足特定的需求。
结论
- 暂定的第一个想法，思考其他的想法和它们之间的利弊。
- 描述合理的替代方案，以及你为什么拒绝它们。
建议的解决方案
通过脑爆后，确定下当前决定采用的方案。这里需要比概述更为详尽的深入去介绍更多的细节、步骤、功能、过程和可能实施的某种策略。目的是让读者应能够获得对所提解决方案全面的理解，包括它是如何被选择的、将如何被执行的，以及它预期将带来什么样的效果。
在描述更多细节时候，可以围绕下面的9个主题。
- 详细性： 描述解决方案时，应该提供充分的细节，不仅要阐明解决方案是什么，还要解释为什么选择这个方案以及如何工作的。
- 完整性： 需要确保涵盖解决方案的所有重要方面，包括关键组件、所需资源、涉及的技术等。
- 步骤清晰： 如果解决方案涉及多个步骤或阶段，应该按顺序详细说明每个步骤，并描述其目的和预期结果。
- 功能说明： 对于涉及技术或产品的解决方案，应详细说明其功能特性以及它们如何满足项目需求。
- 过程概述： 提供实施解决方案的具体过程，包括计划、时间表、责任分配和监控机制。
- 策略阐述： 如果有特定的实施策略，如分阶段实施、测试和反馈机制等，也需要详细说明。
- 期望效果： 对于预期的结果和优势，应当给出具体的描述，比如如何提升效率、节约成本或改善服务。
- 风险评估： 可能的风险和挑战应在描述中被识别，并提供应对这些风险的方法或缓解措施。
- 对比其他方案： 可能需要解释为何该方案优于其他备选方案，包括成本效益分析、性能比较等。
结论
- 提供比概述更为详尽和深入的信息。这通常意味着包括更多的细节、步骤、功能、过程和可能的实施策略。
设计与架构
在这里需要用图例或者其他方式直观的展示本次变更的架构模式是如何设计的。当前设计是一种怎么样的调用流程、数据流或者用户界面。
如果变更中使用到其他类库来实现，需要解释这些类库的版本信息并标注说明为什么会选择它们。如果在设计的过程中有考虑使用其他类库来代替，那么请简要说明为什么没有选择它们。你是如何权衡利弊的。
如果公司存在标准化的规定，但是本次变更你并没有严格按照标准化执行。那么需要明确指出所以出的设计架构在哪些方面与公司的标准化有差异，并解释为什么会产生这些差异。
结论
- 利用的关键类库和框架、实施模式、以及任何与公司常见做法不同的地方。
- 应该包括组件的示意图、调用流程和数据流、用户界面、代码、API和模式模拟。
UI/UX变更点
- 如果你的项目改变了用户界面，请创建原型，用原型的方式来预演用户的动作流。
- 如果你的变更没有可视化的组件，这部分可以讨论开发者对于你正在创建的类库的使用体验，或者描述用户使用你的命令行工具的方式。
代码变更点
这里需要描述本次变更的具体实现过程，通常包括代码、算法逻辑、数据结构、数据库的变更等。你可以通过按照时间顺序的步骤描述变更的过程，解释从开始到结束如何实施这些变更的、过程中经历的问题和决策点。
当变更引入了任何新的抽象概念时，应详细描述新概念的功能、目的、如何与现有代码相互作用，以及它是如何解决特定问题或改善系统的。提供这些详细描述的目的是为了确保代码的其他用户、开发者或审查者能够理解变更背后的逻辑，从而更好地维护和扩展代码。
这里给一个提议，不能靠纯文字的方式去描述，必要时使用一些视觉上的手段（比如文本格式、颜色高亮或标记）来区分哪些代码发生了变更，以便于审查和理解。
但变更往往就会产生影响，影响就会暴露出潜在的风险。所以变更点都是需要阐释进行这些代码变更的原因，最好是与上下文关联。例如是为了添加新功能、修复已知缺陷、提高性能、提升用户体验还是保持代码的可维护性。
最终展示变更前后的效果对比，如性能提升的指标、用户体验的改善等。
结论
- 描述你的具体实现的过程。
- 要高亮出现有的代码需要变更的内容、方式和时间。
- 当引入任何新的抽象概念时，也需要描述出来。
API变更点（如涉及则必说明）
当你在现有的API结构上增加新的功能、端点（endpoints）、方法或参数时，这些变动都应该被详细记录下来。不管当前产品是否被其他产品所依赖，变更记录都一定是API更新历史的一部分，为了追踪API的演进以及可能影响到的用户或系统。
这种记录工作对于API的使用者（通常是软件开发者）至关重要，因为他们需要知道：
- 有哪些新功能可以利用；
- 现有的哪些功能发生了变化，以及这些变化如何影响他们当前的代码；
- 如果有API功能被废弃，他们需要知道如何进行替换或升级。
上面都是在讲述记录API变更的意义，现状开始是API变更时我们需要格外注意的。
首先是兼容性。就算你百分百确性当前的更改是不会造成任何风险，你还是需要进行考虑的。这是为了确保API用户不会因为变更而遭受服务中断或功能损失的关键因素。良好的API管理应该避免不必要的不兼容变更，并且在引入这些变更时要有清晰的沟通和足够的过渡期。
其次是错误处理。错误处理是API设计中的一个关键方面，因为良好的错误处理机制可以提高API的可用性、可靠性和易用性。通过记录错误处理的细节。在设计和维护API时，应该考虑全面的错误处理策略，并确保当错误发生时，返回给客户端的错误消息是清晰和有帮助的。同时在遇到问题时，能够得到足够的信息来进行调试和问题解决。此外，这也是文档化最佳实践的一部分，有助于维护API的质量和提供良好的用户体验。
结论
- 记录所有对现有的API的任何新增的API的改变。
- 讨论向前或向后的兼容性与版本问题。
- 记录你的API提案中包含错误处理。
- 当遇到不规则输入、违反约束条件、意外的内部错误或异常时，应该以有用的消息来响应。
持久层变更点（如涉及则必说明）
这不是一个必填项，但是如果本次变更设计到了。那么请一定要进行说明，记录持久层的变更点是非常重要的，因为这些变更可能涉及到重要的数据结构和系统行为。透明的记录和解释这些变更对于团队成员来说是很有帮助的，能够确保每个人都在同一页面上，并理解变更背后的动机和预期的影响。此外，这也是必要的文档实践，有助于维护系统的稳定性和未来的可维护性。
强调需要关注这些关键组成部分的变化，并探讨它们对整个系统的影响。这包括但不限于系统性能、数据一致性、可用性、扩展性和维护的复杂性。变更点的讨论有助于团队成员了解新的设计和实现如何影响系统的数据层，以及这些变化对现有数据操作和业务逻辑的潜在影响。明确记录并讨论这些点是确保数据层平稳过渡和高效运营的重要部分。
记录这些变更点并说明向后兼容性对于确保系统的稳定和预防数据丢失、服务中断至关重要。它也有助于团队成员、利益相关者和用户理解变更的影响，并在必要时做好准备和适当的更新。
结论
- 解释正在引入或已经修改的存储技术。
- 讨论新的数据库、文件和文件系统架构、检索的索引和数据传输管道。
- 包括所有模式的变化并对其向后兼容性进行说明。
日志和埋点
- 明确埋点和日志需要支持的业务目标和技术需求。例如，了解需要追踪哪些用户行为、监控哪些性能指标、满足哪些安全审计要求等。
- 基于目标和需求，确定需要记录的关键事件和指标。对于埋点来说，这可能包括页面访问量、按钮点击次数、用户注册流程的完成率等。对于日志，可能包括错误消息、系统警告、事务处理时间等。
- 阐述如何测试和验证埋点和日志的正确性和完整性。这可能包括自动化测试、手动测试检查点和审计日志的实践。
结论
- 明确埋点和日志需要支持的业务目标和技术需求。
- 基于目标和需求，确定需要记录的关键事件和指标。
- 阐述如何测试和验证埋点和日志的正确性和完整性。
风险评估
风险评估往往是重中之重，一个全面的评估可以将大致的所有风险都暴露在外并妥善解决。
风险评估可以先从微观的角度在慢慢扩延之宏观角度，从一个小的点逐渐将风险范围扩大。最后对本次风险造成的影响进行登记划分并标注其严重程度。
特别需要记录哪些系统、流程或利益相关者将受到影响。评估这些影响是否处于可控且可接受的范围内。
结论
- 全面评估变更的潜在影响，我们从宏观角度出发，综合考虑以下几个方面：
- 对变更造成的影响进行等级划分，以明确其严重程度。
- 界定变更影响的具体范围，包括哪些系统、流程或利益相关者将受到影响。
- 评估这些影响是否处于可控且可接受的范畴内。
- 针对识别的风险，我们将提出相应的规避策略，以确保变更的顺利实施，并最大限度地减少负面后果。
测试计划
在设计测试计划之前，优先明确整体流程的设计理念和变更的关键验证点，然后根据这些信息来制定针对流程链路的验证策略。
需要简要说明，你要如何进行自测？测试用例有哪些？并强调所覆盖的用例以及覆盖率。有没有需要额外关注的风险区域？如何验证变更达到预期的安全标准？
可以围绕着4个问题为主题来编写你的测试计划
结论
- 事先不要定义每项计划，而是去解释你计划如何去验证你的变更。
- 讨论测试数据的来源或生成方法，强调需要覆盖的用例。
- 讨论你期望使用的类库和测试策略**。
- 解释你讲如何验证安全性的需求是否得到满足。
发布计划
制定初步的发布计划，明确系统的直接依赖关系，并按照这些依赖顺序逐步进行发布。
需要表明在进行新版本发布前，需要识别哪些功能将会通过特性开关进行控制。要有明确的文档化过程，列出所有的特性开关，以及它们各自控制的功能和相关的配置信息。
还需说明如何逐步向用户推出新功能，先从一个小用户群体开始，逐渐扩大范围，以便于监测和评估新版本的表现。
这里涉及到的内容颇多，就不再这里详细介绍
发布成功并不是变更完成的最后一环，需要验证变更的有效性。描述在发布后如何验证需求变更的有效性，并阐明可用于监测日志异常的方法。
并且请描述当异常出现时，你会如何对其进行优先级分类？如何执行事先制定的应急措施以控制状况？以确保影响最小化。
如果公司内有一套标准的发布流程，请遵守它。
结论 描述你进行采用的策略，以避免复杂的部署顺序需求。 记录你需要设置特性开关，以控制新版本的展开。 你的发布的变更是否生效？以及在发现问题时你将如何回滚。
遗留的问题
需要清晰地指出那些在目前的设计阶段还未解决的关键问题。这些遗留问题通常是紧急的，需要尽快解决，因为它们可能对项目的进展、质量或最终交付有显著影响。
遗留问题的说明是必要的。有助于保证团队成员对于现存的挑战有共同的理解，同时为项目的接下来的步骤提供一个清晰的行动指南。此外，这也能够帮助避免在项目后期出现意外的阻碍，确保所有关键风险都被妥善管理。
能够识别并记录"已知的未知"是非常重要的。这有助于团队评估潜在的风险，制定应对计划，分配资源去探索这些问题的答案，并确保在项目进展中对这些问题保持关注。通过这样的处理，团队可以更加明智地做出决策，并提高项目成功的可能性。
结论
- 明确地列出设计中尚未回答的紧迫问题。
- 并说明你的"已知的未知"。
项目总结/复盘（可选）
围绕本次需求的总结内容皆可。一方面可以通过总结的方式弥补提升自己，二来可以留痕为读者更方面理解全文的内容和方向。
结论
- 项目开发或上线后，对整个流程进行的总结、复盘。
附录
- 加入额外的令人感兴趣的细节
- 添加相关工作参考
提供研究线索不仅有助于引导读者，也是对自己研究过程的有效回顾。
感谢（题外话）🌸
本节内容参考了 《程序的README》 -- 10.3 撰写设计文档。