软件架构文档编写
合集下载
相关主题
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
模式
当使用MDSD的时候，架构模式可以作为架构元 模型的基础来使用（见后）
• 一个架构模式的结构化解决方案可以被描述为一个元模型。
编写你自己的模式
如果你在业务领域中（技术性或功能性） 发现了某种可重复的最佳体验你可能会用 模式的方式把他们记录下来。
模式单（有多种形式）通常会要求作者严 格的把内容结构化。
架构模式
架构模式可以用来描述工作良好的架构风格和蓝 图
在POSA的系列书籍中已有许多描述，如在 [POSA1]中。
示例：
• 黑板 • 管道和过滤器 • 微内核 • 组件和连接器
当然，SEI把许多同样的架构编档为架构风格，我 们也可以加以参考。
架构模式和风格：概览
管道和过滤器模式
组件仅通过本地接口实现为无状态的Session Beans。
过程实现为消息驱动类型的beans；消息通过 JMS实现。
数据结构和过程状态以JPA为基础持久化到关系 数据库中。
使用JBOSS作为J2EE容器管理应用程序组件。 数据库用Oracle。
概念架构与编程模型的比较
概念架构与其具体的技术实现可以相当复杂-为了 满足包括非功能性需求在内的所有需求。
• 许多覆盖到中间件技术[服务器组件模式，远程模式]， • 他们通过不同的形式发布
布局与排版 图表编制方针 摘要
所有部件的编档基础
对于每一个部件，确定受众的状态及定义-确保内 容与受众相关
采用适当的媒介/渠道（见后） 文档应尽可能的简练 避免重复！每一方面的问题只记录在一个地方，
使用关联（而不是引用）来连接有关主题 象编码一样，文档也要放入版本控制系统中（不
-共享状态可能是昂贵和复杂的 -可能存在数据转换成本比较高 -错误的操作
架构模式的确定要点
架构模式在架构设计领域具有一些确定的要点。
• 你应该理解需求 • 你设计了一个初始架构 • 你发现他与某种架构模式类似 • 你分析之间的不同。关键吗？ • 接着你审查这些模式的推论看他们是否可被接受。 • 然后你可能会迭代…也许直到你碰到在架构设计领域的另一个
• 第一步是仅覆盖基本的层 • 然后是在图示上增加更多的层 • 这样可以使事物易于理解
可视化…见后。
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
布局与排版 图表编制方针 摘要
术语表
术语表列出的是相关的架构概念及其含义 和关系
对基本的概念进行说明有助于读者熟悉架 构中使用的术语
要让术语表不那么抽象，需要在介绍每一 个术语的时候附有示例
术语表可以用在概念架构和应用程序架构 中-但在概念架构中更重要些
目标听众：每一位技术人员
术语表示例
结构化术语表
用图表的形式展现核心概念，概念间的关 系加亮显示
我的观点： 架构是那些需要贯穿系统始终的一致的东西。
架构/系统 分类-重点
小型，点对点系统：典型的由小型团队开发的系 统
大型系统：大型团队开发，体现在战略层面上， 具有较长的生命周期
产品线和平台：构建在一系列系统之上的基础架 构，通常由几个团队开发，体现在战略层面上
我们要将主要的焦点集中在大型系统和产品线上因为对于小型系统和点对点系统来讲架构文档并 不是必须的
什么是软件架构II
Boehm, et al., 1995: 一套软件系统架构包含：
• 软件及系统组件、连接和约束的集合。 • 系统干系人需求描述的集合。 • 描述的是这样的基本原则，如果实现了定义系统的组件、连接
和约束，那么就应该满足系统干系人的需求集合。
其他： 架构指的是这样的东西，如果以后发生了改变， 那么代价将是昂贵的。
我们称这些有限数量的概念和他们间的关系为概念架构 用于构建具体应用系统的具体的实例化的概念称之为应用
架构 一个良好定义的概念架构对于大型系统和产品线来讲是有
重大意义的，他能确保系统
• 内在一致 • 可理解 • 可扩展
应用程序与概念模型的比较II：例子
应用程序架构： 我们打算构建一个企业系统，他包含了几个子系 统，如客户管理，账务和目录。除此之外还包括 使用数据库、表单等来管理数据，我们也要管理 有关的长期运行的业务过程。
• 观点：唯一正确的架构是持续改进的，但在任何给定时刻他也 是良好定义的
因此，在变更过程中的任何时刻保持应用程序与 架构的一致性是使系统一致稳固的关键
• 理想情况下你需要借助工具来‘坚持’架构…
哪些内容需要进行编档？
概念层次：
• 概念架构 • 干系人及其需求 • 概念架构为什么是这样的基本原理 • 编程模型 • 技术映射
• 如何传递数据？
容器能够提供的服务是什么？ 我能使用哪些java语言的特性？
概念架构与编程模型的比较：例 子II
架构化的过程
在我们搭建系统的时候架构（包括概念架构和应 用程序）一直在持续改进。
• 可能有或多或少的适当的原始的想法… • …可能基于架构风格和模式… • …总是持续改进
然而，在任何给定的时刻总有唯一正确的架构
与具体技术有关的映射应该放在另外独立的阶段细化 作为概念模型指明的一部分，映射应该受其非功能性和操
作性需求的指导 将技术问题与概念架构进行良好的分离是一种有效的方法：
• 有能力进行一些技术方面的变更 • 通过尽可能的将具体技术细节进行隔离可以简化应用程序的开发
概念架构与技术决策的比较：例子
• 开始是设置上下文 • 说明何时和谁会对以下的材料感兴趣 • 按逐级细化的方式描述问题和解决方案 • 然后详细阐述推论 • 最后，点明有关材料
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
应用程序开发人员应该拥有一份良好定义的编程 模型以使应用程序的开发尽可能切合架构：
• “简化典型用例，尽可能简化例外用例”
编程模型应该尽可能的隐藏技术实现细节-并使概 念架构变得易于访问
• 他可以看做是“架构API”
概念架构与编程模型的比较：例子
如何编写一个组件？ 如何细化一个过程？ 如何实例化一个数据对象？ 如何在通讯中使用管道？ 如何向一个过程发送事件？
布局与排版 图表编制方针 摘要
编档复杂架构的挑战
简单收集一些描述性的数据对一个架构来 讲是不够的
• 比如一个大型的UML模型或是一套图表或API
而且，就一个架构进行交流需要一个良好 定义的，有指导意义的方法，在这里
• 开始于产生打算搞清楚那些一般性问题（架构要记 录什么）的动机
• 然后提供一个解决方案策略的概览 • …然后逐步提供越来越详细的的内容… • 直到覆盖所有的用例，包括边界用例
布局与排版 图表编制方针 摘要
什么是软件架构
Wikipedia: 程序或者计算机系统的软件架构，描述的是系统 的一个或一组结构，它包含软件元素、外部可见 的元素属性以及元素间的关系。
Eoin Woods: 软件架构是一整套的设计决策，如果决策失误， 可能会导致项目中止。
Hayes-Roth: 一套复杂软件系统的架构体现了其设计和构筑的 风格及方法
缩略图：
• 管道和过滤器模式是处理数据流的一种结构化系统。 • 每一个处理步骤都被包装进过滤器组件。 • 数据通过管道在相邻的过滤器中传递。 • 重组过滤器可以用来构建相似的关系系统。
• 已知的应用：
• 编译器（不同阶段） • UNIX外壳系统
架构模式/管道和过滤器模式II
推论： +中间文件不是必须的，但是可能会有 +通过变更或者重组过滤器来实现弹性化 +过滤器组件可重用 +快速原型化管道 +并行处理过程使提高效率成为可能
软件架构的表现形式
在下面的图表中描述了一些在后面的文档 中会用到的术语和概念
应用程序 实现技术
概念架构 技术映射
编程模型 语言
应用程序与概念模型的比较
任何有价值的，具有良好架构的系统典型的是由许多有限 数量概念的实例组成。
• 组件和连接器，管道和过滤器，层，等等。 • 架构式的模板和风格是一个良好的开端
布局与排版 图表编制方针 Βιβλιοθήκη Baidu要
参考模式
如果你在描述某种软件结构，该软件结构已经有 模式文档，那么引用该模式是有意义的-读者可能 知道它！
在文献中模式有相当篇幅的内容，有关主题诸如
• Distributed (Object) Systems [POSA2, POSA4] • Remoting Infrastructures [Remoting Patterns] • Resource Management [POSA3] • Patterns of Enterprise Application Architecture [PoEAA] • Enterprise Integration Patterns [EIP], Integration Patterns • [IP]
• 这种方式会强迫作者努力考虑诸如应用性、力度或 者推论等素材。
• 对读者来讲，结构化良好的内容更易于理解。
使用模式单
如果某件事情不能重复那他就不是一个模式… 把内容写在模式单上有助于提高沟通的有效性，
模式单提供一种方法可以将复杂的结构进行分解 从而改进书写风格（和作者的熟练度）。
一旦你习惯了模式单，那你会在编写任何类型技 术文档的时候自然而然的使用它。比如：
复杂系统的内部结构
模式语言是用来描述一个“整体” 的模式的集合/ 序列，
• 系统的全部结构很复杂，难于一步就描述出来-因此产生了模 式语言。
• 有时候可以通过可选择次序的模式语言来描述一个‘整体’不 同选择
• 以前曾经提到把模式分组放入到章节中来实现层/级/环
模式语言用来描述如何构建某种类型的复杂系统。 关于模式语言有几个不同的例子，
软件架构编档方法
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
布局与排版 图表编制方针 摘要
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
是那种基于Web的奇怪的协作平台）
• 开发文档也是如此 • 可能有不同的发布渠道
所有部件的编档基础II
总是自上而下的编制文档
• 仅为那些确实需要了解细节的用户逐步提供更详尽的内容 • 确保用户不能为了理解概念和大图片去翻阅所有的细节内容！
尽量将架构结构化（至少文档要结构化），结构 化是指使用层、级或者环的概念。
应用程序层次：
• 应用程序架构 • 干系人及其需求 • 应用程序架构为什么是这样的基本原理
我们应该将焦点主要放在概念层次上
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
概念架构：
核心的构建主体是组件、接口、数据类型、业务 过程和通讯管道。通讯是同步和本地的。过程间 的通讯是异步和远程的。组件被发布/部署在某种 有技术方面考虑的容器中。
概念架构与技术决策的比较
概念架构应该尽可能的独立于具体的技术决策(POJOS)
• 在这里，技术泛指操作系统、DOC和消息中间件、驱动，UI框架 • 我们不必抽离语言或范例
UML类图很适用这种形式的描述 对一般术语表来将结构化术语表是一个补
充，不是替代，因为他们不解释概念，只 是展现关系
对建模人员来讲：这与元模型不同，因为 他们缺少正式内容，缺少细节，一般也不 是“可实现的”
结构化术语表示例
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
当使用MDSD的时候，架构模式可以作为架构元 模型的基础来使用（见后）
• 一个架构模式的结构化解决方案可以被描述为一个元模型。
编写你自己的模式
如果你在业务领域中（技术性或功能性） 发现了某种可重复的最佳体验你可能会用 模式的方式把他们记录下来。
模式单（有多种形式）通常会要求作者严 格的把内容结构化。
架构模式
架构模式可以用来描述工作良好的架构风格和蓝 图
在POSA的系列书籍中已有许多描述，如在 [POSA1]中。
示例：
• 黑板 • 管道和过滤器 • 微内核 • 组件和连接器
当然，SEI把许多同样的架构编档为架构风格，我 们也可以加以参考。
架构模式和风格：概览
管道和过滤器模式
组件仅通过本地接口实现为无状态的Session Beans。
过程实现为消息驱动类型的beans；消息通过 JMS实现。
数据结构和过程状态以JPA为基础持久化到关系 数据库中。
使用JBOSS作为J2EE容器管理应用程序组件。 数据库用Oracle。
概念架构与编程模型的比较
概念架构与其具体的技术实现可以相当复杂-为了 满足包括非功能性需求在内的所有需求。
• 许多覆盖到中间件技术[服务器组件模式，远程模式]， • 他们通过不同的形式发布
布局与排版 图表编制方针 摘要
所有部件的编档基础
对于每一个部件，确定受众的状态及定义-确保内 容与受众相关
采用适当的媒介/渠道（见后） 文档应尽可能的简练 避免重复！每一方面的问题只记录在一个地方，
使用关联（而不是引用）来连接有关主题 象编码一样，文档也要放入版本控制系统中（不
-共享状态可能是昂贵和复杂的 -可能存在数据转换成本比较高 -错误的操作
架构模式的确定要点
架构模式在架构设计领域具有一些确定的要点。
• 你应该理解需求 • 你设计了一个初始架构 • 你发现他与某种架构模式类似 • 你分析之间的不同。关键吗？ • 接着你审查这些模式的推论看他们是否可被接受。 • 然后你可能会迭代…也许直到你碰到在架构设计领域的另一个
• 第一步是仅覆盖基本的层 • 然后是在图示上增加更多的层 • 这样可以使事物易于理解
可视化…见后。
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
布局与排版 图表编制方针 摘要
术语表
术语表列出的是相关的架构概念及其含义 和关系
对基本的概念进行说明有助于读者熟悉架 构中使用的术语
要让术语表不那么抽象，需要在介绍每一 个术语的时候附有示例
术语表可以用在概念架构和应用程序架构 中-但在概念架构中更重要些
目标听众：每一位技术人员
术语表示例
结构化术语表
用图表的形式展现核心概念，概念间的关 系加亮显示
我的观点： 架构是那些需要贯穿系统始终的一致的东西。
架构/系统 分类-重点
小型，点对点系统：典型的由小型团队开发的系 统
大型系统：大型团队开发，体现在战略层面上， 具有较长的生命周期
产品线和平台：构建在一系列系统之上的基础架 构，通常由几个团队开发，体现在战略层面上
我们要将主要的焦点集中在大型系统和产品线上因为对于小型系统和点对点系统来讲架构文档并 不是必须的
什么是软件架构II
Boehm, et al., 1995: 一套软件系统架构包含：
• 软件及系统组件、连接和约束的集合。 • 系统干系人需求描述的集合。 • 描述的是这样的基本原则，如果实现了定义系统的组件、连接
和约束，那么就应该满足系统干系人的需求集合。
其他： 架构指的是这样的东西，如果以后发生了改变， 那么代价将是昂贵的。
我们称这些有限数量的概念和他们间的关系为概念架构 用于构建具体应用系统的具体的实例化的概念称之为应用
架构 一个良好定义的概念架构对于大型系统和产品线来讲是有
重大意义的，他能确保系统
• 内在一致 • 可理解 • 可扩展
应用程序与概念模型的比较II：例子
应用程序架构： 我们打算构建一个企业系统，他包含了几个子系 统，如客户管理，账务和目录。除此之外还包括 使用数据库、表单等来管理数据，我们也要管理 有关的长期运行的业务过程。
• 观点：唯一正确的架构是持续改进的，但在任何给定时刻他也 是良好定义的
因此，在变更过程中的任何时刻保持应用程序与 架构的一致性是使系统一致稳固的关键
• 理想情况下你需要借助工具来‘坚持’架构…
哪些内容需要进行编档？
概念层次：
• 概念架构 • 干系人及其需求 • 概念架构为什么是这样的基本原理 • 编程模型 • 技术映射
• 如何传递数据？
容器能够提供的服务是什么？ 我能使用哪些java语言的特性？
概念架构与编程模型的比较：例 子II
架构化的过程
在我们搭建系统的时候架构（包括概念架构和应 用程序）一直在持续改进。
• 可能有或多或少的适当的原始的想法… • …可能基于架构风格和模式… • …总是持续改进
然而，在任何给定的时刻总有唯一正确的架构
与具体技术有关的映射应该放在另外独立的阶段细化 作为概念模型指明的一部分，映射应该受其非功能性和操
作性需求的指导 将技术问题与概念架构进行良好的分离是一种有效的方法：
• 有能力进行一些技术方面的变更 • 通过尽可能的将具体技术细节进行隔离可以简化应用程序的开发
概念架构与技术决策的比较：例子
• 开始是设置上下文 • 说明何时和谁会对以下的材料感兴趣 • 按逐级细化的方式描述问题和解决方案 • 然后详细阐述推论 • 最后，点明有关材料
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
应用程序开发人员应该拥有一份良好定义的编程 模型以使应用程序的开发尽可能切合架构：
• “简化典型用例，尽可能简化例外用例”
编程模型应该尽可能的隐藏技术实现细节-并使概 念架构变得易于访问
• 他可以看做是“架构API”
概念架构与编程模型的比较：例子
如何编写一个组件？ 如何细化一个过程？ 如何实例化一个数据对象？ 如何在通讯中使用管道？ 如何向一个过程发送事件？
布局与排版 图表编制方针 摘要
编档复杂架构的挑战
简单收集一些描述性的数据对一个架构来 讲是不够的
• 比如一个大型的UML模型或是一套图表或API
而且，就一个架构进行交流需要一个良好 定义的，有指导意义的方法，在这里
• 开始于产生打算搞清楚那些一般性问题（架构要记 录什么）的动机
• 然后提供一个解决方案策略的概览 • …然后逐步提供越来越详细的的内容… • 直到覆盖所有的用例，包括边界用例
布局与排版 图表编制方针 摘要
什么是软件架构
Wikipedia: 程序或者计算机系统的软件架构，描述的是系统 的一个或一组结构，它包含软件元素、外部可见 的元素属性以及元素间的关系。
Eoin Woods: 软件架构是一整套的设计决策，如果决策失误， 可能会导致项目中止。
Hayes-Roth: 一套复杂软件系统的架构体现了其设计和构筑的 风格及方法
缩略图：
• 管道和过滤器模式是处理数据流的一种结构化系统。 • 每一个处理步骤都被包装进过滤器组件。 • 数据通过管道在相邻的过滤器中传递。 • 重组过滤器可以用来构建相似的关系系统。
• 已知的应用：
• 编译器（不同阶段） • UNIX外壳系统
架构模式/管道和过滤器模式II
推论： +中间文件不是必须的，但是可能会有 +通过变更或者重组过滤器来实现弹性化 +过滤器组件可重用 +快速原型化管道 +并行处理过程使提高效率成为可能
软件架构的表现形式
在下面的图表中描述了一些在后面的文档 中会用到的术语和概念
应用程序 实现技术
概念架构 技术映射
编程模型 语言
应用程序与概念模型的比较
任何有价值的，具有良好架构的系统典型的是由许多有限 数量概念的实例组成。
• 组件和连接器，管道和过滤器，层，等等。 • 架构式的模板和风格是一个良好的开端
布局与排版 图表编制方针 Βιβλιοθήκη Baidu要
参考模式
如果你在描述某种软件结构，该软件结构已经有 模式文档，那么引用该模式是有意义的-读者可能 知道它！
在文献中模式有相当篇幅的内容，有关主题诸如
• Distributed (Object) Systems [POSA2, POSA4] • Remoting Infrastructures [Remoting Patterns] • Resource Management [POSA3] • Patterns of Enterprise Application Architecture [PoEAA] • Enterprise Integration Patterns [EIP], Integration Patterns • [IP]
• 这种方式会强迫作者努力考虑诸如应用性、力度或 者推论等素材。
• 对读者来讲，结构化良好的内容更易于理解。
使用模式单
如果某件事情不能重复那他就不是一个模式… 把内容写在模式单上有助于提高沟通的有效性，
模式单提供一种方法可以将复杂的结构进行分解 从而改进书写风格（和作者的熟练度）。
一旦你习惯了模式单，那你会在编写任何类型技 术文档的时候自然而然的使用它。比如：
复杂系统的内部结构
模式语言是用来描述一个“整体” 的模式的集合/ 序列，
• 系统的全部结构很复杂，难于一步就描述出来-因此产生了模 式语言。
• 有时候可以通过可选择次序的模式语言来描述一个‘整体’不 同选择
• 以前曾经提到把模式分组放入到章节中来实现层/级/环
模式语言用来描述如何构建某种类型的复杂系统。 关于模式语言有几个不同的例子，
软件架构编档方法
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
布局与排版 图表编制方针 摘要
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
是那种基于Web的奇怪的协作平台）
• 开发文档也是如此 • 可能有不同的发布渠道
所有部件的编档基础II
总是自上而下的编制文档
• 仅为那些确实需要了解细节的用户逐步提供更详尽的内容 • 确保用户不能为了理解概念和大图片去翻阅所有的细节内容！
尽量将架构结构化（至少文档要结构化），结构 化是指使用层、级或者环的概念。
应用程序层次：
• 应用程序架构 • 干系人及其需求 • 应用程序架构为什么是这样的基本原理
我们应该将焦点主要放在概念层次上
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节
概念架构：
核心的构建主体是组件、接口、数据类型、业务 过程和通讯管道。通讯是同步和本地的。过程间 的通讯是异步和远程的。组件被发布/部署在某种 有技术方面考虑的容器中。
概念架构与技术决策的比较
概念架构应该尽可能的独立于具体的技术决策(POJOS)
• 在这里，技术泛指操作系统、DOC和消息中间件、驱动，UI框架 • 我们不必抽离语言或范例
UML类图很适用这种形式的描述 对一般术语表来将结构化术语表是一个补
充，不是替代，因为他们不解释概念，只 是展现关系
对建模人员来讲：这与元模型不同，因为 他们缺少正式内容，缺少细节，一般也不 是“可实现的”
结构化术语表示例
目录
什么是软件架构 编写软件架构文档
• (结构化)术语表 • 模式及模式单 • 模式语言 • 指南和FAQs • 图表与建模 • 学习渠道 • 代码包含什么？ • 产品线和平台细节