《高效软件设计文档编写 – CodesCode》
在本文中，我将谈论我通常遵循的充分理解问题并成功提供解决方案的典型流程
软件设计在软件工程师的生活中起着至关重要的作用。它始于问题陈述，并为实施解决方案铺平了道路。在这篇文章中，我将谈论我通常遵循的一个全面理解问题并成功交付解决方案的典型流程。
问题陈述
定义问题陈述是开发过程中的第一个关键阶段。这些问题陈述来自产品、领导或其他工程师。一个明确定义的问题能够清楚地描述系统应该如何看起来。但通常情况下，无论问题陈述如何定义，都会存在许多模棱两可和未知之处。为了克服这些问题，我们继续进行需求收集。
需求收集
一旦问题陈述被定义，例如：开发一个聊天应用程序，开发一个微博网站等。下一步是解码问题，概述需求，标明未知和依赖关系，并解释假设。让我解释一下每个部分：
1. 解码问题陈述：简单的问题陈述是对利益相关者最终目标的高层次解释。这通常是一个非常抽象的陈述。为了设计一个高效的系统，我们首先需要通过提出各种澄清性的问题来理解问题陈述，比如“用户是谁”，“需要哪些功能”，“存在哪些限制”等。这将提供对要求的良好理解。
2. 概述需求：在实施之前进行文档记录和签署总是更好。一旦问题陈述清楚，可以将需求分解为功能和非功能的，根据时间表、复杂性等优先级划分为P0、P1、P2等。这将作为需要在何时以及何时交付的蓝图。
3. 标明未知和依赖关系：一旦需求确定，我们就能够概述依赖关系并确定未知。对于大小不同的系统，通常存在对现有应用程序或新应用程序的某些依赖关系。这些依赖关系可能来自同一团队或跨团队/组织，如果不及时解决可能会构成风险。在设计文档中对这些进行概述，并着重指出以让利益相关者了解风险并优先解决这些问题。
4. 假设：没有完美的系统，我们需要做出一定的假设，这些假设可能是由于技术限制、依赖限制、未知因素或对某个现有服务的某种行为的假设等。记录下这些假设将在开发阶段和交付阶段帮助您。
背信计算
背信计算对于设计您的系统非常重要。它帮助您了解您的客户，并基于选择基础设施、存储、可扩展性 等需求做出决策。这将包括了解流量模式、数据量、数据类型、存储需求等，进而帮助您选择系统的各种组件。
任务拆分
一旦需求明确，我们可以将这些需求拆分为各种任务、里程碑或交付物。这将为读者/利益相关者提供关于应用程序组件交付的时间表的清晰想法。这也将帮助我们跟踪进度，并重新调整优先级。一旦交付物被拆分，就更容易创建故事/任务并将其分配给多个开发人员并行进行。
高层设计
非常关键且重要的一步：系统设计。高层设计是您的应用程序的蓝图，也是开发人员的参考指南。一旦需求明确，它给我们带来对系统的深入了解。根据需求，我们确定了设计系统所需的各种组件。高层设计由这些组件和它们之间的相互作用组成。它概述了各种参与者、基础设施以及它们之间的相互作用。为了提供更好的可见性，您还可以提供图例、编号和标记这些相互作用。通常情况下，不仅有一个而且有许多不同的现有和新的组件/服务相互作用在一起。最好使用颜色代码或分隔来将相关组件分组在一起。这为读者提供了对组件之间的相互作用及其边界的清晰理解。
低层设计
高级设计应遵循低级设计（基于复杂性而选择性）。高级设计以非常高的层次显示组件和相互作用，而低级设计详细解释了每个组件。这使得每个单独组件的可见性变得清晰，并成为开发人员在这些组件上工作的北极星。您可以在此部分中包含诸如类图、交互、层次结构等详细信息。
流程图
每个软件应用都是一组命令和执行步骤，用于实现所需的任务。每次执行都会导致各个组件之间的一定数据流动，这决定了应用程序的行为方式。例如，调用 API，然后使用该结果来得出某些决策，然后调用API b. 或者, API a 被调用后，在做出任何业务决策之前，请验证身份验证和授权。这些可以在流程图中更好地进行可视化。这将提供数据、控制、动作等流动的可视化。
备选方案
完成以上步骤后，您将拥有一个非常完善的设计文档。迄今为止的文档将提供足够的信息来得出任务、结果和实现这些任务的路径。但是，通常一个解决方案并不适用于所有情况，为了达到最佳解决方案，必须考虑各种不同的方法。将所有这些备选方案及其优缺点都记录下来是一种良好的做法。最后，您可以用高层次的解释总结您选择以上设计的原因。这将使读者清楚地了解您的设计选择和技术深度。
数据模式
一旦完成了高级设计和低级设计，您将对各个组件有清晰的理解。这些组件将托管您的应用程序、存储数据、调用下游或执行一些业务逻辑。在这个部分，您可以描述设计中使用的所有数据模式和关系。这将帮助开发人员以清晰的方式实现这些模式，并帮助读者理解。
API 结构
如果系统需要 API，则这是概述每个 API 的最佳位置。您可以为每个 API 编写端点详细信息、路径详细信息、方法类型、身份验证、授权、请求和响应结构。
运行成本
这是系统设计的另一个重要方面。在这个部分，您可以概述您的设计选择以及预计流量的运行成本。这将使读者更好地了解您系统的运行成本，以及可以进行的任何未来优化以减少成本。
安全
除非发生某些事故，否则不需要安全性。因此，在设计中考虑安全方面总是更好的选择，如身份验证、授权、数据存储、存储加密、REST 加密、密码删除、访问策略、数据分类等。如果发生故障会发生什么？如果密钥被泄露会发生什么？如何确保数据的安全存储？等等。
用户体验
如果设计需要用户体验，请添加一个带有模型、线框等的部分。
测试细节
您可以撰写流程的高层次细节。根据设计的不同，这可以是一个单独的文档，用来概述每个流程的测试。
运营卓越
运营卓越在健康应用程序中起着非常重要和关键的作用。这是一个精心设计和开发的应用程序的一个非常重要的支柱。您可以使用此部分来概述部署、维护、警报、仪表板等，以确保应用程序的健康。
故障条件
最后但同样重要的是故障条件。每个系统都有一定的阈值，除非达到。可能存在竞争条件、边界情况、下游依赖、存储层等，这可能导致失败。概述这些故障条件以及从这些条件中恢复的机制始终是一种好的做法。
除了以上内容，您还可以在设计文档中提及附录、数据建模、讨论等。系统设计是主观的，这篇文章仅代表我对良好文档的理解。欢迎您提供您的意见！
Leave a Reply