你应该把什么build筑规范?

我目前正在为我的公司修改一些文档模板。 我们从来没有过的一件事是正式的架构规范,所以我开始把它们放在一起。

你把什么样的东西放到你的架构规范中? 随意复制和粘贴目录 – 这将是有益的。 网上有没有好的模板可用?

我同意亚萨的信仰, 幸运的是,生成有用/实用的架构文档并不是不可能的 – 只是不常见。

对我来说关键是要了解这个文件是谁的,他们什么时候使用它? 他们为什么要用它? 太多的时候,它只是一些项目计划中的勾选框的填表练习。

我假设你的意思是一个软件体系结构文档或解决scheme体系结构文档 – 而不是企业战略或某事。

还记得典型的体系结构文档会做两件事:

  • 为其他地方的决策提供input:“这是我们目前的想法 – 是否有人决定是否花大价钱购买DR站点等等”。
  • logging决定:特别说明你的决定。

在结构和关键信息方面,我build议您查看系统的不同视图:逻辑,物理,数据,安全性等。 一个好的起点是4 + 1模型 。

[更新:]这样一个artefact的用途之一是可追溯性 – 从要求和devise人工制品到代码人工制品; 尽pipe这可能听起来像是以瀑布为导向,但它实际上也适用于(也适用于)基于敏捷的项目。

[更新:]人造物不代表 “Word文档”。 下面的ToC示例是一个基于UMLbuild模工具(SparxEA)build模的支持文档/文档的系统版本,其中还包括需求。 有时候你“不得不”使用一个文件,但是我尽可能地尽可能保持原样。

关于一个清晰明了的文件的另一个好处是,新血更容易理解他们正在inheritance什么 – 特别是如果以前的工作人员不可用。

卡耐基梅隆大学的软件工程研究所拥有大量的信息,在下面的页面中提供了一个模板链接: http : //www.sei.cmu.edu/architecture/tools/viewsandbeyond/
要知道这是非常全面的 – 不是因为心灵的缺乏(或者时间不够)。

[更新:]最后,这是一个来自最近项目的示例目录。 尽pipe有很多章节,文档不会太长(大约只有35页,其中很大一部分是图表)。

Table of Contents 1 Documentation Roadmap 1.1 Document & Version Information 1.1.1 Document Contributors 1.1.2 Referenced Documents 1.1.3 Reviewers 1.1.4 Document Signoff 1.2 Glossary of Terms 1.3 Purpose and Scope of the SAD 1.4 Stakeholder Representation 2 Project Background 2.1 Problem Background 2.2 Solution Overview and Project Phases 2.3 Solution Context 2.3.1 Solution Usage 2.4 Architectural Goals 2.5 Constraints 2.6 Considerations 3 Register of Issues and Decisions 3.1 Issues Register 3.2 Decisions Register 4 Overview of Key Views 5 Functional View 6 Logical Layers View 7 Physical View 7.1 Mapping of Logical and Physical Components 7.2 Mapping of Logical Layers and Bespoke Packages 7.3 Bespoke Physical Components 7.4 Common 7.5 Business Logic 7.6 Data Provider Interfaces 7.7 MS SQL Data Provider 7.8 Data Repository 7.9 External Data Services – Time Sheeting 7.10 External Data Services - DLR 7.11 UI - Flash 7.12 FlourineFX 7.13 UI - ASP.NET 7.14 Model 7.15 Login 7.16 Mapping To Physical Components 7.17 Solution Dependencies 8 Solution Views 8.1 Data View 23 8.1.1 Conceptual Data Model 8.1.2 Physical Data Model 8.2 Technology View 8.2.1 Microsoft Windows Server 8.2.2 Microsoft Internet Information Server 8.2.3 Microsoft SQL Server 8.2.4 Microsoft .Net Framework 8.2.5 Microsoft ASP.NET 8.2.6 Microsoft ASP.NET Role Membership Provider 8.2.7 Dot Net Nuke (DNN) 8.2.8 AntiXSS Library 8.2.9 Microsoft Enterprise Libraries 8.2.9.1 Application Logging Block 8.2.10 Log4Net 8.2.11 Fluorine 8.2.12 Adobe Flash 8.3 Security View 8.3.1 Data Encryption – Data at Rest 8.3.2 Data Encryption – Data in Flight 8.3.3 Authentication 8.3.4 Authorisation 8.3.5 Non-Repudiation 8.3.6 Cross-Site Scripting (XSS) and SQL Injection 8.3.7 Other Security Concerns 8.4 Infrastructure View 8.5 Support View 8.6 Enterprise Standards Compliance 9 Design Patterns and Principles 9.1 Dependency Inversion Principle 9.2 Dependency Injection Pattern 9.3 Factory Pattern 9.4 Persistence Ignorance 9.5 Dependency Injection Appendix – [legacy project name] Phase 1 9.6 Bespoke Physical Components 

