软件架构｜设计中如何编制详细设计说明文档

好事发生

这里推荐一篇实用的文章：Go Mongox 开源库设计分享：简化 MongoDB 开发的最佳实践，作者：【陈明勇】。

这篇文章作者主要讲mongo-go-driver 功能强大，但通过进一步封装，可以在实际开发中显著提升开发效率，特别是在复杂场景下减少代码冗余和提升可读性方面。开发一个功能类似 go mongox 的库并不复杂，但如何通过精心设计实现出色的扩展性、易用性和复用性，才是开发者需要深思的问题。

引言

呦吼，这是风筝🪁，是不是很漂亮，我很担心你说不漂亮，因为这是甲方提供的设计图，具体实物如何，就要靠供应商来实施模具设计、实物加工、出厂验收等等一系列工具，最终才能到达甲方手里。风筝作为一种交付物品，架构设计固然不能缺少，就像我们在软件开发中，软件的架构设计也不能缺少一样，尤其是在IT软件设计中。下面我想引用制作风筝来说明编制架构设计文档。

制作风筝

制作一个风筝是一个既有趣又富有创造性的过程，我们做项目也如此，那么如何才能制作出来一个比较钟意的风筝呢？

1 准备设计阶段

【目标】：首先得有一个目标，或者说是一个诉求，那就是甲方需要一款风筝。

【设计和规划】：得搜罗下如何制作，制作的步骤，制作的工具，制作出来测试等等。

【工具】：规划和设计之后，得考虑设计中所需要的工具，例如：剪刀、笔、直尺、美工刀（或锯子，用于处理木条）、砂纸、油漆刷、塑料胶带或胶水。

【材料】：需要哪些材料，材料如何获取等等

上述所有步骤在软件开发中就是如何选择架构、合理的搭配等。

2 制作实施

在制作上，可以考虑绘制图案，竹条（木条）的处理，骨架的组装，蒙面，尾巴处理等等。这些详细的设计以及步骤应该在提前设计好。

这个步骤就比较简单，按照所列计划进行实施，在软件开发中也是如此。

3 调试

风筝的调试就是放飞，在调试过程中，需要考虑个人安全，选择合适的室外飞行场所等等。这应对到软件开发性能、可维护性和扩展性。

软件开发中的架构设计

回归到正题，看了上面制作风筝是不是也想跃跃欲试？先回到我们软件开发中的设计来，后续我们再来看看风筝的制作。

系统架构

系统架构是系统的一种整体的高层次的结构表示，是系统的骨架和根基，其决定了系统的健壮性和生命周期的长短。

架构的定义来源于IEEE 1471-2000，架构是体现在组件中的一个系统的基本组织、它们彼此的关系与环境的关系及指导它的设计和发展的原则。

例如Java平台标准版8，也可以说是Java平台的架构，从图中可以看到Java相关结构。

图来自：https://docs.oracle.com/javase/8/docs/index.html

软件架构的定义

【软件架构】

软件架构（也可称为体系结构）是用来刻画软件系统整体抽象结构的一种手段，软件架构设计也是软件系统开发过程中的一个重要环节。

文档设计的重要性

在软件架构设计中，编写文档确实是一个至关重要的环节。文档的重要性不言而喻，他主要体现在甲方的最终目的。

明确需求和预期期望，通过阐述功能需求和非功能需求一集当前的业务逻辑，来确保后续的软件能够准确的满足实际需要。

设计文档可以促进团队协助，文档是桥梁，通过文档可以提高沟通效率和协助速率，利于共同推送项目进展。

指导开发者和实施者，架构设计文档可以为开发团队提供明确的指导，帮助他们了解系统的整体架构、模块划分、接口设计等信息。这有助于减少开发过程中的误解和错误，提高开发效率和质量。

方便运维实施，系统的功能和结构可能会发生变化。通过编写和维护文档，可以方便地记录系统的演变历程和当前状态，为后续的维护、升级和扩展提供有力的支持。

如何开启架构文档设计

本文所列文档设计为局部，不代表通用，可以酌情处理、补充。我认为此处应该有10步骤可以完成。

1文档综述

文档综述主要是描述文档编写的目的，适用范围，所引用国家、企业规范性的材料以及所具有的约束内容。

2系统功能设计

系统功能设计主要体现在总体设计、接口功能设计、集成服务设计、接口实现等。

功能设计是系统开发的基础，如果功能设计不合理、不清晰或不符合用户需求，系统可能无法被用户接受，导致项目失败或用户流失。因此，在系统功能设计中，需要考虑到用户的期望、系统的可行性以及技术的限制，以达到最佳的用户体验和系统性能。

接口功能设计，主要明确接口的定义名称、参数、返回值、错误码，接口名称应该简明和让人快速理解含义。数据传输过程中，数据格式如JSON、XML等要考虑到可读性和解析的效率。设计清晰的错误码和错误信息，方便开发人员和用户快速定位和解决问题。如果可能，尽量在文档中标注流程设计的逻辑。例如调用微信公众号粉丝列表接口。

