创建有效设计文档的实用指南
在与“数据架构”相关的指导/培训课程中，我经常会遇到这些问题。
- 设计文件应涵盖哪些设计方面？
- 真的需要设计文件吗？
- 应该向文档中添加多少详细信息？
我写这篇文章是为了帮助第一次编写设计文档的数据架构师。在这篇博客文章中，我将尝试涵盖设计文档的所有关键方面。这些都是基于我的经验&我相信还会有其他人可以在这里增加更多的分数。请将您的建议作为公开评论添加，以便其他读者也可以参考。
受众：数据架构师、技术负责人、解决方案设计师、技术项目经理、技术领导角色。
用于实现数据分析平台的设计文档应至少涵盖这10个部分。可以根据您想要捕获的用例和信息级别添加更多的部分、小节、示例和图表。
1.背景与概述
这不仅仅是设计文件的开头一段。这一部分可以帮助本文档的消费者理解整个计划的主要目标。确保它涵盖了为阅读本文档的所有人物角色（数据工程师、数据分析师、技术负责人、PM等）设置上下文所需的所有内容。
你可以涵盖以下几点。
- 项目的总体愿景和目标是什么？
- 这个项目将解决哪些具体问题？
- 本设计文件的主要目的是什么？
谁是这份文件的读者？一个好的做法是添加一个表格，突出观众在阅读本设计文件后的期望（基于他们的角色）。如果是一个规模较小、稳定的团队，您也可以添加名称。
2.要求
本节应高层次地总结需求，并应参考详细需求文件的放置位置，以便任何需要深入研究的人都可以阅读特定的业务需求文件。
- 列出每一项高级功能需求。
- 如果可能的话，添加RTM（需求跟踪矩阵）。它应该详细说明本设计文件中的哪一节/小节满足给定的要求。
- 强调是否有任何要求尚未得到解决或需要从当前范围中排除。（大多数设计文件都是实时文件，随着情况的明朗和需求的变化，这些文件会不断变化）
3.设计注意事项
设计注意事项和设计原则是设计文件中最关键的部分。
应根据
- 需求和整体数据愿景
- 当前系统的局限性和挑战
- 对现有系统的主要学习和观察
- 现有事件和问题
基于现有数据生态系统、源系统、下游应用程序和整个数据产业中的其他关键参与者
- 现有系统文档分析（来源、下游应用程序、现有平台）
- 先前实施的任何POC或MVP
- 内部或外部顾问进行的任何评估。
- 数据战略和数据治理原则
这些设计考虑因素可以在各种数据平台组件中进行分类。下面是一些例子供您快速参考。
a.数据源
- 它是批处理数据源还是流数据源？如果是流式传输，延迟要求是什么？
- 数据卷—需要物理迁移的任何大型数据卷（PB级）
b.数据摄入
- 是否需要基于API的数据摄取？这些API是否由源系统提供？
- 是否要获取增量数据？来源是否有能力识别变化（CDC）
c.数据处理
- 您需要ETL或ELT类型的处理吗？
- 转换有多复杂？是否有任何可以重用的现有代码？这有助于定义技术堆栈。
- 是否需要流媒体分析？
d.数据存储
- 你需要一个仓库、湖还是湖屋？
- 需要从现有系统迁移多少数据？
- 您是否只需要存储结构化数据？或者是否也需要存储非结构化数据？
e.数据消耗
- 您有BI或AI工作负载吗？
- 您是否需要特殊交互查询功能？
- 您需要共享数据吗？这些用户是在同一个生态系统内还是来自外部世界？
f.数据操作
- 团队目前使用的监控工具是什么？同样的东西可以利用吗？或者你需要一个新的工具吗？
- 未来有数据可观察性要求吗？
g.数据治理
- 谁将访问这些数据？外部用户还是仅内部用户？
- 您希望如何控制访问——粗粒度的还是细粒度的？文件级或表/属性级
- 现有数据消费者是如何发现数据的？是否有可用的数据目录？
i.数据安全
- 存储数据时是否有任何特定的法规遵从性要求？加密/数据主权规则？
- 处理敏感数据是否有任何与PII相关的要求？
- 所有这些都是设计新系统的重要考虑因素。你应该根据研究、RnD和你在设计系统时所做的讨论来记录所有这些。
4.设计原则
设计原则有助于定义在实施系统时需要遵循的通用规则和标准。这些原则可以帮助使用中央数据平台的各个团队建立共识。
应为每个基础设计支柱定义设计原则。下面列出了其中的一些例子
a.成本优化
- 在成本和性能之间保持适当的平衡。你不想建立一个性能最好、耗资巨大的系统。
- 仅提供所需的容量。从小规模开始，根据需要扩大规模或缩小规模。
- 启动、暂停和停止群集和作业，而不是全天候运行
b.卓越运营
- 记录所有内容，监控异常，跟踪异常
- 自动化所有部署，无需手动更改生产。
- 可重用的通用框架-类似活动无代码重复
c.性能改进
- 在设计阶段考虑性能
- 测试dev-env中的可扩展性，不要等到prod之前。
- 没有为实现性能目标而过度调配资源，在性能与成本之间取得平衡。
d.系统可靠性
- 提供备份和高可用性。尽可能多地使用内置功能。
- 制定完善的灾难恢复策略，及时审查、测试并做出更改
- 建立一个无需手动干预故障切换的自我修复系统。
e.数据安全
- 安全是一切的核心
- 数据-随时随地都应受到保护
- 加密/屏蔽/标记存储的数据。
5.技术解决方案
本节是设计文件的核心部分。这是您应该提供解决方案设计细节的地方。提供所有相关的细节，添加图表、示例、参考和公式——使其特定于您的用例，而不是仅包含另一个参考体系结构的部分。
添加以下具有所需详细级别的小节。
- a.架构图-包括构建块和关键组件。突出显示任何未最终确定、超出范围或属于未来范围的内容。
- b.数据流程图-对于数据项目非常重要。显示数据如何从一个组件流到另一个组件，包括正确的错误路径。
- c.每个组成部分的重要性-详细解释每个组成部分。它在系统中有什么用途？它将扮演什么角色？E.g数据摄取组件，用于将数据摄取到湖泊或仓库中。
- d.技术选择和选择理由-创建一个表格，列出可能的技术选择、您的建议以及选择它们的理由。强调每一项的优点和局限性。此外，请记住工程团队的技术技能。
- e.源系统详细信息-源系统、数据性质、摄入频率和任何限制的详细信息。检查他们是否发送结构化或非结构化、批处理或流式数据，并相应地拥有正确的工具堆栈。
- f.下游应用程序-从平台获得数据的应用程序的详细信息。这些机器或人类正在访问这些数据吗？他们计划如何利用这些数据？
6.非功能性要求
除了功能需求外，NFR对于任何大数据分析程序都同样重要。本节应包含与此类要求和新系统性能预期相关的详细信息。
需要考虑的一些关键NFR如下
- 针对不同工作负载的服务级别协议（SLA）。E.g应在何时向最终用户提供每日报告
- 源系统-频率和时间。源何时可以发送数据，如果出现延迟会发生什么？下一批应该开始还是等待文件？
- 系统时间表，假日日历-系统应该每天运行还是只在工作日运行？是否有需要遵循的企业级假日日历
- 现有的系统挑战-是否存在与性能相关的已知问题？现有的ETL大约需要6个小时才能完成，新系统应该可以在持续时间减少75%的情况下完成执行
7.数据安全和数据治理指南
对于任何数据项目来说，安全性都是最关键的方面。本节应提供实施必要的数据安全和数据治理流程的指导方针。
在高层，您应该包括以下详细信息
如何保护数据
- 静止数据-使用适当的加密密钥（如AWS KMS）。建议是否应将单独的密钥用于单独的数据湖层。（例如，如果源正在访问着陆层以传输文件，则着陆层可以具有单独的密钥）
- 传输中的数据-确保在传输数据时可以使用SSL/TLS或专用链接。
- 敏感数据-存储数据时对数据进行抽象的指导原则。这应该基于任何特定的合规规则，如存储信用卡数据的PCI-DSS标准。应用适当的加密、屏蔽或标记化逻辑
如何管理数据
- 表、视图、属性级别-您计划如何在数据库、表、视图甚至属性级别控制访问？提供与实施这些工具/流程相关的详细信息。
- 任何特定于PII的屏蔽策略-提供一种控制对PII数据访问的方法。（例如，使用AWS湖泊形成或雪花动态掩蔽）
- 提供临时访问权限-如何将临时访问权限提供给特定用户？这可以根据用例进行时间限制。
如何共享数据
- 与内部用户共享数据-如何在组织内与内部用户分享数据。这些可以是跨帐户或跨地区的用户或服务。
- 与外部用户共享数据-如何与外部世界共享数据。（例如，对于Snowflake，你能提供“阅读器”访问权限吗？）
8.测试指南
现在你们中的一些人可能会想——设计文档中与测试相关的部分在做什么？
对于任何数据项目，测试主要围绕“数据”，而不是像其他软件工程项目那样围绕“代码”。为了确保测试团队能够取得进展，数据架构师引导他们朝着正确的方向前进是很重要的。
您可以在本节中介绍以下几点
测试策略
- 总体测试策略是什么？
- 您计划如何测试数据？
- 您会对现有的目标表和新的目标表进行数据核对吗？
- 性能测试应该考虑多少数据量？
- 你想做的特殊场景是什么（例如与访问相关的测试、数据屏蔽测试）
测试自动化
- 您计划如何实现测试自动化？
- 您可以使用任何开源工具/库进行数据对账吗？
- 有没有任何方法可以在每次发布后自动化测试周期？
衡量成功
- 证明数据准确性的成功标准是什么？
- 如何签署最终数据——它是基于全部还是部分数据验证？
- 为了证明新系统适合实际用户使用，您需要进行多少次测试周期和并行执行
9.参考文献
本节将有助于使本设计文档成为您可以链接所有其他关键文档的唯一位置。对所有其他文档/链接/培训/演示的所有引用，这些文档可以帮助本文档的不同消费者。下面将提到其中一些。
文件
添加一个包含您在创建设计文档时引用的所有文档的表。此外，添加与其他文档相关的详细信息，这些文档在实现解决方案时可能对开发人员有用。
添加一个包含您在创建设计文档时引用的所有文档的表。此外，添加与其他文档相关的详细信息，这些文档在实现解决方案时可能对开发人员有用。
技术博客
添加与各种技术博客和文档相关的详细信息，帮助他们建立和测试团队。下面将提到其中一些。
- 来自产品供应商的技术博客-特别是与您在设计中考虑的一些功能有关。例如Snowflake的动态数据制作、AWS Glue PII检测功能、Databricks更改数据馈送。
- 与类似用例相关的各种数据会议/峰会的网络研讨会/离线视频。例如数据网格客户体验、Lakehouse实施。
- 有没有好的演示/实践视频，其中有与新功能相关的细节？E.g Databricks Unity目录功能及其使用方法
- 来自产品供应商的培训。例如，AWS Partnercast为合作伙伴或Databricks的客户培训视频
10.附录
文档的最后一部分，您可以在其中添加到目前为止尚未涉及的任何内容。本节可以有完整形式的缩写词、以前PoC的观察结果、其他有用的指南、标准和命名约定、基础设施细节等。
术语表和问题列表是您应该添加的几个要点。
- 术语表-提供一个表格，列出文件中使用的所有重要缩写词以及任何关键术语/概念/联系方式。
- 问题列表-需要持续维护的未结问题列表，应每天跟踪和关闭。这可以是维护它的门户网站的链接，甚至可以是Jira门票的链接。
虽然以上所有部分都很重要，但也有一些其他关键部分可以根据您的用例添加到设计文档中。
- 部署策略-如果您正在使用CI/CD，那么本节对于向所有团队提供通用指南至关重要。
- 代码库结构-您计划如何存储代码，如何维护修订以及如何批准和合并更改？
- 管理指南-整体基础设施设置是从头开始设置的云项目的第一个起点。添加与文档相关的链接，这些文档具有与云帐户、订阅、资源组、标签、模板等相关的详细信息。
除此之外，您还应该考虑其他因素。这些主要与创建设计文档的过程有关。下面列出了其中的一些。
你应该什么时候写设计文件？
它应该在您进行解决方案设计时创建。编写本文件有助于澄清在实施阶段可能出现的许多问题。在构建阶段进行过程中维护此文档，并在需要时进行更改。在实施解决方案时，您必须根据观察结果进行课程更正。
谁应该编写设计文件
它应该主要由具有早期设计类似系统的正确专业知识、知识和经验的数据架构师/解决方案设计师或技术负责人编写。
如果你是新手，不要担心。从他人的经验中学习并遵循本文中提到的步骤！
谁应该审查设计文件
文件中的各个部分应由不同的团队进行审查。需求可以由业务团队审查，NFR可以由生产支持成员审查，技术解决方案可以由将要构建解决方案的开发人员审查。听取所有人的意见——根据需要但基于你的判断做出改变。你不能同意每个人的观点，因为本文档的每个消费者都扮演着不同的角色，你需要确保最佳设计与实用/可行的设计之间保持平衡。
设计文档是一个实时文档。
请记住，此文档中会有更改。确保在取得进展的同时维护和更新文档。有时，也可能会根据需求、性能问题或技术堆栈的变化进行重大设计更改！
接受签字
不要忘记接受所有利益相关者的签字。这将确保每个人都阅读了该文件并达成共识，主要围绕设计考虑和设计原则。这将确保使用本文档的所有团队都必须遵守文档中提到的通用管理政策。
我希望这篇文章能帮助您为计划构建的数据和分析平台编写设计文档。请添加您的意见，如果您认为应该添加其他内容以使设计文档对受众更有用，请告诉我。
感谢您的阅读，祝您度过美好的一天！