我个人认为,在定义软件文档时,我认为以下主题很有用:

  • 简介 (文件目标)
  • 上下文图 (应用目的)
  • 硬件要求 (内存和处理器要求)
  • 软件要求 (操作系统,数据库服务器,框架,库)
  • 操作模式 (业务操作,工艺表)
  • 物理架构模型 (物理configuration,服务器,DMZ,防火墙)
  • 应用程序体系结构模型 (应用程序层,服务,组件,UML图)
  • 数据库模型 (UML-PDM;表,Sps,视图,触发器)
  • 安全模型 (authentication,授权,个性化,散列技术)
  • GUI模型 (屏幕,用例图,通用控件)
  • 数据字典 (Excel格式)

看一下这些微软应用程序体系结构的指导性文档

  • 应用程序架构指南2.0
  • .NET的应用程序体系结构:devise应用程序和服务

我的build筑规范的典型成分是:

  • 静态系统结构
    • 概观
    • 组件(每个组件:function,技术,持久性)
    • 接口(内部和外部,机器对机器和用户界面)
  • dynamic行为
    • 业务stream程(即用例)
    • 业务stream程与系统结构的映射(即序列图)
  • 部署
    • 硬件概述
    • networking概述
    • 软件组件映射到硬件

也看看4 + 1模型 。

IEEE根据这些问题有许多标准。 如IEEE 1016,它规定了软件devise描述的组织结构。 http://en.wikipedia.org/wiki/Software_Design_Description

该文件至less应包含以下章节

  1. 介绍
    • devise概述
    • 需求追溯matrix
  2. 系统结构devise
    • select的系统架构
    • 讨论替代devise
    • 系统接口说明
  3. 组件的详细说明
    • 组件n
    • 组件n + 1
  4. 用户界面devise
    • 用户界面的说明
      • 屏幕图像
      • 对象和行动
  5. 其他材料

架构应该以避免集成和维护问题的方式为开发人员提供指导。 更具体地说,体系结构应该识别诸如批准的操作系统,批准的开发语言,批准的数据存储系统,批准的通信协议,编码实践,testing框架,源代码控制,用户接受程序和生产发布程序,关注点分离,维护程序和安全。 在大多数情况下,这是一个活的文件,随着技术的提高,部分被添加和完善。 由于每家公司都是独一无二的,所以指南的副本只会对包含内容的想法有用。 根据别人的反应,你已经有了一些很棒的想法,你可以使用。

“架构规范”将是一个非常有限的术语。 “架构文档”将是正确的术语。

架构师的目标是要有一个系统devise来满足支持主服务器的QoS(服务质量)属性(如可伸缩性,可用性,性能,可靠性,安全性,可扩展性,可维护性,可pipe理性等)的非function性要求(NFR)业务function需求。

您需要logging对您的系统非常重要的QoS属性,以及您为实现这些属性所做的deviseselect。 这个Qos属性是相互关联的,你可能不得不做一些交易,所以你应该提出适当推理的权衡。

为了实现QoS,您将按照分布,层次(层/层),暴露,function,通用性,耦合与凝聚力,易失性,可configuration性等系统性地分解您的系统。这将被视为“体系结构规范”由开发者在系统中实现各种组件。

系统如何部署也会影响QoS。 您将需要loggingnetworking和硬件基础结构以及在该硬件上如何部署应用程序组件。 如何提高系统容量(垂直/水平)或者可以有更多的冗余。

这个讨论:

在RUP中:RUPangular色负责创build软件体系结构文档?

提供了这个模板

http://www.ts.mah.se/RUP/RationalUnifiedProcess/webtmpl/templates/a_and_d/rup_sad.htm

以及RUP中的SAD文档概述:

http://www.ts.mah.se/RUP/RationalUnifiedProcess/process/artifact/ar_sadoc.htm

体系结构规范用于对系统进行高层次的概述。 它有助于开发人员了解系统的全貌,并帮助可视化不同子系统之间的交互。 由于通常架构横跨多个产品版本,所以它应该尽可能地覆盖可维护性和预期需求的灵活性。

我认为确保架构规范中充分涵盖以下主题非常重要

  • 要求
  • 用例
  • 体系结构框图
  • 子系统和接口
  • 安全性/可靠性/可用性
  • testing策略

一个很好的阅读: https : //www.amazon.com/Documenting-Software-Architectures-Views-Beyond/dp/0321552687

您应该将您的架构文档与您的利益相关者(例如开发人员,客户)一起编写。 意见和内容取决于利益相关方的必要条件。 因此,您的体系结构的内容可能因项目而异。