集成服务设计，集成服务设计主要是在设计中集成其他系统或者数据，形成一个闭环。主要有业务流程集成、数据资源集成、页面集成等等。在编写设计时，最好集成一个服务就编制一个，例如集成QQ登录。

3业务功能设计

业务功能设计一般贴合自身情况，主要编写有业务功能的一些描述信息。编制时采取总分效果最好。一般有功能界面（一般都是一些UI图表），形成分类、分级、分模块等结构来编织。

4接口服务设计

接口设计也是采取总分效果最好，在编制时需要梳理接口清单，每一个接口都要有一个设计说明，包括接口名称、参数（输入参数、输出参数）、接口调用逻辑（包括算法逻辑）、组件之间的调用关系，最好有图展示，更能清晰直观。

5数据库设计

数据是业务系统中的血液，支撑到角角落落，在设计时需要关注模型。文档中需要有模型视图、模型清淡等，当然，再详细设计时，设计的颗粒度需要到字段。例如某个库的某张表的某个字段。

6安全架构设计

安全架构在设计中是非功能性设计，需要架构设计中权衡软件的安全应用场景和应用环境，在性能、灵活性和可维护性之间找到平衡点。

可靠性

在设计时，确保系统高可用性，保证7×24小时不间断运行，年可用率高达（不统计计划停机）99.9%。具体技术要求包括：

• 中间件使用负载均衡技术将系统请求压力分担到可扩展的集群上，解决单服务器性能瓶颈可扩展问题，保障平台的稳定性。
• 基于云微服务多实例集群部署与多实例故障切换方式实现服务故障切换，保障服务可靠运行。
• 通过增加服务器节点以达到整个服务器集群的性能提高，提升平台的服务计算能力。
• 数据库采用读写分离、分布式或集群等高可用部署方式，解决单服务器数据库性能瓶颈可扩展问题。

稳定性

考虑系统未来可能的增长需求，设计能够方便扩展的架构，确保系统能够按需水平或垂直扩展。建立良好的监控体系和日志记录机制，及时发现问题并追踪排查故障。通过负载均衡技术合理分配系统负载，避免某个节点过载而影响整体性能。定期进行性能测试和优化，确保系统在高负载情况下依然能够保持稳定运行。

高安全

在建设信息系统时，一般按照国家技术安全标准《信息安全技术网络安全等级保护基本要求》的规范实施。

易维护

易维护体现在系统的部署和升级，采用企业标准版本的建设模式，系统的部署和升级采用统一发布、脚本部署方式，系统支持热部署、热更新，除数据库这些重大升级改造外，系统部署升级可不停机完成。

易扩展

易扩展在服务实现的基础上进行服务化的封装和定义，以标准的接口技术协议HTTP和JSON数据结构提供服务调用或获取外部服务，对外屏蔽服务实现的技术细节，实现服务实现层与业务功能层之间的松耦合，具备易扩展性。

安全设计方案

安全设计方案主要体现系统安全等级、安全通信网络设计、安全区域边界设计、安全计算环境设计、数据库安全、中间件安全、应用安全设计、数据安全设计、密码安全、安全管理、云安全，如果有安全对接还需要标注安全对接中的安全设计，如果有涉及到移动嵌入式安全，也需要纳入其中。

7软硬件设计

逻辑架构设计

软件设计中有总体设计，此处也可以标注为逻辑架构设计，包括技术架构设计、功能架构设计和数据架构设计。实际上我们一般写说明性文档时，会经常将技术架构标榜在这里，也就是按照分层架构来编写，看一张图就可以明白了。

事件驱动架构、微核架构并不是我等牛马关心的，这些都是高精尖的，一般情况也不会考试这两个，着重看下定义就好了。

物理架构设计

物理架构是部署和运行层次的架构，主要支撑服务的实际运行和运行管理工作。物理架构的设计着重考虑“安装和部署需求”，即软件系统最终如何安装或部署到物理机器。

硬件信息清单

硬件信息是系统运行的骨架，需要描述清晰且准确。主要包括硬盘大小、内存、网卡等。

软件信息清单

系统运行的软件以及一些中间件，包括名称、版本、型号等。

8日志监控

日志监控（LogMon）是一站式的日志数据管理工具，它集日志收集、数据分析以及数据视图化功能于一体，有助于用户提升运维、运营效率，快速查找和定位问题。

9数据备份

数据备份在设计时主要是提供数据备份的相关信息时，可以包含备份策略、备份方式、备份软件以及备份时间表等关键内容。

10 附录表

附录表通常用于在文档或报告的末尾提供额外的数据、信息或详细资料，以便阅读此文档在需要时查阅。附录表可以包含各种类型的数据，如统计数据、配置参数、产品规格、代码示例等。

总结

好了，写了这么多，结合自己在编写详细架构设计时的总结，希望在帮助你的同时可以让你在编制时更清晰、更快速的编制文档。